1 .TH IDL "1" "2023-03-23" "idl 2023-03-23" "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 \-f ", " \-\-files 64 Only show processed filenames on standard output, with no output files being 65 produced. 66 .TP 67 .BR \-h ", " \-\-headers 68 Generate header files for the selected configuration or for both client and 69 server configurations. 70 .TP 71 .BR \-i ", " \-\-interfaces 72 Generate interface header files only, these declaring the actual functions 73 implementing the operations of the described interfaces. Common definitions 74 employed by client and server code are also defined in these files. 75 .TP 76 .BR \-R ", " \-\-recursive 77 Generate output files corresponding to all interface files processed. Where an 78 interface file imports other files, output will also be generated for these 79 files. 80 .TP 81 .BR \-r ", " \-\-routines 82 Generate routines, these defining functions exposing the operations of the 83 described interfaces. 84 .TP 85 .BR \-s ", " \-\-server 86 Generate server code only, appropriate when exposing components via interfaces. 87 .TP 88 .BR \-v ", " \-\-verbose 89 Report the details of interfaces as they are processed. 90 .PP 91 If the 92 .BR \-h ", " \-\-headers ", " \-i ", " \-\-interfaces ", " \-r " or " 93 .BR \-\-routines 94 options are not given, all kinds of output are produced for whichever 95 configuration has been selected. 96 .PP 97 If the 98 .BR \-c ", " \-\-client ", " \-s " or " \-\-server 99 options are not given, output is produced for client and server configurations. 100 The 101 .BR \-f " and " \-\-files 102 options will suppress all output regardless of any other options indicated. 103 .PP 104 Some options may be followed by a value, either immediately after the long form 105 of the option and an equals sign (\fB=\fR) or in the argument that follows them: 106 .PP 107 .TP 108 \fB\-A\fR, \fB\-\-alignment\fR=\fIALIGNMENT\fR 109 Specify a minimum alignment in bytes for operation parameters, determining how 110 they are encoded in messages exchanged between components. 111 .TP 112 \fB\-d\fR, \fB\-\-dir\fR=\fIDIRECTORY\fR 113 Indicate the output directory for generated files. 114 .TP 115 \fB\-l\fR, \fB\-\-language\fR=\fILANGUAGE\fR 116 Select the programming language to be used for output; currently only 117 .BR C " and " C++ 118 are accepted as values for this option. 119 120 .SH EXAMPLES 121 Compile the interfaces in 122 .IR hello.idl , 123 writing the generated files to the same directory: 124 .IP 125 idl hello.idl 126 .PP 127 Compile the interfaces but only generate header files, writing them to the 128 .I output 129 directory: 130 .IP 131 idl -d output -h hello.idl 132 .PP 133 The same using long arguments: 134 .IP 135 idl --dir=output --headers hello.idl 136 .PP 137 Generate client header files and routines: 138 .IP 139 idl -c hello.idl 140 .PP 141 Generate server header files and routines: 142 .IP 143 idl -s hello.idl 144 .PP 145 Generate server routines in C++ only: 146 .IP 147 idl --language=C++ -r -s hello.idl 148 .PP 149 Generate files for multiple interface files: 150 .IP 151 idl hello.idl goodbye.idl 152 .PP 153 Generate all output files for an interface file that imports other files: 154 .IP 155 idl -R hello_and_goodbye.idl 156 157 .SH INTERFACE DESCRIPTIONS 158 An interface will resemble the following in its simplest practical form: 159 .in +4n 160 .nf 161 .sp 162 interface \fIinterface_name\fR 163 { 164 void \fIoperation_name\fR ( \fIoperation_parameters\fR ); 165 }; 166 .fi 167 .PP 168 Parameters have the following form: 169 .in +4n 170 .nf 171 .sp 172 \fIspecifier\fR \fItype\fR \fIname\fR 173 .fi 174 .PP 175 The specifier indicates the direction: whether a parameter is used for input 176 (\fBin\fR), output (\fBout\fR), or input and output (\fBinout\fR). A type may 177 incorporate multiple identifiers in the way that C data types do so. A 178 parameter name is a single identifier. For example: 179 .in +4n 180 .nf 181 .sp 182 interface Calc 183 { 184 void add(in int left, in int right, out int result); 185 void subtract(in int left, in int right, out int result); 186 void multiply(in int left, in int right, out int result); 187 void divide(in int numerator, in int denominator, out int result); 188 }; 189 .fi 190 .PP 191 Attributes may be applied to interfaces and to individual operations to 192 configure their availability. For instance, interfaces may support protocol 193 attributes and operations may support opcode attributes. These attributes are 194 specified before the appropriate construct in a bracketed section as in the 195 following example: 196 .in +4n 197 .nf 198 .sp 199 [protocol(L4RE_PROTO_DATASPACE)] 200 interface Dataspace 201 { 202 [opcode(0)] void map(...); 203 }; 204 .fi 205 .PP 206 Apart from core L4 data types and values, all other values must be imported from 207 the appropriate header file using the \fB#include\fR directive. For the above 208 use of \fBL4RE_PROTO_DATASPACE\fR the following directive would be required: 209 .in +4n 210 .nf 211 .sp 212 #include <l4/re/protocols.h> 213 .fi 214 .PP 215 Such includes are incorporated into the generated code. 216 217 .SH SUPPORTED ATTRIBUTES 218 Interfaces currently support the following attributes: 219 .PP 220 .TP 221 \fBprotocol(\fIprotocol_value\fB)\fR 222 A protocol applying to the entire interface. Clients will specify the 223 given \fIprotocol_value\fR as the message tag label when sending requests to 224 the interface. 225 .PP 226 Operations currently support the following attributes: 227 .PP 228 .TP 229 \fBcompletion\fR 230 An indication that the given operation is to be supported by a function 231 accepting \fBin\fR (input) and \fBinout\fR (input/output) parameters. This 232 function, featuring in the generated interface, initiates the operation with 233 no immediate reply to the initiating request being generated. A separate 234 function supporting \fBinout\fR and \fBout\fR (output) parameters is also 235 generated so that the server code can eventually send a reply and provide the 236 appropriate reply data. See the \fBCOMPLETION OPERATIONS\fR section for more 237 details. 238 .TP 239 \fBoneway\fR 240 An indication that calls involving the given operation do not expect a reply. 241 .TP 242 \fBopcode(\fIopcode_value\fB)\fR 243 An operation code (opcode) applying to the given operation. Without a protocol 244 value applying to an interface, clients will specify the given 245 \fIopcode_value\fR as the message tag label when sending requests to the 246 interface. With a protocol, the \fIopcode_value\fR will be specified in the 247 first message word. 248 .TP 249 \fBopcode_type(\fIopcode_type_value\fB)\fR 250 An explicit type for the opcode applying to the given operation. 251 252 .SH SENDING RESULTS DURING OPERATIONS 253 .PP 254 Normally, results are communicated from operations by setting the appropriate 255 output parameter values. However, it is possible to send results in advance by 256 calling a completion function. Completion functions are generally made available 257 for all operations, regardless of whether the \fBcompletion\fR attribute is 258 specified. Such default completion functions merely provide a way of 259 communicating results. 260 .PP 261 Consider the following interface: 262 .in +4n 263 .nf 264 .sp 265 interface Calc 266 { 267 void pow(in double left, in double right, out double result); 268 }; 269 .fi 270 .PP 271 A client would employ an interface with an equivalent signature, something 272 like this in C: 273 .in +4n 274 .nf 275 .sp 276 Calc_pow(ref_Calc _self, double left, double right, double *result); 277 .fi 278 .PP 279 Here, the result is normally written to the address provided by the 280 corresponding parameter. However, the operation is also supported by another 281 function as follows: 282 .in +4n 283 .nf 284 .sp 285 complete_Calc_pow(double result); 286 .fi 287 .PP 288 Instead of using the \fBresult\fR output parameter in \fBCalc_pow\fR to return a 289 result value, this parameter can be ignored and the \fBcomplete_Calc_pow\fR 290 function used to send a response to the client, the result value being passed as 291 a parameter to this function. To prevent the server framework from attempting to 292 use the \fBresult\fR output parameter to send another response, a special value 293 is returned from the operation: 294 .in +4n 295 .nf 296 .sp 297 /* Complete the operation and send results. */ 298 299 complete_Calc_pow(result); 300 301 /* More work done. */ 302 303 return IPC_MESSAGE_SENT; 304 .fi 305 .PP 306 Unlike explicitly designated completion operations, results sent in this way 307 will be directed to the initiating client as a reply to its original request. 308 309 .SH COMPLETION OPERATIONS 310 Operations can be annotated with the \fBcompletion\fR attribute, indicating 311 that a client will initiate the operation with any parameters conveying input 312 values, with the completion of the operation being performed explicitly by 313 server code. Unlike regular operations, such annotated operations allow the 314 completion to involve another endpoint, as opposed to the client that initiated 315 the operation. 316 .PP 317 Consider the following interface: 318 .in +4n 319 .nf 320 .sp 321 interface Calc 322 { 323 void pow(in double left, in double right, out double result); 324 }; 325 .fi 326 .PP 327 This interface would be presented to the client for it to use when initiating 328 operations. 329 .PP 330 Now consider the following interface annotated with the \fBcompletion\fR 331 attribute: 332 .in +4n 333 .nf 334 .sp 335 interface CalcPrivate 336 { 337 [completion] void pow(in double left, in double right, out double result); 338 }; 339 .fi 340 .PP 341 Here, the operation exposed on the server would have the following signature: 342 .in +4n 343 .nf 344 .sp 345 CalcPrivate_pow(ref_CalcPrivate _self, double base, double exponent); 346 .fi 347 .PP 348 This function is not intended to communicate the result, and it even lacks the 349 appropriate output parameter. Instead, within the server code, a function of the 350 following form will need to be invoked: 351 .in +4n 352 .nf 353 .sp 354 complete_CalcPrivate_pow(l4_cap_idx_t _endp, double result); 355 .fi 356 .PP 357 Here, the result is communicated via the corresponding parameter, with the 358 indicated endpoint (\fB_endp\fR) receiving the reply. Where the endpoint is 359 the client that initiated an operation, the effect will be indistinguishable 360 from a normal invocation. However, where another endpoint is chosen to receive 361 the reply, the initiating client will effectively give up control to the client 362 employing the chosen endpoint, with that designated client assuming control 363 until such time that it calls the operation. Thus, this form of completion 364 operation permits a form of simple scheduling. 365 366 .SH COMPONENTS AND COMPOUND INTERFACES 367 Components may wish to support more than one interface, and this can be done 368 using composition, as illustrated below involving two interfaces: 369 .in +4n 370 .nf 371 .sp 372 interface \fIinterface_name\fR composes \fIbase_interface1\fR, \fIbase_interface2\fR; 373 .fi 374 .PP 375 Although inheritance might be employed to provide compound interfaces, the 376 combination or composition of interfaces is somewhat different: crucially, all 377 involved interfaces remain distinct and do not override each other (conflicts 378 between protocols and operation codes notwithstanding). 379 .PP 380 Base interfaces, these being interfaces used in composition to make a compound 381 interface, can be defined in the same file as the compound interface. 382 Alternatively, an \fBimport\fR statement can be used to import interface 383 definitions from another file, such files residing in the same directory as the 384 file currently being processed. For example: 385 .in +4n 386 .nf 387 .sp 388 import "calc.idl"; 389 import "counter.idl"; 390 391 interface \fICalcCounter\fR composes \fICalc\fR, \fICounter\fR; 392 .fi 393 .PP 394 Here, \fBcalc.idl\fR would provide \fBCalc\fR, and \fBcounter.idl\fR would 395 provide \fBCounter\fR. 396 397 .SH FILES 398 .B idl 399 reads all interfaces in a single input file and generates output files that 400 each contain the details of all of these interfaces. By default, output files 401 are written alongside their corresponding input files, but this behaviour can be 402 overridden with the \fB\-d\fR or \fB\-\-dir\fR options, choosing a specific 403 output directory for all files including compound interface files. 404 .PP 405 The following kinds of output files are generated for a file with a name of the 406 form 407 .IR name ".idl :" 408 .PP 409 .TP 410 .IR name "_client.c or " name _client.cc 411 contains the function definitions needed for the operations of all the 412 interfaces. 413 .TP 414 .IR name _client.h 415 contains the function declarations, signatures or prototypes for the 416 operations. 417 .TP 418 .IR name _interface.h 419 contains the function declarations, signatures or prototypes for the actual 420 operations; these are used by client and server code. 421 .TP 422 .IR name "_server.c or " name _server.cc 423 contains the function definitions needed to provide entry points for the 424 operations of all the interfaces. Where an interface is composed of other 425 interfaces, the function definitions will dispatch to these interfaces' own 426 functions. 427 .TP 428 .IR name _server.h 429 contains the function declarations, signatures or prototypes for the entry 430 points. 431 .PP 432 Where many input files are provided, 433 .B idl 434 processes each one in turn, generating a separate set of output files for each 435 input file. 436 .PP 437 Output files will only be produced corresponding to the indicated input files, 438 even if those files import other files. To generate output for the input files 439 together with the imported files, use the 440 .BR \-R " or " \-\-recursive 441 options. 442 443 .SH L4RE BUILD SYSTEM INTEGRATION 444 To be useful in the L4Re build system, the 445 .I idl4re 446 distribution should be made available with the name 447 .I idl4re 448 in the 449 .IR l4 " section (or " src/l4 " in earlier forms)" 450 of the general L4Re distribution. Rules can then be added to Makefiles to invoke 451 the tool and to produce source files that can then be compiled in the normal 452 way. A collection of Makefile-compatible files are provided in the 453 .I mk 454 directory within the 455 .I idl4re 456 distribution to provide such rules and to support the declaration of interfaces 457 and components. 458 459 .SH LIMITATIONS 460 There are probably far too many limitations to list here, but some notable 461 ones are provided below. 462 .PP 463 Error reporting is currently very minimal, providing the most basic parsing 464 error details from the scanner and parser. Obviously, this should be improved 465 to make the tool more usable. 466 .PP 467 Memory management is not comprehensive. However, this tool is meant to be run 468 for the duration of a given code generation task, not run as a service 469 indefinitely. 470 .PP 471 Validation of input is also minimal, with the tool mostly acting as a kind of 472 preprocessor, generating code that may then not behave exactly as intended, 473 although the code should be well-formed. 474 .PP 475 The \fBcompletion\fR and \fBoneway\fR attributes should be mutually exclusive, 476 and it should not be possible to use \fBinout\fR and \fBout\fR parameters on 477 operations annotated with the \fBoneway\fR attribute. However, these 478 restrictions are not currently enforced. 479 .PP 480 File inclusion is currently limited to loading files that all reside in the same 481 location, although include paths could be supported. 482 .PP 483 Things like modules and type definitions are not supported, these typically 484 being available in other languages describing interfaces. 485 486 .SH AUTHOR 487 Paul Boddie <paul@boddie.org.uk> 488 489 .SH RESOURCES 490 The project Web site: http://projects.boddie.org.uk/idl4re 491 492 .SH COPYRIGHT 493 Copyright \(co 2019, 2020, 2022, 2023 Paul Boddie <paul@boddie.org.uk> 494 .PP 495 This program is free software; you may redistribute it under the terms of 496 the GNU General Public License version 2 or (at your option) a later version. 497 This program has absolutely no warranty. 498 499 .SH SEE ALSO 500 .TP 501 CORBA: https://www.omg.org/spec/CORBA/ 502 .TP 503 DCE: http://www.opengroup.org/dce/ 504 .TP 505 DICE: https://wiki.tudos.org/Dice_IDL_compiler 506 .TP 507 IDL4: https://www.l4ka.org/downloads/idl4_manual.pdf