1 .TH IDL "1" "2020-04-20" "idl 0.1" "User Commands" 2 3 .SH NAME 4 idl \- L4Re IDL parser and code generator 5 6 .SH SYNOPSIS 7 .B idl 8 .RI [ options ] 9 .IR file " ..." 10 .br 11 .B idl 12 .I --help 13 .br 14 .B idl 15 .I --version 16 17 .SH DESCRIPTION 18 .B idl 19 compiles interface descriptions provided by one or more files, each description 20 representing the interface employed by a component operating in the L4 runtime 21 environment. These descriptions are used to generate definitions and code to be 22 incorporated into libraries and applications, allowing such software to treat 23 distinct components and their operations as if they were resident in the same 24 program. Similarly, code may be generated to permit components to be exposed 25 to, and accessed by, such libraries and applications. 26 .PP 27 Components can support one or many different interfaces by composing them into a 28 single compound interface, with the different interfaces and operations 29 distinguished using protocol and operation code (opcode) information embedded in 30 the invocation information for a given operation. 31 .B idl 32 supports the generation of code to select the appropriate interface when 33 handling invocations. 34 .PP 35 The interface description or definition language (IDL) employed by 36 .B idl 37 is broadly similar to that used by systems such as CORBA. Indeed, a tool called 38 DICE was once made available for L4-based environments that sought to provide a 39 degree of compatibility with the CORBA and DCE standards. However, 40 .B idl 41 does not seek to replicate the extensive functionality or complexity of that 42 tool or of technologies like CORBA. Instead, it merely seeks to provide a 43 convenient shorthand for interface description, relieving the programmer of the 44 burden of writing and maintaining code to help components communicate with each 45 other. 46 .PP 47 By default, code in the C programming language is generated by this tool. 48 Support for other languages is documented below for the 49 .BR \-l " and " \-\-language 50 options. 51 52 .SH OPTIONS 53 The following options may be specified: 54 .PP 55 .TP 56 .BR \-a ", " \-\-all 57 Generate all code and header files for the described interfaces for both client 58 and server roles. 59 .TP 60 .BR \-c ", " \-\-client 61 Generate client files only, appropriate when needing to access interfaces. 62 .TP 63 .BR \-h ", " \-\-headers 64 Generate header files for the selected configuration or for both client and 65 server configurations. 66 .TP 67 .BR \-i ", " \-\-interfaces 68 Generate interface header files only, these declaring the actual functions 69 implementing the operations of the described interfaces. Common definitions 70 employed by client and server code are also defined in these files. 71 .TP 72 .BR \-r ", " \-\-routines 73 Generate routines, these defining functions exposing the operations of the 74 described interfaces. 75 .TP 76 .BR \-s ", " \-\-server 77 Generate server code only, appropriate when exposing components via interfaces. 78 .TP 79 .BR \-v ", " \-\-verbose 80 Report the details of interfaces as they are processed. 81 .PP 82 If the 83 .BR \-h ", " \-\-headers ", " \-i ", " \-\-interfaces ", " \-r " or " 84 .BR \-\-routines 85 options are not given, all kinds of output are produced for whichever 86 configuration has been selected. 87 .PP 88 If the 89 .BR \-c ", " \-\-client ", " \-s ", " \-\-server ", " \-C ", " \-\-comp ", " 90 .BR \-N " or " \-\-comp-name 91 options are not given, output is produced for client and server configurations. 92 .PP 93 Some options may be followed by a value, either immediately after the long form 94 of the option and an equals sign (\fB=\fR) or in the argument that follows them: 95 .PP 96 .TP 97 \fB\-C\fR, \fB\-\-comp\fR=\fIPREFIX\fR 98 Generate compound (or composite, or component) interface files, indicating the 99 name of the compound interface which will also be the prefix of the generated 100 files; such files are employed by servers to pass control to individual 101 interfaces. 102 .TP 103 \fB\-d\fR, \fB\-\-dir\fR=\fIDIRECTORY\fR 104 Indicate the output directory for generated files. 105 .TP 106 \fB\-l\fR, \fB\-\-language\fR=\fILANGUAGE\fR 107 Select the programming language to be used for output; currently only 108 .BR C " and " C++ 109 are accepted as values for this option. 110 .TP 111 \fB\-N\fR, \fB\-\-comp-name\fR=\fINAME\fR 112 Select a different name for a compound (or composite, component) interface than 113 that indicated by the 114 .BR \-C " or " \-\-comp 115 options. 116 117 .SH EXAMPLES 118 Compile the interfaces in 119 .IR hello.idl , 120 writing the generated files to the same directory: 121 .IP 122 idl hello.idl 123 .PP 124 Compile the interfaces but only generate header files, writing them to the 125 .I output 126 directory: 127 .IP 128 idl -d output -h hello.idl 129 .PP 130 The same using long arguments: 131 .IP 132 idl --dir=output --headers hello.idl 133 .PP 134 Generate client header files and routines: 135 .IP 136 idl -c hello.idl 137 .PP 138 Generate server header files and routines: 139 .IP 140 idl -s hello.idl 141 .PP 142 Generate server routines in C++ only: 143 .IP 144 idl --language=C++ -r -s hello.idl 145 .PP 146 Generate compound interface header files and dispatch routines for a server: 147 .IP 148 idl -C greetings hello.idl goodbye.idl 149 .PP 150 The above would create a dispatch mechanism for a component called 151 .I greetings 152 supporting both of the indicated interfaces. This complements server code 153 generated for the individual interfaces: 154 .IP 155 idl -s hello.idl goodbye.idl 156 .PP 157 Generate just the interface headers for the individual interfaces: 158 .IP 159 idl -i hello.idl goodbye.idl 160 161 .SH INTERFACE DESCRIPTIONS 162 An interface will resemble the following in its simplest practical form: 163 .in +4n 164 .nf 165 .sp 166 interface \fIinterface_name\fR 167 { 168 void \fIoperation_name\fR ( \fIoperation_parameters\fR ); 169 }; 170 .fi 171 .PP 172 Parameters have the following form: 173 .in +4n 174 .nf 175 .sp 176 \fIspecifier\fR \fItype\fR \fIname\fR 177 .fi 178 .PP 179 The specifier indicates the direction: whether a parameter is used for input 180 (\fBin\fR), output (\fBout\fR), or input and output (\fBinout\fR). A type may 181 incorporate multiple identifiers in the way that C data types do so. A 182 parameter name is a single identifier. For example: 183 .in +4n 184 .nf 185 .sp 186 interface Calc 187 { 188 void add(in int left, in int right, out int result); 189 void subtract(in int left, in int right, out int result); 190 void multiply(in int left, in int right, out int result); 191 void divide(in int numerator, in int denominator, out int result); 192 }; 193 .fi 194 .PP 195 Attributes may be applied to interfaces and to individual operations to 196 configure their availability. For instance, interfaces may support protocol 197 attributes and operations may support opcode attributes. These attributes are 198 specified before the appropriate construct in a bracketed section as in the 199 following example: 200 .in +4n 201 .nf 202 .sp 203 [protocol(L4RE_PROTO_DATASPACE)] 204 interface Dataspace 205 { 206 [opcode(0)] void map(...); 207 }; 208 .fi 209 .PP 210 Apart from core L4 data types and values, all other values must be imported from 211 the appropriate header file using the \fB#include\fR directive. For the above 212 use of \fBL4RE_PROTO_DATASPACE\fR the following directive would be required: 213 .in +4n 214 .nf 215 .sp 216 #include <l4/re/protocols.h> 217 .fi 218 .PP 219 Such includes are incorporated into the generated code. 220 221 .SH SUPPORTED ATTRIBUTES 222 Interfaces currently support the following attributes: 223 .PP 224 .TP 225 \fBprotocol(\fIprotocol_value\fB)\fR 226 A protocol applying to the entire interface. Clients will specify the 227 given \fIprotocol_value\fR as the message tag label when sending requests to 228 the interface. 229 .PP 230 Operations currently support the following attributes: 231 .PP 232 .TP 233 \fBcompletion\fR 234 An indication that the given operation is to be supported by a function 235 accepting \fBin\fR (input) and \fBinout\fR (input/output) parameters. This 236 function, featuring in the generated interface, initiates the operation with 237 no immediate reply to the initiating request being generated. A separate 238 function supporting \fBinout\fR and \fBout\fR (output) parameters is also 239 generated so that the server code can eventually send a reply and provide the 240 appropriate reply data. See the \fBCOMPLETION OPERATIONS\fR section for more 241 details. 242 .TP 243 \fBopcode(\fIopcode_value\fB)\fR 244 An operation code (opcode) applying to the given operation. Without a protocol 245 value applying to an interface, clients will specify the given 246 \fIopcode_value\fR as the message tag label when sending requests to the 247 interface. With a protocol, the \fIopcode_value\fR will be specified in the 248 first message word. 249 250 .SH COMPLETION OPERATIONS 251 Operations can be annotated with the \fBcompletion\fR attribute, indicating 252 that a client will initiate the operation with any parameters conveying input 253 values, with the completion of the operation being performed explicitly by 254 server code. 255 .PP 256 Consider the following interface: 257 .in +4n 258 .nf 259 .sp 260 interface Calc 261 { 262 void pow(in double left, in double right, out double result); 263 }; 264 .fi 265 .PP 266 A client would employ an interface with an equivalent signature, something 267 like this in C: 268 .in +4n 269 .nf 270 .sp 271 Calc_pow(ref_Calc _self, double left, double right, double *result); 272 .fi 273 .PP 274 Here, the result is written to the address provided by the corresponding 275 parameter. When the client invokes the operation, it remains unaware of the 276 nature of the work done by the server: the operation acts like a typical 277 function call. 278 .PP 279 Now consider the following interface annotated with the \fBcompletion\fR 280 attribute: 281 .in +4n 282 .nf 283 .sp 284 interface CalcPrivate 285 { 286 [completion] void pow(in double left, in double right, out double result); 287 }; 288 .fi 289 .PP 290 Here, the operation exposed on the server would have the following signature: 291 .in +4n 292 .nf 293 .sp 294 CalcPrivate_pow(ref_CalcPrivate _self, double base, double exponent); 295 .fi 296 .PP 297 This function is not intended to communicate the result. Instead, within the 298 server code, a function of the following form will need to be invoked: 299 .in +4n 300 .nf 301 .sp 302 complete_CalcPrivate_pow(l4_cap_idx_t _endp, double result); 303 .fi 304 .PP 305 Here, the result is communicated via the corresponding parameter, with the 306 indicated endpoint (\fB_endp\fR) receiving the reply. 307 308 .SH COMPONENTS AND COMPOUND INTERFACES 309 Components may attempt to support more than one interface. Although inheritance 310 might be employed to achieve this, the combination or composition of interfaces 311 is somewhat different: crucially, all involved interfaces remain distinct and do 312 not override each other (conflicts between protocols and operation codes 313 notwithstanding). 314 315 .SH FILES 316 .B idl 317 reads all interfaces in a single input file and generates output files that 318 each contain the details of all of these interfaces. Apart from the compound 319 interface files, output files are written alongside their corresponding input 320 files. This behaviour can be overridden with the \fB\-d\fR or \fB\-\-dir\fR 321 options, choosing a specific output directory for all files including compound 322 interface files. 323 .PP 324 The following kinds of output files are generated for a file with a name of the 325 form 326 .IR name ".idl :" 327 .PP 328 .TP 329 .IR name "_client.c or " name _client.cc 330 contains the function definitions needed for the operations of all the 331 interfaces. 332 .TP 333 .IR name _client.h 334 contains the function declarations, signatures or prototypes for the 335 operations. 336 .TP 337 .IR name _interface.h 338 contains the function declarations, signatures or prototypes for the actual 339 operations; these are used by client and server code. 340 .TP 341 .IR name "_server.c or " name _server.cc 342 contains the function definitions needed to provide entry points for the 343 operations of all the interfaces. 344 .TP 345 .IR name _server.h 346 contains the function declarations, signatures or prototypes for the entry 347 points. 348 .PP 349 Where many input files are provided, 350 .B idl 351 processes each one in turn, generating a separate set of output files for each 352 input file. 353 .PP 354 For server components, compound interface files can also be produced with their 355 names chosen using the \fB\-C\fR or \fB\-\-comp\fR options. With a value of 356 \fIname\fR given with these options, files of the following form are produced: 357 .TP 358 .IR name _interface.h 359 contains a compound interface declaration (for C++ only) needed for the dispatch 360 mechanism to function, also to be used by the actual component implementing the 361 interfaces. 362 .TP 363 .IR name _interfaces.h 364 contains include statements referencing individual interfaces, needed by the 365 above compound interface declaration. 366 .TP 367 .IR name "_server.c or " name _server.cc 368 contains the function definitions needed to dispatch to the interfaces. 369 .TP 370 .IR name _server.h 371 contains the function declarations, signatures or prototypes for the dispatch 372 functions. 373 .PP 374 These files provide support for interpreting messages received by servers and 375 directing handling of such messages to interface-specific dispatch functions or 376 directly to functions acting as operation entry points. 377 378 .SH L4RE BUILD SYSTEM INTEGRATION 379 To be useful in the L4Re build system, the 380 .I idl4re 381 distribution should be made available with the name 382 .I idl4re 383 in the 384 .I src/l4 385 section of the general L4Re distribution. Rules can then be added to Makefiles 386 to invoke the tool and to produce source files that can then be compiled in the 387 normal way. A collection of Makefile-compatible files are provided in the 388 .I mk 389 directory within the 390 .I idl4re 391 distribution to provide such rules and to support the declaration of interfaces 392 and components. 393 394 .SH LIMITATIONS 395 There are probably far too many limitations to list here, but some notable 396 ones are provided below. 397 .PP 398 Error reporting is currently very minimal, providing the most basic parsing 399 error details from the scanner and parser. Obviously, this should be improved 400 to make the tool more usable. 401 .PP 402 Validation of input is also minimal, with the tool mostly acting as a kind of 403 preprocessor, generating code that may then not behave exactly as intended, 404 although the code should be well-formed. 405 .PP 406 Interface inheritance is not supported, neither are modules. Both of these 407 things are typically available in other languages describing interfaces. 408 409 .SH AUTHOR 410 Paul Boddie <paul@boddie.org.uk> 411 412 .SH RESOURCES 413 The project Web site: http://projects.boddie.org.uk/idl4re 414 415 .SH COPYRIGHT 416 Copyright \(co 2019, 2020 Paul Boddie <paul@boddie.org.uk> 417 .PP 418 This program is free software; you may redistribute it under the terms of 419 the GNU General Public License version 2 or (at your option) a later version. 420 This program has absolutely no warranty. 421 422 .SH SEE ALSO 423 .TP 424 CORBA: https://www.omg.org/spec/CORBA/ 425 .TP 426 DCE: http://www.opengroup.org/dce/ 427 .TP 428 DICE: https://wiki.tudos.org/Dice_IDL_compiler