修訂 | 4a39e9695548b0739e044be977b1a8c1c73eeaff (tree) |
---|---|
時間 | 2023-11-09 00:17:52 |
作者 | Albert Mietus < albert AT mietus DOT nl > |
Commiter | Albert Mietus < albert AT mietus DOT nl > |
more AR docs
@@ -1,4 +1,7 @@ | ||
1 | 1 | .. (C) 2023 Albert Mietus. Part of CCastle project |
2 | + | |
3 | +.. include:: /std/localtoc.irst | |
4 | + | |
2 | 5 | .. _AR_pipeline: |
3 | 6 | |
4 | 7 | ====================== |
@@ -42,6 +45,8 @@ | ||
42 | 45 | The :ref:`mockReader` is different: it does output (needed) ‘`AIGR`’, and so can act as the starts of a |
43 | 46 | pipeline (and therefor considered as a ‘`Reader`’), but has no input. |
44 | 47 | |
48 | +.. uml:: AIGR_Reader.puml | |
49 | + | |
45 | 50 | Some sub-components in the ‘`Reader`’ may also work on the ‘`AIGR`’, as shown. The difference (to a ‘`Translator`’) is |
46 | 51 | simple: the '`Reader'` should do all error-checking, etc, to make sure the inputs (so the code of the developer) is |
47 | 52 | valid. A normal Translator (nor the '`Backend'`) should ever find errors. |
@@ -49,21 +54,117 @@ | ||
49 | 54 | When implementing that (`Reader`) functionality is more convenient as after converting the :ref:`ATS into the AIGR |
50 | 55 | <AST-2-AIGR>` an “AIGR-analyser” is build. |
51 | 56 | |
52 | -.. uml:: AIGR_Reader.puml | |
57 | + | |
53 | 58 | |
54 | 59 | Transformers |
55 | 60 | ============ |
56 | -ToDo | |
61 | + | |
62 | +All ‘`Transformers`’ receive and post (a “dialect” of) the`AIGR`, pushing it into a form that van be handled by the | |
63 | +backend to create an efficient binary. There can be many `Transformers`, and typically several of them are run in | |
64 | +sequence. Other sets of `Transformers` exclude each other. | |
65 | +|BR| | |
66 | +We show two examples. | |
57 | 67 | |
58 | 68 | .. uml:: AIGR_Transformers.puml |
69 | + :align: right | |
70 | + | |
71 | +FSM | |
72 | +--- | |
73 | + | |
74 | +In Castle, one can directly describe a FSM (see: :ref:`FSMs-are-needed`) including advance/extended variants. Like | |
75 | +the non-deterministic “NFA”s, and the “State-Charts” (known from UML), with orthogonale regions and hierarchically | |
76 | +‘superstates’. See :need:`U_FSM_Syntax` for the demands. | |
77 | +|BR| | |
78 | +Those FSM are initially stored “asis” in the AIGR, and step-by-step rewritten by several FSM-Transformers. | |
79 | + | |
80 | +The ``FSM.NFA_2_FSM`` Transformer reworks a NFA into a (bigger, deterministic) FSM. This is a well know algorithm, such | |
81 | +that non-deterministic edges and epsilon-transitions are gone. | |
82 | +|BR| | |
83 | +The resulting `AIGR` has the same functionality, but is simpler to translate into a binary | |
84 | + | |
85 | +Similarly, the ``FSM.SuperStates`` Transformer can “flatten” complex hierarchical FSM’s into ones that are easier to | |
86 | +translate into executable code. | |
87 | + | |
88 | +This is an examples of set of `Transformers` that can work collectively. First, remove the non-determinisms, then handle | |
89 | +the SuperStates and completely transformer the (simple) FSM into regulair routines. | |
90 | + | |
91 | +Machinery | |
92 | +--------- | |
93 | +.. caution:: | |
94 | + :class: clear-none | |
95 | + | |
96 | + The Machinery part is still in development. And so, it’s **not** sure that the Machinery will be implemented as a | |
97 | + `Transformer`! | |
98 | + | |
99 | +‘:ref:`TheMachinery`’ is an abstraction of the technology to connect ports and send data (like events) over | |
100 | +them. Several implementations are possible, like direct function-calls, dispatching to concurent thread-pools, or | |
101 | +distributing them over a network. | |
102 | + | |
103 | +Typically, one wil only use one Machinery: connecting two port with DDS, ‘sending’ an event by dispatching it whereas | |
104 | +the receiving event-handler expect a traditional call, will not work. By choosing one Machinery-Transformer, all | |
105 | +bolt-and nuts will fit. | |
106 | + | |
107 | +.. caution:: This is not an requirement | |
108 | + | |
109 | + One can imagine, that (eventually) a Mixed-Machinery is used. Ultimately, only the details of each (individual) | |
110 | + connection should be aligned. | |
111 | + | |
112 | + .. admonition:: Advanced example | |
113 | + | |
114 | + The *Machinery-kind* can be seen an attribute of the (super)component that holds the connections (and | |
115 | + sub-component, with ports). By using that Machinery for those connections, it will work. | |
116 | + |BR| | |
117 | + But the (external) ports and connections of that super(component) can use another Machinery; when the | |
118 | + supper-super-component’s machinery-kind attribute has another value. | |
119 | + | |
120 | + Again, this makes it complicated. But it gives flexibility: for deep-down connections we might prefer direct | |
121 | + calls, but use concurent options at a (bit) higher level. And use maximal decoupling for networking-applications. | |
122 | + | |
123 | + .. note:: | |
124 | + | |
125 | + Here, we see an example of having the “connected/concurent components” abstraction and | |
126 | + ‘:ref:`TheMachinery`’ abstraction. | |
127 | + | |
128 | + The CCastle code, use “components, ports and connections” only. Later, we compiling it, the details of the | |
129 | + Machinery are added. | |
130 | + |BR| | |
131 | + And by implementing it in/as a `Transformer` we can add more-and-more advanced options without the need to change | |
132 | + the source. Only some (global) “compiler options” have to be improved. | |
133 | + (many) sor | |
59 | 134 | |
60 | 135 | |
61 | -Writers (in the backend) | |
62 | -======================== | |
63 | -ToDo | |
136 | +Writers & Backends | |
137 | +================== | |
138 | + | |
139 | +The ‘`Backends`’ read the (simplified & optimised) `AIGR` and transform it to a binary that can be executed. Typically | |
140 | +this is a two-step approach: A ‘`Writer`’ renders the `AIGR` into a low-level intermediate [#intermediate]_ language [#lll-ex]_ | |
141 | + | |
142 | +The interface between the ‘`Writer`’ and the ‘Translator’ is typically file-based, and depend heavily on the chosesn | |
143 | +‘Translator’ -- which is not part of CCastle. | |
144 | +|BR| | |
145 | +As those two are very depending on each other, there is little commonality between various `Backend` variants. | |
146 | + | |
147 | +Some examples | |
148 | + | |
149 | +* The :ref:`RPy` backend/writer renders to RPython, such that (PyY’s) rpython-translator can handle it. The intermediate | |
150 | + file-format is fully described by RPython: the :ref:`RPy` `Writer` needs to emit exactly that format. | |
151 | +* **CC2Cpy** (now defunct [#CC2Cpy-not-AIGR]_) generates standard C code, that can be translated into binaries by many | |
152 | + (standard, C) compilers. So, it’s a bit more generic (then **RPy**), but still the writer is limited to C -- and so | |
153 | + has to *emulate* namespaces, as that isn’t handled in C | |
154 | + |BR| | |
155 | + A possible variant is using C++, both as lll and translator (but as I’m not a a fan of it, somebody else has to make | |
156 | + it | |
157 | +* Both mentioned writers are implemented in python, for now (that is the ‘py’ part of CC2Cpy). | |
158 | + |BR| | |
159 | + Future variants of those `Writers` will be implemented in Castle itself. This does not change the input (`AIGR`) not | |
160 | + the output of the `Writers` (rpython and C). And such we can use easily upgrade the `Backend` as the `Translator` does | |
161 | + not change. | |
162 | + | |
64 | 163 | |
65 | 164 | .. _AIGR_component: |
66 | 165 | |
166 | + | |
167 | + | |
67 | 168 | The AIGR auxiliary component |
68 | 169 | ============================ |
69 | 170 | ToDo |
@@ -78,3 +179,32 @@ | ||
78 | 179 | |
79 | 180 | .. [#pickle] |
80 | 181 | This can be done by *pickling* in python, or using an XML format, or ... |
182 | + | |
183 | +.. [#intermediate] | |
184 | + We call this low-level-language “intermediate”, as the user shouldn't care about it. And consider it as an internal | |
185 | + detail of the `Backend`. | |
186 | + |BR| | |
187 | + Note however, other tools/environments may speak about the *“Generaring to XXX-language ...”*, which is then | |
188 | + compiled in the normal way. (one may hope, the ‘generated source’ isn’t edited anymore, as old tools did allow). | |
189 | + | |
190 | + Aside of terms, it’s the same! | |
191 | + | |
192 | + .. XXX The hint below overlaps a bit. The |BR| hack is a workaround | |
193 | + | |
194 | + |BR| | |
195 | + | |
196 | + .. hint:: Generating (e.g.) C-code *sounds* like it is needed to intergrade existing code. | |
197 | + |BR| | |
198 | + That is an outdated view however. | |
199 | + | |
200 | + Nowadays all modern languages support a ‘FFI’ (`Foreign Function Interface | |
201 | + <https://en.wikipedia.org/wiki/Foreign_function_interface>`__). Castle will support that to. | |
202 | + | |
203 | +.. [#lll-ex] | |
204 | + A well know example of such low-level-languages is C, or C++. But also RPython --which translate to C, first and | |
205 | + then that an executable-- is can also be used. | |
206 | + Other options are the ‘LLVM-IM’ and so use the LLVM (known from e.g. CLang) backend as Transformer | |
207 | + | |
208 | +.. [#CC2Cpy-not-AIGR] | |
209 | + Notice, the current CC2Cpy module isn’t using the AIGR, and a therefore not a Writer. However, an upcomming version | |
210 | + of it may use the AIGR as interface, making it true `Writer` and a good example. |
@@ -1,7 +1,8 @@ | ||
1 | 1 | @startuml |
2 | 2 | skin rose |
3 | -!include AR_skins.inc | |
3 | +'!include AR_skins.inc | |
4 | 4 | left to right direction |
5 | +scale 0.5 | |
5 | 6 | |
6 | 7 | ''NOTE: Old RTD/plantuml.1.2020.2.jar syntax! |
7 | 8 |
@@ -23,11 +24,18 @@ | ||
23 | 24 | frame "CCastle Compiler" as CCC #c0c0c0 { |
24 | 25 | folder Transformers #white { |
25 | 26 | package FSM { |
26 | - $comp("FSM.SuperStates") | |
27 | 27 | $comp("FSM.NFA_2_FSM") |
28 | - $comp("FSM.Epsilon") | |
28 | + $comp("FSM.SuperStates") | |
29 | +' $comp("FSM.Epsilon") | |
29 | 30 | $comp("FSM_2_Routine") |
30 | - $comp("FSM....") | |
31 | + } | |
32 | + package Machinery { | |
33 | + $comp("DirectCall") | |
34 | + $comp("LibDispatch") | |
35 | + $comp("DDS") | |
36 | + } | |
37 | + package "more ..." as m { | |
38 | + $comp("...") | |
31 | 39 | } |
32 | 40 | } |
33 | 41 | } |