Return to posy.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/posy.tex, revision 1.1

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.