1.1 --- a/docs/idl.1 Fri Dec 09 19:33:15 2022 +0100
1.2 +++ b/docs/idl.1 Sat Dec 10 01:28:22 2022 +0100
1.3 @@ -1,4 +1,4 @@
1.4 -.TH IDL "1" "2022-09-15" "idl 0.1" "User Commands"
1.5 +.TH IDL "1" "2022-12-09" "idl 2022-12-09" "User Commands"
1.6
1.7 .SH NAME
1.8 idl \- L4Re IDL parser and code generator
1.9 @@ -60,6 +60,10 @@
1.10 .BR \-c ", " \-\-client
1.11 Generate client files only, appropriate when needing to access interfaces.
1.12 .TP
1.13 +.BR \-f ", " \-\-files
1.14 +Only show processed filenames on standard output, with no output files being
1.15 +produced.
1.16 +.TP
1.17 .BR \-h ", " \-\-headers
1.18 Generate header files for the selected configuration or for both client and
1.19 server configurations.
1.20 @@ -69,6 +73,11 @@
1.21 implementing the operations of the described interfaces. Common definitions
1.22 employed by client and server code are also defined in these files.
1.23 .TP
1.24 +.BR \-R ", " \-\-recursive
1.25 +Generate output files corresponding to all interface files processed. Where an
1.26 +interface file imports other files, output will also be generated for these
1.27 +files.
1.28 +.TP
1.29 .BR \-r ", " \-\-routines
1.30 Generate routines, these defining functions exposing the operations of the
1.31 described interfaces.
1.32 @@ -86,20 +95,16 @@
1.33 configuration has been selected.
1.34 .PP
1.35 If the
1.36 -.BR \-c ", " \-\-client ", " \-s ", " \-\-server ", " \-C ", " \-\-comp ", "
1.37 -.BR \-N " or " \-\-comp-name
1.38 +.BR \-c ", " \-\-client ", " \-s " or " \-\-server
1.39 options are not given, output is produced for client and server configurations.
1.40 +The
1.41 +.BR \-f " and " \-\-files
1.42 +options will suppress all output regardless of any other options indicated.
1.43 .PP
1.44 Some options may be followed by a value, either immediately after the long form
1.45 of the option and an equals sign (\fB=\fR) or in the argument that follows them:
1.46 .PP
1.47 .TP
1.48 -\fB\-C\fR, \fB\-\-comp\fR=\fIPREFIX\fR
1.49 -Generate compound (or composite, or component) interface files, indicating the
1.50 -name of the compound interface which will also be the prefix of the generated
1.51 -files; such files are employed by servers to pass control to individual
1.52 -interfaces.
1.53 -.TP
1.54 \fB\-d\fR, \fB\-\-dir\fR=\fIDIRECTORY\fR
1.55 Indicate the output directory for generated files.
1.56 .TP
1.57 @@ -107,12 +112,6 @@
1.58 Select the programming language to be used for output; currently only
1.59 .BR C " and " C++
1.60 are accepted as values for this option.
1.61 -.TP
1.62 -\fB\-N\fR, \fB\-\-comp-name\fR=\fINAME\fR
1.63 -Select a different name for a compound (or composite, component) interface than
1.64 -that indicated by the
1.65 -.BR \-C " or " \-\-comp
1.66 -options.
1.67
1.68 .SH EXAMPLES
1.69 Compile the interfaces in
1.70 @@ -143,20 +142,13 @@
1.71 .IP
1.72 idl --language=C++ -r -s hello.idl
1.73 .PP
1.74 -Generate compound interface header files and dispatch routines for a server:
1.75 +Generate files for multiple interface files:
1.76 .IP
1.77 -idl -C greetings hello.idl goodbye.idl
1.78 +idl hello.idl goodbye.idl
1.79 .PP
1.80 -The above would create a dispatch mechanism for a component called
1.81 -.I greetings
1.82 -supporting both of the indicated interfaces. This complements server code
1.83 -generated for the individual interfaces:
1.84 +Generate all output files for an interface file that imports other files:
1.85 .IP
1.86 -idl -s hello.idl goodbye.idl
1.87 -.PP
1.88 -Generate just the interface headers for the individual interfaces:
1.89 -.IP
1.90 -idl -i hello.idl goodbye.idl
1.91 +idl -R hello_and_goodbye.idl
1.92
1.93 .SH INTERFACE DESCRIPTIONS
1.94 An interface will resemble the following in its simplest practical form:
1.95 @@ -250,11 +242,14 @@
1.96 \fBopcode_type(\fIopcode_type_value\fB)\fR
1.97 An explicit type for the opcode applying to the given operation.
1.98
1.99 -.SH COMPLETION OPERATIONS
1.100 -Operations can be annotated with the \fBcompletion\fR attribute, indicating
1.101 -that a client will initiate the operation with any parameters conveying input
1.102 -values, with the completion of the operation being performed explicitly by
1.103 -server code.
1.104 +.SH SENDING RESULTS DURING OPERATIONS
1.105 +.PP
1.106 +Normally, results are communicated from operations by setting the appropriate
1.107 +output parameter values. However, it is possible to send results in advance by
1.108 +calling a completion function. Completion functions are generally made available
1.109 +for all operations, regardless of whether the \fBcompletion\fR attribute is
1.110 +specified. Such default completion functions merely provide a way of
1.111 +communicating results.
1.112 .PP
1.113 Consider the following interface:
1.114 .in +4n
1.115 @@ -274,10 +269,56 @@
1.116 Calc_pow(ref_Calc _self, double left, double right, double *result);
1.117 .fi
1.118 .PP
1.119 -Here, the result is written to the address provided by the corresponding
1.120 -parameter. When the client invokes the operation, it remains unaware of the
1.121 -nature of the work done by the server: the operation acts like a typical
1.122 -function call.
1.123 +Here, the result is normally written to the address provided by the
1.124 +corresponding parameter. However, the operation is also supported by another
1.125 +function as follows:
1.126 +.in +4n
1.127 +.nf
1.128 +.sp
1.129 +complete_Calc_pow(double result);
1.130 +.fi
1.131 +.PP
1.132 +Instead of using the \fBresult\fR output parameter in \fBCalc_pow\fR to return a
1.133 +result value, this parameter can be ignored and the \fBcomplete_Calc_pow\fR
1.134 +function used to send a response to the client, the result value being passed as
1.135 +a parameter to this function. To prevent the server framework from attempting to
1.136 +use the \fBresult\fR output parameter to send another response, a special value
1.137 +is returned from the operation:
1.138 +.in +4n
1.139 +.nf
1.140 +.sp
1.141 +/* Complete the operation and send results. */
1.142 +
1.143 +complete_Calc_pow(result);
1.144 +
1.145 +/* More work done. */
1.146 +
1.147 +return IPC_MESSAGE_SENT;
1.148 +.fi
1.149 +.PP
1.150 +Unlike explicitly designated completion operations, results sent in this way
1.151 +will be directed to the initiating client as a reply to its original request.
1.152 +
1.153 +.SH COMPLETION OPERATIONS
1.154 +Operations can be annotated with the \fBcompletion\fR attribute, indicating
1.155 +that a client will initiate the operation with any parameters conveying input
1.156 +values, with the completion of the operation being performed explicitly by
1.157 +server code. Unlike regular operations, such annotated operations allow the
1.158 +completion to involve another endpoint, as opposed to the client that initiated
1.159 +the operation.
1.160 +.PP
1.161 +Consider the following interface:
1.162 +.in +4n
1.163 +.nf
1.164 +.sp
1.165 +interface Calc
1.166 +{
1.167 + void pow(in double left, in double right, out double result);
1.168 +};
1.169 +.fi
1.170 +.PP
1.171 +This interface would be presented to the client for it to use when initiating
1.172 +operations.
1.173 .PP
1.174 Now consider the following interface annotated with the \fBcompletion\fR
1.175 attribute:
1.176 @@ -297,8 +338,9 @@
1.177 CalcPrivate_pow(ref_CalcPrivate _self, double base, double exponent);
1.178 .fi
1.179 .PP
1.180 -This function is not intended to communicate the result. Instead, within the
1.181 -server code, a function of the following form will need to be invoked:
1.182 +This function is not intended to communicate the result, and it even lacks the
1.183 +appropriate output parameter. Instead, within the server code, a function of the
1.184 +following form will need to be invoked:
1.185 .in +4n
1.186 .nf
1.187 .sp
1.188 @@ -306,23 +348,52 @@
1.189 .fi
1.190 .PP
1.191 Here, the result is communicated via the corresponding parameter, with the
1.192 -indicated endpoint (\fB_endp\fR) receiving the reply.
1.193 +indicated endpoint (\fB_endp\fR) receiving the reply. Where the endpoint is
1.194 +the client that initiated an operation, the effect will be indistinguishable
1.195 +from a normal invocation. However, where another endpoint is chosen to receive
1.196 +the reply, the initiating client will effectively give up control to the client
1.197 +employing the chosen endpoint, with that designated client assuming control
1.198 +until such time that it calls the operation. Thus, this form of completion
1.199 +operation permits a form of simple scheduling.
1.200
1.201 .SH COMPONENTS AND COMPOUND INTERFACES
1.202 -Components may attempt to support more than one interface. Although inheritance
1.203 -might be employed to achieve this, the combination or composition of interfaces
1.204 -is somewhat different: crucially, all involved interfaces remain distinct and do
1.205 -not override each other (conflicts between protocols and operation codes
1.206 -notwithstanding).
1.207 +Components may wish to support more than one interface, and this can be done
1.208 +using composition, as illustrated below involving two interfaces:
1.209 +.in +4n
1.210 +.nf
1.211 +.sp
1.212 +interface \fIinterface_name\fR composes \fIbase_interface1\fR, \fIbase_interface2\fR;
1.213 +.fi
1.214 +.PP
1.215 +Although inheritance might be employed to provide compound interfaces, the
1.216 +combination or composition of interfaces is somewhat different: crucially, all
1.217 +involved interfaces remain distinct and do not override each other (conflicts
1.218 +between protocols and operation codes notwithstanding).
1.219 +.PP
1.220 +Base interfaces, these being interfaces used in composition to make a compound
1.221 +interface, can be defined in the same file as the compound interface.
1.222 +Alternatively, an \fBimport\fR statement can be used to import interface
1.223 +definitions from another file, such files residing in the same directory as the
1.224 +file currently being processed. For example:
1.225 +.in +4n
1.226 +.nf
1.227 +.sp
1.228 +import "calc.idl";
1.229 +import "counter.idl";
1.230 +
1.231 +interface \fICalcCounter\fR composes \fICalc\fR, \fICounter\fR;
1.232 +.fi
1.233 +.PP
1.234 +Here, \fBcalc.idl\fR would provide \fBCalc\fR, and \fBcounter.idl\fR would
1.235 +provide \fBCounter\fR.
1.236
1.237 .SH FILES
1.238 .B idl
1.239 reads all interfaces in a single input file and generates output files that
1.240 -each contain the details of all of these interfaces. Apart from the compound
1.241 -interface files, output files are written alongside their corresponding input
1.242 -files. This behaviour can be overridden with the \fB\-d\fR or \fB\-\-dir\fR
1.243 -options, choosing a specific output directory for all files including compound
1.244 -interface files.
1.245 +each contain the details of all of these interfaces. By default, output files
1.246 +are written alongside their corresponding input files, but this behaviour can be
1.247 +overridden with the \fB\-d\fR or \fB\-\-dir\fR options, choosing a specific
1.248 +output directory for all files including compound interface files.
1.249 .PP
1.250 The following kinds of output files are generated for a file with a name of the
1.251 form
1.252 @@ -343,7 +414,9 @@
1.253 .TP
1.254 .IR name "_server.c or " name _server.cc
1.255 contains the function definitions needed to provide entry points for the
1.256 -operations of all the interfaces.
1.257 +operations of all the interfaces. Where an interface is composed of other
1.258 +interfaces, the function definitions will dispatch to these interfaces' own
1.259 +functions.
1.260 .TP
1.261 .IR name _server.h
1.262 contains the function declarations, signatures or prototypes for the entry
1.263 @@ -354,29 +427,11 @@
1.264 processes each one in turn, generating a separate set of output files for each
1.265 input file.
1.266 .PP
1.267 -For server components, compound interface files can also be produced with their
1.268 -names chosen using the \fB\-C\fR or \fB\-\-comp\fR options. With a value of
1.269 -\fIname\fR given with these options, files of the following form are produced:
1.270 -.TP
1.271 -.IR name _interface.h
1.272 -contains a compound interface declaration (for C++ only) needed for the dispatch
1.273 -mechanism to function, also to be used by the actual component implementing the
1.274 -interfaces.
1.275 -.TP
1.276 -.IR name _interfaces.h
1.277 -contains include statements referencing individual interfaces, needed by the
1.278 -above compound interface declaration.
1.279 -.TP
1.280 -.IR name "_server.c or " name _server.cc
1.281 -contains the function definitions needed to dispatch to the interfaces.
1.282 -.TP
1.283 -.IR name _server.h
1.284 -contains the function declarations, signatures or prototypes for the dispatch
1.285 -functions.
1.286 -.PP
1.287 -These files provide support for interpreting messages received by servers and
1.288 -directing handling of such messages to interface-specific dispatch functions or
1.289 -directly to functions acting as operation entry points.
1.290 +Output files will only be produced corresponding to the indicated input files,
1.291 +even if those files import other files. To generate output for the input files
1.292 +together with the imported files, use the
1.293 +.BR \-R " or " \-\-recursive
1.294 +options.
1.295
1.296 .SH L4RE BUILD SYSTEM INTEGRATION
1.297 To be useful in the L4Re build system, the
1.298 @@ -384,10 +439,10 @@
1.299 distribution should be made available with the name
1.300 .I idl4re
1.301 in the
1.302 -.I src/l4
1.303 -section of the general L4Re distribution. Rules can then be added to Makefiles
1.304 -to invoke the tool and to produce source files that can then be compiled in the
1.305 -normal way. A collection of Makefile-compatible files are provided in the
1.306 +.IR l4 " section (or " src/l4 " in earlier forms)"
1.307 +of the general L4Re distribution. Rules can then be added to Makefiles to invoke
1.308 +the tool and to produce source files that can then be compiled in the normal
1.309 +way. A collection of Makefile-compatible files are provided in the
1.310 .I mk
1.311 directory within the
1.312 .I idl4re
1.313 @@ -402,12 +457,19 @@
1.314 error details from the scanner and parser. Obviously, this should be improved
1.315 to make the tool more usable.
1.316 .PP
1.317 +Memory management is not comprehensive. However, this tool is meant to be run
1.318 +for the duration of a given code generation task, not run as a service
1.319 +indefinitely.
1.320 +.PP
1.321 Validation of input is also minimal, with the tool mostly acting as a kind of
1.322 preprocessor, generating code that may then not behave exactly as intended,
1.323 although the code should be well-formed.
1.324 .PP
1.325 -Interface inheritance is not supported, neither are modules. Both of these
1.326 -things are typically available in other languages describing interfaces.
1.327 +File inclusion is currently limited to loading files that all reside in the same
1.328 +location, although include paths could be supported.
1.329 +.PP
1.330 +Things like modules and type definitions are not supported, these typically
1.331 +being available in other languages describing interfaces.
1.332
1.333 .SH AUTHOR
1.334 Paul Boddie <paul@boddie.org.uk>