Check-in [9f687b8539]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Starting writing on a "how to" for translation using micca.
Timelines: family | ancestors | descendants | both | micca-develop
Files: files | file ages | folders
SHA1:9f687b8539e5410f71f286438437992ef4004072
User & Date: andrewm 2019-02-17 12:07:31
Context
2019-02-17
17:57
Checkpoint in document on how to translate a model with micca. check-in: 43a8ae7699 user: andrewm tags: micca-develop
12:07
Starting writing on a "how to" for translation using micca. check-in: 9f687b8539 user: andrewm tags: micca-develop
2018-08-17
16:43
Build of micca 1.1.4 for macos. check-in: dc1e858a8e user: andrewm tags: micca-develop
Changes

Changes to micca/code/c/arm-7m/efm32gg/Makefile.

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
	 -Os\
	 -g\
	 -Wall\
	 -mcpu=cortex-m3\
	 -march=armv7-m\
	 -mthumb\
	 $(NULL)
SSTUDIO=/home/andrewm/opt/silabs/SimplicityStudio_v4/developer/sdks/exx32/v5.0.0.0
CPPFLAGS =\
	 -D_ISOC11_SOURCE\
	 -DMRT_SWO_OUTPUT\
	 -I$(SSTUDIO)/platform/CMSIS/Include\
	 -I$(SSTUDIO)/platform/Device/SiliconLabs/EFM32GG/Include\
	 -I$(SSTUDIO)/platform/emlib/inc\
	 -I$(SSTUDIO)/hardware/kit/common/bsp\







|







7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
	 -Os\
	 -g\
	 -Wall\
	 -mcpu=cortex-m3\
	 -march=armv7-m\
	 -mthumb\
	 $(NULL)
SSTUDIO=/home/andrewm/opt/silabs/SimplicityStudio_v4/developer/sdks/gecko_sdk_suite/v2.2
CPPFLAGS =\
	 -D_ISOC11_SOURCE\
	 -DMRT_SWO_OUTPUT\
	 -I$(SSTUDIO)/platform/CMSIS/Include\
	 -I$(SSTUDIO)/platform/Device/SiliconLabs/EFM32GG/Include\
	 -I$(SSTUDIO)/platform/emlib/inc\
	 -I$(SSTUDIO)/hardware/kit/common/bsp\

Added micca/doc/howto/Makefile.



































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
#
#*++
# PROJECT:
#	Tools
# MODULE:
#
# ABSTRACT:
#
#*--
#

vpath %.uxf $(IMAGEDIR)

IMAGEDIR = ./figures

DOCSRC 	=\
	howto.txt\
	$(NULL)

DOCPARTS =\
	intro.txt\
	marking.txt\
	syntax.txt\
	data.txt\
	dynamics.txt\
	processing.txt\
	bridge.txt\
	codeorg.txt\
	$(NULL)

DIAGRAMS =\
	$(NULL)

IMAGES =\
	$(patsubst %.uxf,$(IMAGEDIR)/%.pdf,$(DIAGRAMS))\
	$(NULL)

PDF 	=\
     	$(patsubst %.txt,%.pdf,$(DOCSRC))\
     	$(NULL)

CLEANFILES =\
	$(IMAGES)\
	$(PDF)\
	$(NULL)

A2XOPTS =\
	$(NULL)

#	--verbose


ATANGLEOPTS =\
	$(NULL)

DBLATEX_PARAMS =\
	bibliography.numbered=0\
	index.numbered=0\
	doc.publisher.show=0\
	doc.toc.show=1\
	doc.lot.show=figure,table\
	toc.section.depth=2\
	doc.section.depth=0\
	$(NULL)

# draft.mode=yes
# draft.watermark=1

DOCINFO	=\
	$(patsubst %.txt,%-docinfo.xml,$(DOCSRC))\
	docinfo.xml\
	$(NULL)

EXTRAS =\
	$(DOCINFO)\
	$(NULL)

ASCIIDOC_ATTRS =\
	docinfo2\
	$(NULL)


DBLATEX_OPTS =\
	--dblatex-opts="$(patsubst %,--param=%,$(DBLATEX_PARAMS))"\
	--dblatex-opts="--fig-path=$(IMAGEDIR)"\
	$(NULL)

