1 .TH IDL "1" "2022-09-15" "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 .TP 250 \fBopcode_type(\fIopcode_type_value\fB)\fR 251 An explicit type for the opcode applying to the given operation. 252 253 .SH COMPLETION OPERATIONS 254 Operations can be annotated with the \fBcompletion\fR attribute, indicating 255 that a client will initiate the operation with any parameters conveying input 256 values, with the completion of the operation being performed explicitly by 257 server code. 258 .PP 259 Consider the following interface: 260 .in +4n 261 .nf 262 .sp 263 interface Calc 264 { 265 void pow(in double left, in double right, out double result); 266 }; 267 .fi 268 .PP 269 A client would employ an interface with an equivalent signature, something 270 like this in C: 271 .in +4n 272 .nf 273 .sp 274 Calc_pow(ref_Calc _self, double left, double right, double *result); 275 .fi 276 .PP 277 Here, the result is written to the address provided by the corresponding 278 parameter. When the client invokes the operation, it remains unaware of the 279 nature of the work done by the server: the operation acts like a typical 280 function call. 281 .PP 282 Now consider the following interface annotated with the \fBcompletion\fR 283 attribute: 284 .in +4n 285 .nf 286 .sp 287 interface CalcPrivate 288 { 289 [completion] void pow(in double left, in double right, out double result); 290 }; 291 .fi 292 .PP 293 Here, the operation exposed on the server would have the following signature: 294 .in +4n 295 .nf 296 .sp 297 CalcPrivate_pow(ref_CalcPrivate _self, double base, double exponent); 298 .fi 299 .PP 300 This function is not intended to communicate the result. Instead, within the 301 server code, a function of the following form will need to be invoked: 302 .in +4n 303 .nf 304 .sp 305 complete_CalcPrivate_pow(l4_cap_idx_t _endp, double result); 306 .fi 307 .PP 308 Here, the result is communicated via the corresponding parameter, with the 309 indicated endpoint (\fB_endp\fR) receiving the reply. 310 311 .SH COMPONENTS AND COMPOUND INTERFACES 312 Components may attempt to support more than one interface. Although inheritance 313 might be employed to achieve this, the combination or composition of interfaces 314 is somewhat different: crucially, all involved interfaces remain distinct and do 315 not override each other (conflicts between protocols and operation codes 316 notwithstanding). 317 318 .SH FILES 319 .B idl 320 reads all interfaces in a single input file and generates output files that 321 each contain the details of all of these interfaces. Apart from the compound 322 interface files, output files are written alongside their corresponding input 323 files. This behaviour can be overridden with the \fB\-d\fR or \fB\-\-dir\fR 324 options, choosing a specific output directory for all files including compound 325 interface files. 326 .PP 327 The following kinds of output files are generated for a file with a name of the 328 form 329 .IR name ".idl :" 330 .PP 331 .TP 332 .IR name "_client.c or " name _client.cc 333 contains the function definitions needed for the operations of all the 334 interfaces. 335 .TP 336 .IR name _client.h 337 contains the function declarations, signatures or prototypes for the 338 operations. 339 .TP 340 .IR name _interface.h 341 contains the function declarations, signatures or prototypes for the actual 342 operations; these are used by client and server code. 343 .TP 344 .IR name "_server.c or " name _server.cc 345 contains the function definitions needed to provide entry points for the 346 operations of all the interfaces. 347 .TP 348 .IR name _server.h 349 contains the function declarations, signatures or prototypes for the entry 350 points. 351 .PP 352 Where many input files are provided, 353 .B idl 354 processes each one in turn, generating a separate set of output files for each 355 input file. 356 .PP 357 For server components, compound interface files can also be produced with their 358 names chosen using the \fB\-C\fR or \fB\-\-comp\fR options. With a value of 359 \fIname\fR given with these options, files of the following form are produced: 360 .TP 361 .IR name _interface.h 362 contains a compound interface declaration (for C++ only) needed for the dispatch 363 mechanism to function, also to be used by the actual component implementing the 364 interfaces. 365 .TP 366 .IR name _interfaces.h 367 contains include statements referencing individual interfaces, needed by the 368 above compound interface declaration. 369 .TP 370 .IR name "_server.c or " name _server.cc 371 contains the function definitions needed to dispatch to the interfaces. 372 .TP 373 .IR name _server.h 374 contains the function declarations, signatures or prototypes for the dispatch 375 functions. 376 .PP 377 These files provide support for interpreting messages received by servers and 378 directing handling of such messages to interface-specific dispatch functions or 379 directly to functions acting as operation entry points. 380 381 .SH L4RE BUILD SYSTEM INTEGRATION 382 To be useful in the L4Re build system, the 383 .I idl4re 384 distribution should be made available with the name 385 .I idl4re 386 in the 387 .I src/l4 388 section of the general L4Re distribution. Rules can then be added to Makefiles 389 to invoke the tool and to produce source files that can then be compiled in the 390 normal way. A collection of Makefile-compatible files are provided in the 391 .I mk 392 directory within the 393 .I idl4re 394 distribution to provide such rules and to support the declaration of interfaces 395 and components. 396 397 .SH LIMITATIONS 398 There are probably far too many limitations to list here, but some notable 399 ones are provided below. 400 .PP 401 Error reporting is currently very minimal, providing the most basic parsing 402 error details from the scanner and parser. Obviously, this should be improved 403 to make the tool more usable. 404 .PP 405 Validation of input is also minimal, with the tool mostly acting as a kind of 406 preprocessor, generating code that may then not behave exactly as intended, 407 although the code should be well-formed. 408 .PP 409 Interface inheritance is not supported, neither are modules. Both of these 410 things are typically available in other languages describing interfaces. 411 412 .SH AUTHOR 413 Paul Boddie <paul@boddie.org.uk> 414 415 .SH RESOURCES 416 The project Web site: http://projects.boddie.org.uk/idl4re 417 418 .SH COPYRIGHT 419 Copyright \(co 2019, 2020, 2022 Paul Boddie <paul@boddie.org.uk> 420 .PP 421 This program is free software; you may redistribute it under the terms of 422 the GNU General Public License version 2 or (at your option) a later version. 423 This program has absolutely no warranty. 424 425 .SH SEE ALSO 426 .TP 427 CORBA: https://www.omg.org/spec/CORBA/ 428 .TP 429 DCE: http://www.opengroup.org/dce/ 430 .TP 431 DICE: https://wiki.tudos.org/Dice_IDL_compiler