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