ASCIIDOC_OPTS =\
	$(patsubst %,--attribute=%,$(ASCIIDOC_ATTRS))\
	$(NULL)

.PHONY : all doc clean

all : doc

doc : $(PDF)

clean :
	$(RM) $(CLEANFILES)

$(PDF) : $(DOCSRC) $(DOCPARTS) $(EXTRAS) $(IMAGES)

%.pdf : %.txt
	a2x $(A2XOPTS) --doctype=article  --format=pdf\
	    $(ASCIIDOC_OPTS) $(DBLATEX_OPTS) $<

%.pdf : %.uxf
	umlet -action=convert -format=pdf\
		-filename=$< -output=$(basename $@)

#
# vim: sw=8 ts=8 sts=8 noexpandtab
#

Added micca/doc/howto/bridge.txt.





















>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
== Bridge code
Bridge code

* instance identification
* semantic mapping
* use of the micca portal
* use of domain operations


// vim:syntax=asciidoc:

Added micca/doc/howto/codeorg.txt.











>
>
>
>
>
1
2
3
4
5
== Code organization
Code organization


// vim:syntax=asciidoc:

Added micca/doc/howto/data.txt.















>
>
>
>
>
>
>
1
2
3
4
5
6
7
== Translating data
Translating data

* data type translation


// vim:syntax=asciidoc:

Added micca/doc/howto/docinfo.xml.



























































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
<authorgroup>
  <author>
    <firstname>Andrew</firstname>
    <surname>Mangogna</surname>
  </author>
</authorgroup>
<copyright>
  <year>2019</year>
  <holder>
      G. Andrew Mangogna
  </holder>
</copyright>
<legalnotice>
  <title>
      Legal Notices and Information
  </title>
  <para>
This document is copyrighted 2019 by G. Andrew Mangogna.
The following terms apply to all files associated with the software unless
explicitly disclaimed in individual files.
  </para>
  <para>
The author hereby grants permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose, provided
that existing copyright notices are retained in all copies and that this
notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses.
Modifications to this software may be copyrighted by their authors and
need not follow the licensing terms described here, provided that the
new terms are clearly indicated on the first page of each file where
they apply.
  </para>
  <para>
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES
THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
  </para>
  <para>
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS,
OR MODIFICATIONS.
  </para>
  <para>
GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only "Restricted Rights"
in the software and related documentation as defined in the Federal
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
are acquiring the software on behalf of the Department of Defense,
the software shall be classified as "Commercial Computer Software"
and the Government shall have only "Restricted Rights" as defined in
Clause 252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing,
the authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license.
  </para>
</legalnotice>

Added micca/doc/howto/dynamics.txt.











>
>
>
>
>
1
2
3
4
5
== Translating dynamics
Translating dynamics


// vim:syntax=asciidoc:

Added micca/doc/howto/howto-docinfo.xml.



























>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
<!--
  article-docinfo.xml
-->
<revhistory>
  <revision>
    <revnumber>0.1</revnumber>
    <date>February 17, 2019</date>
    <authorinitials>GAM</authorinitials>
    <revremark>
      Start of writing.
    </revremark>
  </revision>
</revhistory>

Added micca/doc/howto/howto.txt.









































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
= How to Translate XUML Models using `micca`

include::intro.txt[]

include::marking.txt[]

include::syntax.txt[]

include::data.txt[]

include::dynamics.txt[]

include::processing.txt[]

include::bridge.txt[]

include::codeorg.txt[]


// vim:syntax=asciidoc:

Added micca/doc/howto/intro.txt.

































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
== Introduction

This paper presents a set of techniques to demonstrate
translating an
https://en.wikipedia.org/wiki/Executable_UML[Executable UML (XUML)]
domain model into a "C" based implementation using `micca`.

* overall workflow scheme
* Human driven translation
* available targets
* model first -- don't hack
* analysis vs translation

=== Complete model

Before translation can be begin,
it is necessary to have a complete model.
That seems like an obvious statement,
but in our usual rush to finish systems there is a natural tendency
to start translation before the model is complete.
In the end,
starting with a half-baked model wastes time,
especially if the person performing the translation
(as is our recommendation)
is not the same person who created the model.

