![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rosy.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 rosy.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 {Remote Operations Stub-Generator}\label{rosy}
4: The \man rosy(1) program is a compiler for specifications of remote operations.
5:
6: For those interested in trivia,
7: \pgm{rosy} stands for
8: \underbar{R}emote
9: \underbar{O}perations
10: \underbar{S}tub-generator
11: (\underbar{Y}ACC-based).
12: The \man yacc(1) program,
13: of course,
14: is a compiler-compiler.
15:
16: \section {Remote Operations Module}
17: The \pgm{rosy} program reads a description of a {\em remote operations
18: module\/}
19: and produces the corresponding {\em C\/} stubs and definitions for use with
20: the run-time environment provided by the \man librosy(3n) library.
21: The syntax of the input file corresponds almost exactly to the remote
22: operations notation described in any of the references found in
23: Section~\ref{ros:reading} on page~\pageref{ros:reading} of \volone/.
24: (But see Section~\ref{rosy:deficiencies} on page~\pageref{rosy:deficiencies}
25: for the details.)
26: In short, three kinds of objects are defined:
27: {\em operations}, {\em errors}, and {\em types}.
28:
29: An example of a complete remote operations module can be found in
30: Figure~\ref{ROSexample} starting on page~\pageref{ROSexample}.
31: For now,
32: let's briefly consider the three individual objects.
33:
34: \subsection {Operation Definitions}
35: Operations are defined by a name which starts with a lowercase character
36: followed by the keyword \verb"OPERATION".
37: Following this are optional definitions for the operation:
38: \begin{describe}
39: \item[\verb"ARGUMENT":] defines the ASN.1 type which the operation expects
40: as its argument;
41:
42: \item[\verb"RESULTS":] defines the ASN.1 type which the operation returns
43: on success;
44: and,
45:
46: \item[\verb"ERRORS":] defines the errors which the operation can return on
47: failure.
48: \end{describe}
49: These optional definitions must occur in the order presented here.
50: Following any optional definitions,
51: the lexeme ``\verb"::="'' follows with an integer which uniquely identifies the
52: operation in the module.
53: By convention, the integer,
54: termed the {\em operation code},
55: should be non-negative.
56:
57: \subsection {Error Definitions}
58: Errors are defined by a name which starts with a lowercase character
59: followed by the keyword \verb"ERROR".
60: Following this are optional definitions for the operation:
61: \begin{describe}
62: \item[\verb"PARAMETER":]defines the ASN.1 type which the error returns
63: when it occurs.
64: \end{describe}
65: Following any optional definitions,
66: the lexeme ``\verb"::="'' follows with an integer which uniquely identifies the
67: error in the module.
68: By convention, the integer,
69: termed the {\em error code},
70: should be non-negative.
71:
72: \subsection {Type Definitions}
73: Types are defined by a name which starts with an uppercase character
74: followed by the lexeme ``\verb"::="'' and then an ASN.1 type definition.
75: As the ASN.1 language is rich in its notation,
76: the rules are not presented herein.
77: The reader should consult \cite{ISO.PP.Syntax,CCITT.PP.Syntax} for the full
78: details,
79: though Section~\ref{asn1:notation} on page~\pageref{asn1:notation} of \volone/
80: presents an incomplete treatment of the less substantive aspects of the
81: language.
82:
83: \newpage
84: \tagrindfile{grindimage-1}{Example of a Remote Operations Module}{ROSexample}
85: \newpage
86:
87: \section {ROSY Environment}
88: The \pgm{rosy} program will produce several files after reading its remote
89: operations module.
90:
91: \subsection {Abstract Syntax Module}
92: The abstract syntax module produced by \pgm{rosy} is simply a copy of the
93: type definitions found in the remote operations module.
94: In addition,
95: \pgm{rosy} may define a few new types based on the definitions used in the
96: operations and errors.
97:
98: \subsection {C Language Stubs}
99: Three separate stub files are produced by \pgm{rosy}.
100:
101: The first is a {\em C\/} pre-processor file containing definitions of:
102: \begin{itemize}
103: \item each operation code
104: \begin{quote}\small\begin{verbatim}
105: #define operation_MODULE_OPNAME OPCODE
106: \end{verbatim}\end{quote}
107: as in:
108: \begin{quote}\small\begin{verbatim}
109: #define operation_IMAGE_initialize 1
110: \end{verbatim}\end{quote}
111:
112: \item each error code
113: \begin{quote}\small\begin{verbatim}
114: #define error_MODULE_ERNAME ERRCODE
115: \end{verbatim}
116: \end{quote}
117: as in:
118: \begin{quote}\small\begin{verbatim}
119: #define error_IMAGE_congested 1
120: \end{verbatim}
121: \end{quote}
122:
123: \item stub routines
124: \begin{quote}\small\begin{verbatim}
125: #define op_MODULE_OPNAME(sd,in,out,rsp,roi) \
126: RyOperation ( ... )
127: \end{verbatim}\end{quote}
128: as in:
129: \begin{quote}\small\begin{verbatim}
130: #define op_IMAGE_initialize(sd,in,out,rsp,roi) \
131: RyOperation ( ... )
132: \end{verbatim}\end{quote}
133: \end{itemize}
134: The stub routines require a lot more explanation.
135: Rather than introduce the full details,
136: for the moment simply note that the stub routines are actually calls to the
137: \verb"RyOperation" routine discussed in Chapter~\ref{librosy} which
138: ``does all the work''.
139:
140: The second file produced by \pgm{rosy} defines the {\em C\/} language
141: data structures used by the run-time environment which the \man librosy(3n)
142: library provides.
143:
144: The third file produced by \pgm{rosy} is used in conjunction with \man lint(1).
145: It defines as routines, rather than macros, the same stub routines found in
146: the {\em C\/} pre-processor file.
147: These routines permit more stringent argument checking.
148:
149: \section {Known Deficiences}\label{rosy:deficiencies}
150: The \pgm{rosy} program is a prototype.
151: It probably won't undergo substantive change,
152: but experience will tell.
153:
154: In particular,
155: \pgm{rosy} uses essentially the same front-end as the \man pepy(1) program,
156: so it has some limitations in the ASN.1 syntax it can accept.
157: Consult Section~\ref{pepy:syntax} for the details.
158:
159: The \verb"BIND" and \verb"UNBIND" macros are currently unrecognized,
160: along with the newer (\verb"OBJECT" \verb"IDENTIFIER") notation for operation
161: codes.
162:
163: The \verb"LINKED" clause is currently recognized but otherwise ignored
164: for the \verb"OPERATION" macro.
165:
166: \section {Running ROSY}
167: Here are a few things to know when running \pgm{rosy}.
168:
169: \subsection {Options}
170: The \pgm{rosy} program has a few options to modify its behavior.
171:
172: The \switch"b" switch sets the prefix used for the output file.
173: If this option is not given,
174: the ASN.1 module name is used.
175:
176: The \switch"d" switch directs \pgm{rosy} to ignore any \pgm{pepy}-style
177: augmentations.
178:
179: The \switch"o" switch sets the name of the output file,
180: which is normally derived from the name of the input file.
181: The distinguished file ``\verb"-"'' can be used to force the use of the
182: standard output.
183:
184: Normally, \pgm{rosy} prints the name of each operation, error, or type
185: as it works.
186: The \switch"s" switch disables this behavior.
187:
188: The \switch"pepsy" switch tells \pgm{rosy} that you will be using
189: \pgm{pepsy} rather than \pgm{posy}.
190: The \pgm{pepsy} program is dscribed in Chapter~\ref{pepsy} starting on
191: page~\pageref{pepsy}.
192:
193: \subsection {Makefiles}\label{rosy:make}
194: By convention,
195: input files to \pgm{rosy} have the extension \verb".ry".
196:
197: Consider the file \verb"module.ry" which defines the module \verb"MODULE".
198: The name of the abstract syntax module produced by \pgm{rosy} is normally
199: derived from the name of the input file, using an extension of \verb".py".
200: The name of the {\em C\/} language stub files is derived from the name of the
201: module defined in the input file.
202: Hence
203: \begin{quote}\begin{verbatim}
204: rosy module.ry
205: \end{verbatim}\end{quote}
206: will produce:
207: \begin{describe}
208: \item[\verb"module.py":] the abstract syntax module;
209:
210: \item[\verb"MODULE-ops.h":] operation definitions and stubs;
211:
212: \item[\verb"MODULE-ops.c":] data structures for \man librosy(3n);
213: and,
214:
215: \item[\verb"MODULE-stubs.c":] stub definitions for \man lint(1)
216: \end{describe}
217:
218: Intuitively, one would suspect that the the rules for \man make(1) should take
219: advantage of the \verb".ry" and \verb".py" suffix relationship for a rule
220: like:
221: \begin{quote}\small\begin{verbatim}
222: .ry.py:; rosy $(RYFLAGS) $<
223: \end{verbatim}\end{quote}
224: For reasons explained later on
225: (in Section~\ref{posy:make} on page~\pageref{posy:make}),
226: it is advantageous to use a more complicated set of rules:
227: \begin{quote}\small\begin{verbatim}
228: MODULE-asn.py: module.ry
229: rosy $(RYFLAGS) -o $@ module.ry
230: MODULE-ops.c: module.ry
231: MODULE-ops.h: module.ry
232: MODULE-stubs.c: module.ry
233: \end{verbatim}\end{quote}
234: Usually \verb"RYFLAGS" is empty.
235:
236: In our particular discipline,
237: we will generate two sets of files:
238: one for the invoker and the other for the performer.
239: \begin{quote}\small\begin{verbatim}
240: MODULE-Rops.o: MODULE-ops.c MODULE-ops.h
241: $(CC) $(CFLAGS) -DPERFORMER -c MODULE-ops.c
242: mv MODULE-ops.o $@
243:
244: MODULE-Iops.o: MODULE-ops.c MODULE-ops.h
245: $(CC) $(CFLAGS) -DINVOKER -c MODULE-ops.c
246: mv MODULE-ops.o $@
247: \end{verbatim}\end{quote}
248:
249: \subsection {Grinding}
250: Figure~\ref{PepyGrind} on page~\pageref{PepyGrind} of \volone/
251: contains an entry for the \man vgrindefs(5) file,
252: which may be used by the \man vgrind(1) or \man tgrind(1) facility.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.