IDL4 Manual
Contents
1. hi This means that the method file open can in addition to system exceptions raise two user defined exceptions named access_denied and not_found CORBA also allows exceptions to contain additional information for example it may be useful to add a message for the user or details on how to correct the error Here is an example interface file DCE exception handling exception access_denied not supported string reason int missing _privileges void open in string name raises access _denied hi Note Currently IDI only supports exceptions without additional information 1 4 Constants It is possible to define constants within an interface The constants are added to the generated header files but may also be used within the specification itself Consider the following example interface too interface too const int addr size 6 const int addr size 6 struct hwaddr struct hwaddr octet macladdr_size unsigned small macladdr_size he y ky ki This causes a constant named addr_size to be exported to the client header file also the struct hwaddr is declared to be six bytes long 15 Attributes 1 5 1 Oneway functions Usually a remote procedure call consists of two phases A send phase in which the client sends a message to the server and a receive phase in which it waits for a reply However in some cases it is necessary to omit the second phase e g when the request is2. Lin length_is len float addr yi void xyz Lin length is 5 J short addr yi hi The stub code for bar transfers len floating point numbers starting at addr whereas the code for xyz always transfers five 16 bit integers On the server side buffer space is allocated and freed by the stub code In particular for out arguments the stub preallocates enough buffer space and passes a pointer to it when the function is invoked Neverthe less your code is not required to use this buffer it can save one copy operation by returning a pointer of its own On the client side the stub allocates buffers for output values but does not free them It is your respon sibility to invoke CORBA_free for every array that is returned by the server Note that the argument to length 1s denotes the number of elements not the size in bytes Structs Structs are used exactly like their counterparts in C C struct some_t short a 4 bj float c y struct some t short a 4 bj float c The stub allocates and frees buffers for the server on the client side this is the responsibility of the user However CORBA_alloc is not used because structs have a fixed size instead for an out parameter the user supplies a pointer to an existing struct which is then overwritten by the stub Unions Unlike C C style unions a CORBA compliant union needs a special member the discriminant which is used to decide which type the union
3. by a zero byte the third one ends with a 16 bit zero value On the server side strings are managed by the stubs For output values sufficient buffer space is al located before the method is invoked however the implementation is free to move the pointer to another buffer On the client side the stubs allocate output buffers using CORBA_alloc but do not free them it is the responsibility of the user to invoke CORBA_free for each one Fixed point CORBA includes a special type for fixed point BCD coded numbers This type is not supported by IDI Bitfields IDL supports C C style bitfields These are allowed neither by CORBA nor by DCE and should be used with care because they are highly platform dependent Consider the following example struct msgdope_t struct msgdope t long cc 8 long cc Be long parts 5 long parts 5 long mwords 19 long mwords 19 y y 1 3 Exceptions Currently only the CORBA exception handling is supported by IDL In CORBA there are two classes of exceptions system and user defined System exceptions may be raised by any method e g when the IPC fails or a timeout happens whereas user defined exceptions must be explicitly specified by the interface description Consider the following example interface file DCE exception handling exception access_denied not supported exception not_found void open in string name raises access_denied not_found
4. currently contains This is important because different types are usually marshalled differently Consider the following example union U switch int union U switch int a case 1 long x case 1 long x case 2 case 2 case 3 string sj case 3 string sj default char c hi hi Ifthe discriminant which is always named _d in CORBA has the value 1 then one 32 bit value needs to be copied When _d is 2 or 3 however the union contains a pointer which must be dereferenced resulting in a string to be transferred Note Unions are not yet available in the current IDI release However C C style unions are supported Such a union is always copied directly and entirely thus it may not contain types with special semantics such as strings default char c Strings CORBA supports 8 bit and 16 bit strings with an optional length bound strings are always terminated by the value zero Consider the following example typedef string lt 20 gt s20_t interface foo void bar in string a inout s20_t b out wstring lt 40 gt c I Y No bounded strings in DCE interface foo void bar in string char a in out string char b out string short c I The first argument to foo bar is an 8 bit string of arbitrary length whereas the second argument may contain at most 20 characters the third argument is a 16 bit string of not more than 40 elements The first two arguments are terminated
5. from the IDL file Generate debug output for the semantical analysis and consistency check Dump the C abstract syntax tree Print the function ID assignment Show details about the marshalling stage Analyze the stub generator and the backend Generate debug info while importing C headers Show details when reordering parameters Add debug output to the server stubs All ofthe above Allows IDL4 to use a non conforming IPC system call where avail able The resulting code is faster but may not be entirely compliant with the kernel specification For example the X0 1A32 backend may use sysenter to invoke the IPC system call Enables support for local IPC on X0 style kernels Use ANSI C types instead of the platform independent CORBA types like CORBA long Assume the frame pointer is not used This option must be consistent with the corresponding gcc option Allows IDL4 to use dynamic memory allocation e g CORBA_alloc This is enabled by default if you disable it you must preallocate buffers for all variable sized output parameters such as sequence or string Prevents files from being generated if they do not contain any code This is enabled by default In server templates removes all definitions except server loops In server templates generate code only for interfaces that are defined in a module These options can also be disabled by using a no prefix e g Eno fastcall 3 1 5 Preprocessor Option
6. information related to the call such as a timeout value or a memory window for receiving mappings You must initialize this structure before invoking the call An invocation of readin could look like this include lt storage_client h gt void test 14_threadid_t server CORBA Environment env id14 default environment short pos 100 char buf storage textfile readln server amp pos amp buf amp env switch env _major case CORBA_SYSTEM_EXCEPTION printf IPC failed code d n CORBA exception id senv CORBA exception free amp env return 1 case CORBA USER EXCEPTION printf User defined exception CORBA exception free amp env return 1 case CORBA NO EXCEPTION break printf Read s n buf CORBA_free buf r Note how env is initialized with an IDI supplied default value which means a timeout of infinity and an empty receive window Also the example shows how environment structure can be used to determine whether an exception occurred during the call and what type it was Finally it is important to always release storage allocated by the stubs e g exceptions output strings with the appropriate function 2 3 Processing requests The standard server loop which is included in the server template mainly consists of two macros e idl4_reply_and_wait which sends any pending replies and then receives one incoming re q
7. interface foo local interface foox short bar short bar in short a in short a in short b in short b yi yi hi hi The local attribute indicates that the methods in this interface will only be called via lipc This permits IDI to apply considerably more optimizations for example lipc will be used by both client and server stubs and parameters may be passed by reference Possible applications include semaphore servers or dispatcher threads which are used for distributing incoming requests to multiple worker threads in the same address space Note This is an experimental feature in the current release 1 6 2 Type import from C code Usually interface specifications should contain definitions for the data types they use However it may sometimes be convenient to import additional data types from the application code IDI supports this with a DCE style import statement interface foo interface foo import 14 x86 types h import 14 x86 types h void bar in 14 taskid t tid void bar in 14 taskid t tid hi hi This makes available the types defined in 14 x86 types h to all the methods in interface foo IDL contains a gcc compatible C parser for this purpose At compile time the header file is scanned all global type definitions are imported and converted into IDL Note that unlike types defined directly in IDL the generated header files do not contain definitions for imported types instead an include
8. that every parameter has a directional attribute in inout or out This is used to indicate whether the parameter contains e input data which must be copied from client to server e output data which is returned by the server or e acombination of both Another difference is the presence of special data types like st ring which have additional semantics for example st ring stands for a sequence of characters with a trailing zero and sequence denotes an array of variable length These special types are explained later in this chapter Finally it is possible to avoid naming conflicts by putting interfaces into modules For example a network driver and a postal application might both want to provide a packet interface possibly with different methods this conflict can be resolved by using two separate modules 7 1 2 Types 1 2 1 Basic types Integers IDL supports the following CORBA integer types Type name Size Value range unsigned short 16 bit 0 65535 short 16 bit 32768 32767 unsigned long 32 bit 0 4294967295 long 32 bit 2147483648 2147483647 unsigned long long 64 bit 0 18446744073709551615 long long 64 bit 9223372036854775808 9223372036854775807 The type int is also supported although it is deprecated because the standard does not define its size 32 or 64 bit Currently it has 32 bit on all platforms Floating point The following floating point types are availa
9. the end of the function This macro makes the function accessible to the server loop for the optimizations to work it is also very important that this macro is included after the implementation function Unlike the client side memory allocation on the server side is mostly handled by the stub code that is you do not need to call CORBA_free except if you explicitly allocated additional buffers The stub code preallocates a buffer for every out value and passes a pointer to the implementation function in the respective argument However for large buffers such as strings you can save one copy by overwriting the pointer with another one pointing directly to the data you want to send If you decide not to send a reply at all you can use the id14_set_no_response function In this case the stub code will discard any inout or out values and skip the send phase instead it will directly receive another request Chapter 3 Ouick reference guide 3 1 Invoking IDL IDL is generally invoked in the following way id14 OPTIONS input idl The following sections contain a more detailed description of the individual options 3 1 1 Overall Options o filename c h filename h 3 1 2 Warning Options Wprealloc Wall These options are used to control the kind of output The following output types are available e Client stubs c are used by client tasks to invoke a service e Server stubs s contain functions to receive and
10. 14 ix0 pia32 ffastcall s pager idl h pager server h generates a header file called pager server h which contains all the server stubs for methods in pager idl Also the XO backend for the IA32 platform is selected e g because the application will use the Hazelnut kernel and run on a Pentium III processor Finally the fastcall option is given which allows IDL to use nonstandard system calls in this case the sysenter instruction 2 2 Sending requests As specified by the CORBA C language mapping 2 client stubs have two implicit parameters i e param eters that are not defined by the interface Consider the following example module storage library storage interface textfile interface textfile void readin void readin inout short pos lin out short pos out string line out string char line yi hi hi y 15 When this definition is compiled with the c option IDL creates the following client stub void storage textfile readln storage textfile service CORBA short pos CORBA char line CORBA Environment env The first parameter service contains the thread ID of the server where the reguest is to be sent Unlike other CORBA code generators IDL does not provide a way to obtain this automatically it assumes that this functionality is implemented by your system The last parameter is apointertoa CORBA Environment structure This structure contains additional
11. A dat 16 3 Quick reference guide 19 A A KAN don neh kw au Oon bu wak an it tem ode 19 3 1 OveralkOptiOnS ey x os dad AN Gee des 19 3 1 2 Warming Options somos serene heb Oh ee Read Kd 19 3 1 3 Debugging Options 2 2 Common nee 20 3 1 4 Miscellaneous Options 0 0 00 ee ee 20 3 1 5 Preprocessor Options ee 21 3 1 6 Target Options seas eae bb e ema 21 4 Appendix 23 4 14 Keywords run ara an a Sk ae re na de AL A EN ai ok dn MAL Ra mat hed 23 4 2 Supported platforms cuts was Mulan bean BL AANG beta Saw UP bahas 23 4 3 Supported types is rosei nan a na e E RAN AN ana A a 24 Chapter 1 Writing interface definitions 11 Basic structure The specification in an IDL file describes one or more interfaces which in turn may contain one or more methods Here is an example module storage library storage interface textfile interface textfile void readin void readin inout short pos in out short pos out string line out string char line void writeln void writeln inout short pos in out short pos in string line in string char line int get_pos int get_pos yi yi y IDL supports two specification languages CORBA IDL and DCE IDL so most example code is shown in both languages the CORBA code is always on the left side Note that the syntax is very similar to C C especially in the case of DCE IDL The most important difference is
12. IDL Version 1 0 0 User s Manual Andreas Haeberlen University of Karlsruhe haeberlen ira uka de April 2003 Preface This manual is still under construction More information on the technology used in IDI can be found in 3 for more details on CORBA IDL please read 1 or one of the countless books on CORBA e g 7 Contents 1 Writing interface definitions 7 Il B sic str ct re a ve See oP oe Mena OP EN BEN ad 7 1 2 YES 28 te e a Oe er ED ee erde Bus a dee lee nee 8 1 2 1 gt Basie types arau ran A Baal an BE SNN ade hd 8 1 2 2 Constnicted types Bra A dow Ba SN LNG LT ANN tc 9 1 3 gt Exceptions 22 4 Tan aa ea an Bir gel 11 1 4 Constants 2 ties ae a E ee HE ee Ana a On ba 11 1 5 Attributes o ace ee ee Ba na BEN EN Rb Baba ana ea a re 12 15 1 Oneway functions nenn Un RERE rare ana 12 1 52 Function identfiers z u 2 cra Wate BEN Er EN na AN ap 12 1 3 3 Mapping Ipages ida nana DE ee e ide 13 1 6 Advanced features saja 2221 aa RA ea and 13 1 6 1 Local functions ota want a lau Seb as BA eh ed oe ee ode Balan te dad 13 1 6 2 Type import from C code Common 13 1 6 3 Disabling the memory allocator 0 o o e e 14 1 6 4 Receiving kernel Messages e 14 2 Working with generated code 15 2 1 Compiling the IDL file gt vota A a eS 15 2 2 Sending TEquests eo aa ao aa al hate 15 2 3 PrOCESSINE TOQUES S oo 8 ro ae Tiban en a A Aa aud AA
13. a void bar in int a hi hi You can also change the assignment of method numbers by applying the uuid attribute to individual methods However this is rarely necessary 1 5 3 Mapping fpages The L4 IPC primitive supports mapping which is essentially the transfer of a complete memory page from one address space to another As a result the page is shared by both address spaces write operations in either of them are instantly visible in both Also the page may cover the same address range in both spaces but this is not mandatory IDL supports this primitive with a special data type the fpage which describes a memory region see 4 5 8 for more details fpages are implicitly mapped during message transfer the mapping persists and is not revoked upon completion of the call Consider the following example interface pager interface pager uuid 0 1 uuid 0 1 void pagefault void pagefault in int addr in int ip in long addr in long ip out fpage out fpage f ji yi y y This defines a method pagefault which takes two arguments the fault address addr and the instruc tion pointer ip the server replies with an fpage which is to be mapped to the client address space 1 6 Advanced features 1 6 1 Local functions Some L4 microkernels support a special IPC primitive the local IPC or lipc which is optimized for intra address space calls 6 This feature can be used with IDL as follows local
14. ble Type name Size Value range Precision float 32 bit 3 403 1088 6 digits double 64 bit 1 798 10208 15 digits long double 80 bit 1 1897 101982 18 digits Characters IDL supports both the 8 bit char and the 16 bit wchar data types The type unsigned char may also be used but it is deprecated The reason is that in CORBA IDL characters have special semantics for example they might be translated to a different character set by the marshalling code If you need an 8 bit data type for binary data you should use the octet type Flexpages IDL supports the L4 mapping primitives by providing a special type named fpage This type corresponds to the flexpage type of the respective kernel interface its size is platform dependent Miscellaneous Type name Size Possible values boolean 1 bit true false octet 8 bit 0 255 void undefined none The void data type may only be used for return values or as the base type for a pointer The Object and any types which are also defined by CORBA are not supported 1 2 2 Constructed types Alias types You can use typedef to create your own types typedef unsigned short word_t typedef unsigned short word_t typedef string lt 40 gt max40char_t Bounded strings not supported typedef long array_t 4 3 typedef long array_t 4 3 IDL maps the types in an interface description to the target language and adds a definit
15. directive referring to the original file is added 1 6 3 Disabling the memory allocator By default IDL uses CORBA style dynamic memory allocation i e it calls CORBA_alloc to reserve buffers for variable length output values In some cases however the data is expected at a specific location which requires an additional copy on the client side To avoid this problem you can use the prealloc attribute Consider the following example interface foo interface foo typedef sequence lt long 100 gt buf void bar void bar out prealloc length_is len prealloc out buf x char data out short len yi yi hi hi No dynamic buffers are allocated in either case Instead you must explicitly provide a buffer by initial izing x _buffer or data respectively Also you must supply the size of the buffer in x maximum or len in the DCE example While prealloc should be used for individual arguments a command line option is also available which disables dynamic allocation for the entire file 1 6 4 Receiving kernel messages In the L4 world exceptions are mapped to IPCs which are sent by the kernel on behalf of the faulting ap plication e g to its pager These messages can be received by IDL stubs when special interface definitions are used The following interface handles X0 style page faults which are e g generated by the Hazelnut kernel interface pager interface pager uuid 0 void pagefault uu
16. dispatch in coming requests on the server side e Server templates t can be used as a starting point when im plementing a new service They contain function prototypes and a simple server loop Place code output in filename c Note that for some mappings the stub code is contained entirely in the header files Create a header file called filename h This option cannot be used together with t because server templates do not include a header file Print the version number and build date on standard output Warn whenever a stub needs to allocate an excessive amount of heap memory e g when an unlimited output string is encountered All of the above W options combined 19 3 1 3 Debugging Options dtest dparanoid dcpp daoi dcheck dceast dfids dmarshal dgenerator dimport dreorder dvisual gt d 3 1 4 Miscellaneous Options ffastcall flipc fctypes fomit frame pointer fuse malloc fomit empty files floop only fmodules only Generate test code When used with t this creates a test applica tion that can run as a root task on the bare microkernel The code creates a server for each interface in the IDL and then invokes every operation with random parameters Add even more checks to the test code For example test for stack overflow and monitor the message dopes Print each input line as it is read from the C preprocessor Dump the abstract syntax tree generated
17. id 0 void pagefault in long addr in long addr in long ip in long ip out fpage p out fpage p yi yi hi hi Here is how a V4 page fault is specified e g for the Pistachio kernel interface pager interface pager kernelmsg idl4 pagefault kernelmsg idl4 pagefault void pagefault void pagefault in long addr in long addr in long ip in long ip in long privileges in long privileges out fpage p out fpage p yi yi hi hi Note that in this case the fault type i e the reguested privileges is provided as a separate argument whereas in the upper example it is encoded in the lower two bits of the fault address Chapter 2 Working with generated code 2 1 Compiling the IDL file IDL can generate three types of output from a given interface description e Client stubs which are linked with every client application i e every application that needs to invoke methods from the interface e Server stubs which are used by every server that needs to implement the interface e Server templates which essentially contain a dummy implementation for the interface They can be used as a starting point for writing a server Usually the first two Kinds of output are generated during the compilation process whereas the third is only generated once and then extended with user code You can select the kind of output by supplying c s or t on the command line respectively For example id
18. ion to the header files it produces Thus you can also use these types in your own code Sequences CORBA provides a special type for transferring variable length data the sequence type A sequence has a base type e g char and optionally a size bound Consider the following example typedef sequence lt float 7 gt some_t DCE IDL does not support typedef sequence lt char gt another_t the sequence type The first line defines an array of floats that does not contain more than seven members but may contain less the second line defines a character array of arbitrary size Note that sequences may only appear in typedefs not directly as an argument type When using sequences please consider that IDI needs to preallocate buffer space for them Providing a tight size bound saves memory and considerably improves performance Note that the sequence mapping in IDL differs from the one specified in 2 In the IDI mapping the programmer is always responsible for the storage allocated for output sequences the release flag is not supported Also output sequence parameters do not use double indirection instead they are treated just like ordinary structs Arrays In DCE there is no single type for variable length arguments Instead size and location of the data are specified independently Consider the following example CORBA does not support interface foo the length_is attribute void bar in int len
19. ns Platform Interface Current status X0 Supported IA32 V2 Supported no mapping V4 Supported X0 Supported Generic V2 Supported no mapping V4 Supported 23 4 3 Supported types Basic data types short signed 16 bit integer supported long signed 32 bit integer supported long long signed 64 bit integer supported unsigned short unsigned 16 bit integer supported unsigned long unsigned 32 bit integer supported unsigned long long unsigned 64 bit integer supported float floating point 32 bits supported double floating point 64 bits supported long double floating point 80 bits supported char 8 bit character supported wchar 16 bit character supported boolean boolean value supported any wildcard type octet unsigned 8 bit integer supported enum enumeration supported ref pointer supported fpage memory flexpage supported fixed fixed point decimal Constructed Types string unbounded string supported string lt n gt bounded string supported wstring unbounded wide string supported sequence lt type gt type sequence supported sequence lt type n gt bounded type sequence supported struct structure flat members supported union union DCE style supported Object object reference supported array array supported typedef alias type supported exception exception memberless exceptions sup
20. ported Bibliography 1 2 3 4 5 6 7 8 Object Management Group CORBA 2 6 specification http www omg org cgi bin doc formal 01 12 35 Object Management Group CORBA C language mapping http www omg org cgi bin doc formal 99 07 35 Andreas Haeberlen Jochen Liedtke Yoonho Park Lars Reuther and Volkmar Uhlig Stub code performance is becoming important In Proceedings of the First Workshop on Industrial Experiences with Systems Software WIESS pages 31 38 San Diego CA October 2000 Jochen Liedtke Lava nucleus reference manual http 130www ira uka de publications pub1998 1n 86 21 ps March 1998 Jochen Liedtke L4 nucleus version X 0 reference manual http 14ka org documentation files 14 86 x0 ps September 1999 Jochen Liedtke and Horst Wenske Lazy process switching In Proceedings of the 8th Workshop on Hot Topics in Operating Systems Elmau Germany May 2001 Jens Peter Redlich CORBA 2 0 Addison Wesley 1996 The L4Ka Team L4 X 2 reference manual http 14ka org documentation files 14 x2 pdf January 2002 25
21. s D macro I path Wp option with cpp path 3 1 6 Target Options m mapping i interface p platform w wordsize sys prefix path Defines macro in the preprocessor Adds path to the current include path The include path is passed to the preprocessor and is also searched when importing types Passes option directly to the preprocessor Use another preprocessor the default is usr bin cpp When generating stub code use the specified mapping C or C Produce code for the specified kernel interface Optimize for the specified platform generic is allowed Specifies the word size in bits 32 or 64 where it cannot be deter mined from the platform e g in the generic backends Add a prefix to all system include files Chapter 4 Appendix 41 Keywords The following strings are reserved as keywords and should not be used for identifiers all caches float nocache switch any gather noxfer TRUE attribute import Object typedef base is in octet union boolean include oneway unsigned case inout out uuid char int raises void const interface readonly wchar context 11 only ref writeable default length is scatter wstring double library seguence enum local short exception long size is FALSE max size string fixed module struct 42 Supported platforms This table shows the current status of the individual IDL backends You can select one of these backends with the i and p optio
22. to be processed asynchronously or when no reply is possible Here is how this behaviour can be specified interface foo interface foo oneway void bar in int a oneway void bar in int a hi hi Oneway methods must not have inout or out arguments also they may neither return a value nor raise any exceptions Note that when the method returns on the client side the absence of exceptions does not mean that the request has been processed successfully it only indicates that the request transfer did not fail 1 5 2 Function identifiers As interfaces can contain multiple methods and servers may implement multiple interfaces the server must be able to tell from the request which method it is intended for In IDL this is accomplished with numeric function IDs A function ID has two parts An interface number and a method number The interface number is identical for all methods in an interface whereas different interfaces may be assigned the same number The method number must be unigue within an interface By default IDI assigns the number 0 to all interfaces this implicitly assumes that different interfaces are implemented by different threads If this is not the case you need to assign the interface numbers manually The allowed range for interface numbers is platform dependent typically numbers of up to 1 000 are supported Here is an example uuid 5 uuid 5 interface foo interface foo void bar in int
23. uest and e idl14 process reguest which analyzes the request and calls the appropriate implementation function Between those macros you can insert additional code e g a permission check The second macro uses a function table to decide which function should handle the reguest it takes the method number as an argument and uses it as an index into the table Table entries which correspond to unassigned method numbers contain a reference to the discard function of the interface thus this function is only called when a malformed request was received The server template file also contains function templates for every method in the interface For the example interface from above the following template is created IDL4 INLINE void storage textfile readlin implementation CORBA Object _caller CORBA short pos CORBA char line idl4 server environment _env implementation of storage textfile readln return H IDL4 PUBLISH STORAGE TEXTFILE READLN storage textfile readlin implementation Similar to the client side the function has two additional parameters The first parameter _caller contains the ID of the thread that has sent the request whereas the last parameter _env points to an internal data structure Many functions in the IDL runtime need a pointer to this structure for example the function CORBA_exception_set which is used to raise exceptions Please note the macro at
Download Pdf Manuals
Related Search