The need for a complete model does *not* imply that the
model has to satisfy every possible requirement that could be envisioned
for the domain.
The necessity for the domain model be complete and self-consistent
does *not* necessarily imply that it is complete in terms
of the services it provides to the system.
Experience shows that models,
like conventional code bases,
benefit from incremental, iterative development.
Call it agile or waterfall or whatever you like,
skilled practitioners of software development do not build systems
in one sequential undertaking.
Development is iterative and the results of one iteration help direct
subsequent efforts.
The usual recommendation is to model core concepts that are central
to the subject matter of the domain and work out from there to more
peripheral concepts.
Of course such recommendations have little to offer in terms of how
to determine what the core concepts of a domain are.
Experience shows that domain models, like a conventional code base,
tend to have areas where it is less clear what the _right_ thing is
to do.
Usually, some doubts enter into the process near the domain boundary
and its interactions with other domains.
This seems to be a property of any collection of logic when exceeding a certain
size (which size is almost never exceeded by the simple examples usually
presented).

However,
domain models are precise and therefore don't have _fuzzy_ parts that
left open for interpretation or dangling for future elaboration.
So we consider the following a _minimal_ set of deliverables that
are required before translation can begin.

* A class model of the domain data. The class model must contain:
  - A UML class diagram (in accordance with XUML usage).
  - Written descriptions of each class, relationship and attribute.
    Writing descriptions of the class model elements is an essential
    aspect of creating the class model and the presence of the
    descriptions indicates that the analyst has thoroughly checked
    the implications of the model.
  - A description of each model-level data type employed in the
    class model.
    The description must define the set of values (either by formula
    or enumeration) that constitute the data type.
* A state model for each class that has non-trivial lifecycle behavior.
  The state models contain:
  - A UML state diagram (in accordance with XUML usage).
    The diagram must show the initial state and any final states.
  - A state transition matrix in which every possible transition
    is defined.
    Every transition not shown on the state model diagram must be
    marked as *CH* (can't happen) or *IG* (ignored).
    It is suggested that ignored events be justified as to the reasoning
    behind them.
  - A description of each state and the role it plays in the lifecycle
    of the class.
  - A state activity description of the processing for each state.
    The processing should be described in an unambiguous action language
    or in action data flow diagrams.
* A set of instance operation descriptions for each class
    that defines them, to include:
  - A description of the function and interface of the operation.
  - The processing performed by the operation in terms of action language
    or a data flow diagram.
* A set of domain operation descriptions that include:
  - A written description of the operation function and interface.
  - The processing of the domain operation presented as action language
    or a data flow diagram.
* A set of external entity descriptions that include:
  - A description of the logical dependencies allocated to the external
    entity by the domain.
  - A description of the function and interface for each operation
    performed by the external entity.
    This must include whether the operation is considered as synchronous
    or asynchronous in its behavior.
* An initial instance population of the domain including:
  - Values for every attribute of every instance that is to exist when
    the domain starts.
    The preferred manner of specification is via tabluar layout in a
    purely data oriented fashion.
    Values of referential attributes indicate the relationship instances
    that are part of the initial instance population.
    Using action language to define initial data populations is not
    acceptible.

=== Translation workflow summary

The basic workflow described here for translating an XUML model is:

. Perform an introspection of the model marking it to show the execution
    characteristics.
. Translate the class model.
. Translate the state models.
. Translate the data flow diagrams or action language to "C" code.
. Construct an initial instance population.
. Construct the bridges between domains.

Each of these areas is discussed below.


// vim:syntax=asciidoc:

Added micca/doc/howto/marking.txt.

























































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
== Model marking
Model marking

* marking is analogous to semantic analysis for a language compiler.

* model compiler does not generate the model you should have written.


* mark instance creation/deletion -- both sync and async
* mark attributes as read/written
  - reading/writing of referential attributes
* mark relationships traversed and direction

* mark instance access by attribute values vs. relationship navigation

* elide identifying attributes
  - when you can and when you cannot

* use of class operations

=== Optimizations

* composition of related instances

* generalization relationships union/non-union


// vim:syntax=asciidoc:

Added micca/doc/howto/processing.txt.











>
>
>
>
>
1
2
3
4
5
== Translating processing
Translating processing


// vim:syntax=asciidoc:

Added micca/doc/howto/syntax.txt.











>
>
>
>
>
1
2
3
4
5
== Syntax considerations
Syntax considerations


// vim:syntax=asciidoc: