![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to posy.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual|
Return to posy.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual |
1.1 root 1: % run this through LaTeX with the appropriate wrapper
2:
3: \chapter {Pepy Optional Structure-Generator}\label{posy}
4: The \man posy(1) program is a compiler for specifications of abstract
5: syntaxes.
6:
7: For those interested in trivia,
8: \pgm{posy} stands for
9: \underbar{P}epy
10: \underbar{O}ptional
11: \underbar{S}tructure-generator
12: (\underbar{Y}ACC-based).
13: The \man pepy(1) program is an ASN.1 compiler,
14: and the \man yacc(1) program,
15: of course,
16: is a compiler-compiler.
17:
18: \section {Abstract Syntax Module}
19: The \pgm{posy} program reads a description of an {\em abstract syntax
20: module\/}
21: and produces the corresponding {\em C\/} structures along with an augmented
22: abstract syntax module.
23:
24: The syntax of the input file corresponds almost exactly to the notation
25: described in \cite{ISO.PP.Syntax,CCITT.PP.Syntax}.
26: (But see Section~\ref{posy:deficiencies} on page~\pageref{posy:deficiencies}
27: for the details.)
28: As the ASN.1 language is rich in its notation,
29: the rules are not presented herein,
30: though Section~\ref{asn1:notation} on page~\pageref{asn1:notation} of \volone/
31: presents an incomplete treatment of the less substantive aspects of the
32: language.
33:
34: An example of a complete abstract syntax module can be found in
35: Figure~\ref{POSexample} starting on page~\pageref{POSexample}.
36: This corresponds to the output produced by \man rosy(1) when given
37: the remote operations module in Figure~\ref{ROSexample} as input.
38:
39: For our purposes,
40: the input file is relatively unimportant as it is usually generated by the
41: \pgm{rosy} program.
42: Hence,
43: the output from \pgm{posy} is where this chapter focuses.
44:
45: \newpage
46: \tagrindfile{grindposy-1}{Example of an Abstract Syntax Module}{POSexample}
47: \newpage
48:
49: \section {POSY Environment}
50: The \pgm{posy} program will produce two files after reading its abstract
51: syntax module.
52:
53: \subsection {C Language Structures}\label{posy:c-struct}
54: For each type in the abstract syntax module,
55: \pgm{posy} will define a corresponding {\em C\/} language structure
56: (\verb"struct").
57:
58: The rules that \pgm{posy} uses to generate the structures are fairly simple:
59: \begin{describe}
60: \item [\verb"BOOLEAN":] represented as a \verb"char".
61:
62: \item [\verb"INTEGER":] represented as an \verb"int".
63: If the \verb"INTEGER" type has a list of tagged values,
64: then for each value:
65: \begin{quote}\small\begin{verbatim}
66: #define int_MODULE_TYPE_TAG value
67: \end{verbatim}\end{quote}
68: as in:
69: \begin{quote}\small\begin{verbatim}
70: #define int_IMAGE_IntList_zero 0
71: \end{verbatim}\end{quote}
72:
73: \item [\verb"BIT STRING":] represented as a \verb"struct PElement"
74: (these are described in Section~\ref{psap:bits} of \volone/).
75: If the \verb"BIT STRING" type has a list of tagged bits,
76: then for each bit:
77: \begin{quote}\small\begin{verbatim}
78: #define bit_MODULE_TYPE_TAG value
79: \end{verbatim}\end{quote}
80: as in:
81: \begin{quote}\small\begin{verbatim}
82: #define bit_IMAGE_Version_version__1 0
83: \end{verbatim}\end{quote}
84: In addition, one other definition is present:
85: \begin{quote}\small\begin{verbatim}
86: #define bits_MODULE_TYPE string
87: \end{verbatim}\end{quote}
88: as in:
89: \begin{quote}\small\begin{verbatim}
90: #define bits_IMAGE_Version "\020\01version-1"
91: \end{verbatim}\end{quote}
92:
93: \item [\verb"OCTET STRING":] represented as a \verb"struct qbuf"
94: (these are described in Section~\ref{psap:qbuf} of \volone/
95: and Section~\ref{tsap:qbuf} of \voltwo/).
96:
97: \item [\verb"REAL":] represented as a \verb"double".
98:
99: \item [\verb"NULL":] represented as a \verb"char".
100:
101: \item [\verb"SEQUENCE"/\verb"SET"/\verb"ANY":]
102: represented as a \verb"struct PElement"
103: (which are described throughout Chapter~\ref{libpsap} of \volone/).
104: This format is used for those \verb"SEQUENCE"s or \verb"SET"s which
105: contain no elements.
106:
107: \item [\verb"SEQUENCE OF"/\verb"SET OF":]
108: by default, represented as a \verb"struct" with two elements,
109: a linked-list.
110: The first element is the type for set or sequence,
111: the second element is a pointer to another instance of the structure.
112: For example:
113: \begin{quote}\small\begin{verbatim}
114: SEQUENCE OF
115: Format
116: \end{verbatim}\end{quote}
117: might be translated as:
118: \begin{quote}\small\begin{verbatim}
119: struct element_IMAGE_4 {
120: struct type_IMAGE_Format *Format;
121:
122: struct element_IMAGE_4 *next;
123: };
124: \end{verbatim}\end{quote}
125: By using the \switch"h2" option (described below),
126: an array structure can be generated instead.
127:
128: \item [\verb"SEQUENCE"/\verb"SET":] represented as a simple \verb"struct"
129: with an element for each member.
130: For example:
131: \begin{quote}\small\begin{verbatim}
132: Mail-Address ::= SEQUENCE {
133: local[0]
134: IMPLICIT GraphicString,
135:
136: domain[1]
137: IMPLICIT GraphicString,
138:
139: options[2]
140: IMPLICIT BITSTRING
141: }
142: \end{verbatim}\end{quote}
143: might be translated as:
144: \begin{quote}\small\begin{verbatim}
145: struct type_IMAGE_Mail__Address {
146: struct type_UNIV_GraphicString *local;
147:
148: struct type_UNIV_GraphicString *domain;
149:
150: PE options;
151: };
152: \end{verbatim}\end{quote}
153:
154: \item [\verb"CHOICE":] represented as a \verb"struct" containing an
155: \verb"int" and a \verb"union".
156: \begin{quote}\small\begin{verbatim}
157: CHOICE {
158: file-name[0]
159: IMPLICIT Filename,
160:
161: mail-address[1]
162: IMPLICIT Mail-Address
163: }
164: \end{verbatim}\end{quote}
165: might be translated as:
166: \begin{quote}\small\begin{verbatim}
167: struct choice_IMAGE_0 {
168: int offset;
169: #define choice_IMAGE_0_file__name 1
170: #define choice_IMAGE_0_mail__address 2
171:
172: union {
173: struct type_IMAGE_Filename *file__name;
174:
175: struct type_IMAGE_Mail__Address *mail__address;
176: } un;
177: };
178: \end{verbatim}\end{quote}
179:
180: \item [\verb"OBJECT IDENTIFIER":] represented as a \verb"struct OIDentifier"
181: (these are described in Section~\ref{psap:oid} of \volone/).
182:
183: \item [\verb"MODULE.TYPE":] represented as a pointer to a
184: \verb"struct" \verb"type_MODULE_TYPE".
185: \end{describe}
186:
187: Although these rules might seem complicated,
188: in point of fact they are actually very straight-forward and regular.
189: The easiest way to gain familiarity with them is to run some abstract syntax
190: modules through \pgm{posy} and then view the resulting definitions.
191: Figure~\ref{CStructs} starting on page~\pageref{CStructs} presents the
192: {\em C\/} language structures corresponding to the abstract syntax module in
193: Figure~\ref{POSexample}.
194:
195: \subsubsection {Controlling the names that POSY generates}
196: One of the least friendly aspects of \pgm{posy} is the algorithm
197: it uses for choosing the names of {\em C\/} language structures being
198: generated.
199: The rules for choosing some names are fixed,
200: i.e., the top-level name generated for an ASN.1 type can not be changed.
201: However,
202: the names used for the parts of the \verb"struct"s generated by \pgm{posy} can
203: be controlled~---~to an extent using either (or both) of two techniques.
204:
205: The first method takes advantage of the observation that \pgm{posy} uses
206: commentary tags in the ASN.1 definition, whenever possible, as variable names.
207: To revisit an earlier example:
208: \begin{quote}\small\begin{verbatim}
209: Mail-Address ::= SEQUENCE {
210: local[0]
211: IMPLICIT GraphicString,
212:
213: domain[1]
214: IMPLICIT GraphicString,
215:
216: options[2]
217: IMPLICIT BITSTRING
218: }
219: \end{verbatim}\end{quote}
220: might be translated as:
221: \begin{quote}\small\begin{verbatim}
222: struct type_IMAGE_Mail__Address {
223: struct type_UNIV_GraphicString *local;
224:
225: struct type_UNIV_GraphicString *domain;
226:
227: PE options;
228: };
229: \end{verbatim}\end{quote}
230: In each case, the names of the variables (e.g., \verb"local") were taken from
231: the commentary tag.
232: Note that if no tag is present,
233: \pgm{posy} must choose a name in a different fashion.
234: Hence,
235: the first level of control is to simply add short, descriptive commentary tags
236: to the remote operations module (the \pgm{rosy} program will preserve the
237: ASN.1 when it generates an abstract syntax module.
238:
239: The second method is to augment the remote operations module with the
240: \verb"%[ ... %]" construct.
241: This construct allows the user to select both the name used for
242: intermediate structures that are generated and the name used for the
243: corresponding variable in certain cases.
244: Consider:
245: \begin{quote}\small\begin{verbatim}
246: ReadImage-INV ::= SEQUENCE {
247: ...
248:
249: SEQUENCE OF %[ format_list $ head %]
250: FORMAT
251:
252: ...
253: }
254: \end{verbatim}\end{quote}
255: might be translated as:
256: \begin{quote}\small\begin{verbatim}
257: struct type_IMAGE_ReadImage__INV {
258: ...
259:
260: struct format_list {
261: struct type_IMAGE_Format *element_IMAGE_4;
262:
263: struct format_list *next;
264: } *head;
265:
266: ...
267: };
268: \end{verbatim}\end{quote}
269: More formally,
270: the
271: \begin{quote}\small\begin{verbatim}
272: %[ structure-name $ variable-name %]
273: \end{verbatim}\end{quote}
274: construct can be used to control the names used when generating intermediate
275: structures.
276: The construct can be used with any of these ASN.1 constructs:
277: \begin{itemize}
278: \item \verb"SEQUENCE %[ ... %]"
279: \item \verb"SEQUENCE OF %[ ... %]"
280: \item \verb"SEQUENCE %[ ... %] { ... }"
281: \item \verb"SET %[ ... %]"
282: \item \verb"SET OF %[ ... %]"
283: \item \verb"SET %[ ... %] { ... }"
284: \item \verb"CHOICE %[ ... %] { ... }"
285: \end{itemize}
286: If the \verb"$ variable-name" portion of the construct is missing,
287: then only the structure name is taken from the construct,
288: the name of the corresponding variable is generated in the usual fashion.
289:
290: NOTE: This facility is only allowed in the use of nested constructs. It is
291: not possible to override the names chosen for the top level constructs as
292: this would break the inheritence of structures names from other modules.
293: E.g.
294: \begin{quote}\small\begin{verbatim}
295: Defn ::= SEQUENCE %[ ... %] { ...
296: \end{verbatim}\end{quote}
297: is not supported but
298: \begin{quote}\small\begin{verbatim}
299: Defn ::= SEQUENCE {
300: SEQUENCE OF %[ ... %] Thing,
301: ...
302: \end{verbatim}\end{quote}
303: is.
304:
305: \subsection {Augmented Abstract Syntax Module}
306: In addition to the definition of {\em C\/} language structures,
307: \pgm{posy} will prepare an augmented abstract syntax module for use with the
308: \man pepy(1) program.
309: With this augmented module,
310: \pgm{pepy} will generate {\em C\/} code to translate {\em C\/} structures to
311: and from their corresponding abstract syntax.
312: As this is entirely an automatic process,
313: the contents of the augmented abstract syntax module are relatively
314: unimportant.
315:
316: \newpage
317: \tagrindfile{grindposy-2}{Example of C Language Structures}{CStructs}
318: \newpage
319:
320: \section {Known Deficiences}\label{posy:deficiencies}
321: \pgm{posy} uses essentially the same front-end as the \man pepy(1) program,
322: so it has some limitations in the ASN.1 syntax it can accept.
323: Consult Section~\ref{pepy:syntax} for the details.
324:
325: When generating the augmented abstract syntax module for \pgm{pepy},
326: \pgm{posy} has a well-defined set of rules.
327: There are, however, some aspects which are still incomplete or subject to
328: change:
329: \begin{itemize}
330: \item On determining if an \verb"OPTIONAL" element is present,
331: for elements represented by a pointer (e.g., an \verb"OCTET STRING"
332: and its corresponding \verb"struct qbuf" pointer),
333: if the pointer is non-\verb"NULL" (non-zero valued),
334: then the element is considered to be present.
335:
336: \item For elements which are represented by a scalar and not a pointer
337: (e.g., an \verb"INTEGER" and its corresponding \verb"int"),
338: an additional element, \verb"optionals", is created in the
339: structure. This is a
340: bitmask value, with each bit indicating whether a particular
341: element is present or not. So for optional element, a test is
342: first required to see if this element is really present. e.g.,
343: \begin{quote}\small\begin{verbatim}
344: if (element -> optionals & opt_element_member1)
345: /* process element -> member1 */
346: \end{verbatim}\end{quote}
347:
348: \end{itemize}
349:
350: \section {Running POSY}
351: Here are a few things to know when running \pgm{posy}.
352:
353: \subsection {Options}\label{posy:options}
354: The \pgm{posy} program has a few options to modify its behavior.
355:
356: The \switch"a" switch directs \pgm{posy} to augment the \verb"#include" file
357: it generates with commentary text.
358:
359: Normally, \pgm{posy} ignores all \pgm{pepy}-style augmentations except the
360: ``verbatim'' actions occuring at the very beginning and end of the module.
361: The \switch"d" switch directs \pgm{posy} to ignore the verbatim actions as
362: well.
363:
364: The \switch"f" switch directs \pgm{posy} to generate {\em C\/} routines to
365: deallocate the structures it defines
366: (e.g., for type \verb"type_MODULE_type",
367: a routine called \verb"free_MODULE_type" is defined).
368: These are appended to the augmented module definition
369: (as a consequence,
370: use of the \switch"f" switch forces use of the \switch"d" switch).
371:
372: The \switch"h" switch enables additional heuristics when \pgm{posy} generates
373: a {\em C\/} language structure definition.
374: These heuristics are used to make the \verb"struct"s more concise.
375: For example,
376: compare the definitions in Figure~\ref{CStructs} with those in
377: Figure~\ref{H0Structs} starting on page~\pageref{H0Structs}.
378: Both were derived from the abstract syntax module in Figure~\ref{POSexample},
379: but the definitions in Figure~\ref{H0Structs} was generated using the
380: \switch"h0" switch.
381: The current wisdom is that use of the \switch"h0" switch is a good thing.
382: Enabling any other option also results in enabling option \switch"h0".
383:
384: The \switch"h1" switch
385: enables ``clever'' but non-unique structure naming.
386: Use of the \switch"h1" switch is {\bf not\/} recommended.
387:
388: The \switch"h2" switch enables the generation of arrays rather than
389: linked-lists whenever possible.
390: For example,
391: compare the definitions in Figure~\ref{CStructs} with the fragment in
392: Figure~\ref{H2Structs} on page~\pageref{H2Structs}.
393: Both were derived from the abstract syntax module in Figure~\ref{POSexample},
394: but the fragment in Figure~\ref{H2Structs} was generated using the
395: \switch"h2" switch.
396: The current wisdom makes no pronouncement as to whether the \switch"h2" switch
397: is a good thing: some people prefer linked-lists, others perfer arrays.
398:
399: The \switch"o" switch sets the name of the output file.
400: If this switch is not specified,
401: the standard output is used
402: (\pgm{posy} can not derive the name of the output file from the input file
403: since both should have extension \verb".py").
404:
405: Normally, \pgm{posy} prints the name of each type as it works.
406: The \switch"s" switch disables this behavior.
407:
408: \subsection {Makefiles}\label{posy:make}
409: By convention,
410: input files to \pgm{posy} have the extension \verb".py".
411: This causes something of a problem with \man make(1) as the augmented
412: abstract syntax module which \pgm{posy} outputs should also have an extension
413: of \verb"py".
414:
415: Since \pgm{posy} can not intuit the name of the output file from the input
416: file,
417: rather than starting with file \verb"module.py",
418: we assume we are starting with file \verb"MODULE-asn.py".
419: (Hence the reason for the complexity in Section~\ref{rosy:make}.)
420: Let us arbitrarily select the file named \verb"MODULE-types.py" for the
421: augmented abstract syntax module produced by \pgm{posy}.
422: Hence
423: \begin{quote}\begin{verbatim}
424: posy -o MODULE-types.py MODULE-asn.py
425: \end{verbatim}\end{quote}
426: will produce:
427: \begin{describe}
428: \item[\verb"MODULE-types.py":] the augmented abstract syntax module;
429: and,
430:
431: \item[\verb"MODULE-types.h":] the {\em C\/} language structures.
432: \end{describe}
433:
434: Our \man make(1) rules are:
435: \begin{quote}\small\begin{verbatim}
436: MODULE-types.py: MODULE-asn.py
437: posy $(POFLAGS) -o $@ MODULE-asn.rpy
438: MODULE-types.h: MODULE-types.py
439: \end{verbatim}\end{quote}
440: Usually \verb"POFLAGS" is set to ``\verb"-f -h"''.
441:
442: In our particular discipline,
443: we will generate two sets of files:
444: one for the invoker and the other for the performer.
445: \begin{quote}\small\begin{verbatim}
446: MODULE-Rtypes.c: MODULE-types.py
447: pepy -a PY_advise $(PYFLAGS) -o $@ MODULE-types.py
448:
449: MODULE-Itypes.c: MODULE-types.py
450: pepy $(PYFLAGS) -o $@ MODULE-types.py
451: \end{verbatim}\end{quote}
452:
453: \newpage
454: \tagrindfile{grindposy-3}{Example of C Language Structures (with -h0)}%
455: {H0Structs}
456:
457: \newpage
458: \tagrindfile{grindposy-4}{Example of C Language Structures (with -h2)}%
459: {H2Structs}
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.