1.1 --- a/docs/idl.1 Tue Nov 26 21:18:35 2019 +0100
1.2 +++ b/docs/idl.1 Tue Nov 26 23:39:36 2019 +0100
1.3 @@ -1,6 +1,8 @@
1.4 -.TH IDL "1" "2019-11-25" "idl 0.1" "User Commands"
1.5 +.TH IDL "1" "2019-11-26" "idl 0.1" "User Commands"
1.6 +
1.7 .SH NAME
1.8 idl \- L4Re IDL parser and code generator
1.9 +
1.10 .SH SYNOPSIS
1.11 .B idl
1.12 .RI [ options ]
1.13 @@ -11,6 +13,7 @@
1.14 .br
1.15 .B idl
1.16 .I --version
1.17 +
1.18 .SH DESCRIPTION
1.19 .B idl
1.20 compiles interface descriptions provided by one or more files, each description
1.21 @@ -45,6 +48,7 @@
1.22 Support for other languages is documented below for the
1.23 .BR \-l " and " \-\-language
1.24 options.
1.25 +
1.26 .SH OPTIONS
1.27 The following options may be specified:
1.28 .PP
1.29 @@ -109,6 +113,7 @@
1.30 that indicated by the
1.31 .BR \-C " or " \-\-comp
1.32 options.
1.33 +
1.34 .SH EXAMPLES
1.35 Compile the interfaces in
1.36 .IR hello.idl ,
1.37 @@ -149,9 +154,10 @@
1.38 .IP
1.39 idl -s hello.idl goodbye.idl
1.40 .PP
1.41 -Generates just the interface headers for the individual interfaces:
1.42 +Generate just the interface headers for the individual interfaces:
1.43 .IP
1.44 idl -i hello.idl goodbye.idl
1.45 +
1.46 .SH INTERFACE DESCRIPTIONS
1.47 An interface will resemble the following in its simplest practical form:
1.48 .in +4n
1.49 @@ -177,7 +183,7 @@
1.50 .in +4n
1.51 .nf
1.52 .sp
1.53 -interface calc
1.54 +interface Calc
1.55 {
1.56 void add(in int left, in int right, out int result);
1.57 void subtract(in int left, in int right, out int result);
1.58 @@ -202,11 +208,8 @@
1.59 .fi
1.60 .PP
1.61 Apart from core L4 data types and values, all other values must be imported from
1.62 -the appropriate header file using the
1.63 -.B #include
1.64 -directive. For the above use of
1.65 -.B L4RE_PROTO_DATASPACE
1.66 -the following directive would be required:
1.67 +the appropriate header file using the \fB#include\fR directive. For the above
1.68 +use of \fBL4RE_PROTO_DATASPACE\fR the following directive would be required:
1.69 .in +4n
1.70 .nf
1.71 .sp
1.72 @@ -214,55 +217,107 @@
1.73 .fi
1.74 .PP
1.75 Such includes are incorporated into the generated code.
1.76 +
1.77 .SH SUPPORTED ATTRIBUTES
1.78 Interfaces currently support the following attributes:
1.79 .PP
1.80 .TP
1.81 -protocol(\fIprotocol_value\fR)
1.82 +\fBprotocol(\fIprotocol_value\fB)\fR
1.83 A protocol applying to the entire interface. Clients will specify the
1.84 -given
1.85 -.IR protocol_value
1.86 -as the message tag label when sending requests to the interface.
1.87 +given \fIprotocol_value\fR as the message tag label when sending requests to
1.88 +the interface.
1.89 .PP
1.90 Operations currently support the following attributes:
1.91 .PP
1.92 .TP
1.93 -completion
1.94 +\fBcompletion\fR
1.95 An indication that the given operation is to be supported by a function
1.96 -accepting
1.97 -.B in
1.98 -(input) and
1.99 -.B inout
1.100 -(input/output) parameters. This function, featuring in the generated
1.101 -interface, initiates the operation with no immediate reply to the initiating
1.102 -request being generated. A separate function supporting
1.103 -.B inout
1.104 -and
1.105 -.B out
1.106 -(output) parameters is also generated so that the server code can eventually
1.107 -send a reply and provide the appropriate reply data.
1.108 +accepting \fBin\fR (input) and \fBinout\fR (input/output) parameters. This
1.109 +function, featuring in the generated interface, initiates the operation with
1.110 +no immediate reply to the initiating request being generated. A separate
1.111 +function supporting \fBinout\fR and \fBout\fR (output) parameters is also
1.112 +generated so that the server code can eventually send a reply and provide the
1.113 +appropriate reply data. See the \fBCOMPLETION OPERATIONS\fR section for more
1.114 +details.
1.115 .TP
1.116 -opcode(\fIopcode_value\fR)
1.117 +\fBopcode(\fIopcode_value\fB)\fR
1.118 An operation code (opcode) applying to the given operation. Without a protocol
1.119 value applying to an interface, clients will specify the given
1.120 -.IR opcode_value
1.121 -as the message tag label when sending requests to the interface. With a
1.122 -protocol, the
1.123 -.IR opcode_value
1.124 -will be specified in the first message word.
1.125 +\fIopcode_value\fR as the message tag label when sending requests to the
1.126 +interface. With a protocol, the \fIopcode_value\fR will be specified in the
1.127 +first message word.
1.128 +
1.129 +.SH COMPLETION OPERATIONS
1.130 +Operations can be annotated with the \fBcompletion\fR attribute, indicating
1.131 +that a client will initiate the operation with any parameters conveying input
1.132 +values, with the completion of the operation being performed explicitly by
1.133 +server code.
1.134 +.PP
1.135 +Consider the following interface:
1.136 +.in +4n
1.137 +.nf
1.138 +.sp
1.139 +interface Calc
1.140 +{
1.141 + void pow(in double left, in double right, out double result);
1.142 +};
1.143 +.fi
1.144 +.PP
1.145 +A client would employ an interface with an equivalent signature, something
1.146 +like this in C:
1.147 +.in +4n
1.148 +.nf
1.149 +.sp
1.150 +Calc_pow(ref_Calc _self, double left, double right, double *result);
1.151 +.fi
1.152 +.PP
1.153 +Here, the result is written to the address provided by the corresponding
1.154 +parameter. When the client invokes the operation, it remains unaware of the
1.155 +nature of the work done by the server: the operation acts like a typical
1.156 +function call.
1.157 +.PP
1.158 +Now consider the following interface annotated with the \fBcompletion\fR
1.159 +attribute:
1.160 +.in +4n
1.161 +.nf
1.162 +.sp
1.163 +interface CalcPrivate
1.164 +{
1.165 + [completion] void pow(in double left, in double right, out double result);
1.166 +};
1.167 +.fi
1.168 +.PP
1.169 +Here, the operation exposed on the server would have the following signature:
1.170 +.in +4n
1.171 +.nf
1.172 +.sp
1.173 +CalcPrivate_pow(ref_CalcPrivate _self, double base, double exponent);
1.174 +.fi
1.175 +.PP
1.176 +This function is not intended to communicate the result. Instead, within the
1.177 +server code, a function of the following form will need to be invoked:
1.178 +.in +4n
1.179 +.nf
1.180 +.sp
1.181 +complete_CalcPrivate_pow(l4_cap_idx_t _endp, double result);
1.182 +.fi
1.183 +.PP
1.184 +Here, the result is communicated via the corresponding parameter, with the
1.185 +indicated endpoint (\fB_endp\fR) receiving the reply.
1.186 +
1.187 .SH COMPONENTS AND COMPOUND INTERFACES
1.188 Components may attempt to support more than one interface. Although inheritance
1.189 might be employed to achieve this, the combination or composition of interfaces
1.190 is somewhat different: crucially, all involved interfaces remain distinct and do
1.191 not override each other (conflicts between protocols and operation codes
1.192 notwithstanding).
1.193 +
1.194 .SH FILES
1.195 .B idl
1.196 reads all interfaces in a single input file and generates output files that
1.197 each contain the details of all of these interfaces. Apart from the compound
1.198 interface files, output files are written alongside their corresponding input
1.199 -files. This behaviour can be overridden with the
1.200 -.BR \-d " or " \--dir
1.201 +files. This behaviour can be overridden with the \fB\-d\fR or \fB\-\-dir\fR
1.202 options, choosing a specific output directory for all files including compound
1.203 interface files.
1.204 .PP
1.205 @@ -297,11 +352,8 @@
1.206 input file.
1.207 .PP
1.208 For server components, compound interface files can also be produced with their
1.209 -names chosen using the
1.210 -.BR \-C " or " \-\-comp
1.211 -options. With a value of
1.212 -.I name
1.213 -given with these options, files of the following form are produced:
1.214 +names chosen using the \fB\-C\fR or \fB\-\-comp\fR options. With a value of
1.215 +\fIname\fR given with these options, files of the following form are produced:
1.216 .TP
1.217 .IR name _interface.h
1.218 contains a compound interface declaration (for C++ only) needed for the dispatch
1.219 @@ -322,6 +374,7 @@
1.220 These files provide support for interpreting messages received by servers and
1.221 directing handling of such messages to interface-specific dispatch functions or
1.222 directly to functions acting as operation entry points.
1.223 +
1.224 .SH L4RE BUILD SYSTEM INTEGRATION
1.225 To be useful in the L4Re build system,
1.226 .B idl
1.227 @@ -362,16 +415,20 @@
1.228 .BR \-i " and " \-\-interfaces
1.229 options should be withheld) to avoid generating superfluous header files for
1.230 client and server routines.
1.231 +
1.232 .SH AUTHOR
1.233 Paul Boddie <paul@boddie.org.uk>
1.234 +
1.235 .SH RESOURCES
1.236 The project Web site: http://projects.boddie.org.uk/idl4re
1.237 +
1.238 .SH COPYRIGHT
1.239 Copyright \(co 2019 Paul Boddie <paul@boddie.org.uk>
1.240 .PP
1.241 This program is free software; you may redistribute it under the terms of
1.242 the GNU General Public License version 2 or (at your option) a later version.
1.243 This program has absolutely no warranty.
1.244 +
1.245 .SH SEE ALSO
1.246 .TP
1.247 CORBA: https://www.omg.org/spec/CORBA/
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/examples/calc.idl Tue Nov 26 23:39:36 2019 +0100
2.3 @@ -0,0 +1,8 @@
2.4 +interface Calc
2.5 +{
2.6 + void add(in int left, in int right, out int result);
2.7 + void subtract(in int left, in int right, out int result);
2.8 + void multiply(in int left, in int right, out int result);
2.9 + void divide(in int numerator, in int denominator, out int result);
2.10 + void pow(in double base, in double exponent, out double result);
2.11 +};
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/examples/calc_private.idl Tue Nov 26 23:39:36 2019 +0100
3.3 @@ -0,0 +1,8 @@
3.4 +interface CalcPrivate
3.5 +{
3.6 + void add(in int left, in int right, out int result);
3.7 + void subtract(in int left, in int right, out int result);
3.8 + void multiply(in int left, in int right, out int result);
3.9 + void divide(in int numerator, in int denominator, out int result);
3.10 + [completion] void pow(in double base, in double exponent, out double result);
3.11 +};