Re: Wrapping / Interfacing to C macros

["Warren W. Gay VE3WWG" <ve3wwg@cogeco.ca>]

Thierry Lelegard wrote:
>>I'm hoping someone has seen a dialect or pattern for interfacing to C
>>macros.  I need to use the ioctl() mechanisms of VxWorks to control
>>some low level features of a couple of serial cards.  I've never seen
>>any Ada applications wrapping up linguistic attributes such as the
>>following from Tornado/target/h/sys/ioctl.h :
>>
>>#define _IO(x,y)        (IOC_VOID|((x)<<8)|y)
>>#define _IOR(x,y,t)     (IOC_OUT|((sizeof(t)&IOCPARM_MASK)<<16)|((x)<<8)|y)
...
> 
> Well, there is a tradeoff between theoretical-intellectual exercise and
> practical-maintainabiliy-portability issue.
> 
> In the first case, you can mimic the macro definitions using plain Ada
> features.
> 
> However, the API specification is C-oriented and only defines the name of
> the C macro, not the way it is implemented (using nested macros like your
> examples, plain values, etc). We have noticed that different flavors of
> UNIX implement ioctl codes, for instance, in many different ways. So,
> your plain Ada code which mimics the C macros will not be portable (even
> between different versions of the same OS).
> 
> You will have the same problem with structures (like the stat/fstat structure).
> The UNIX API (POSIX, XPG, etc) defines the name of the structure, the names
> of _some_ fields in the structure and that's all. On different UNIXen, the
> number of fields is different, contains different fields in addition to the
> "standard" ones. Even the order and exact type (int, unsigned, short, etc)
> of the standard fields are different.
> 
> So, to interface the C UNIX API in a portable, maintainable manner, we use
> C jacket routines for each system routine which uses non basic types as
> parameters or with parameter values which depend on C macros (like the
> ioctl function code).
> 
> Thus, we have:
> - Portable C jacket routines (they respect the standard C API for system calls).
> - Portable interface between the C jacket routines and Ada (provided that
>   we only use types which have a direct mapping in Interfaces.C in the interface
>   of the jacket routine)
> - Portable Ada code.
> 
> As a rule of thumb:
> - If the information in C UNIX API standard (or man page) is sufficient to
>   write an Ada interface using types from Interfaces.C, we write a direct 
>   Ada interface.
> - If we need to look at the content of some .h file to write an Ada interface,
>   then we don't and we write a C jacket routine.
> 
> -Thierry Lelegard

I believe this is good advice, if you want portability. Any time
a macro is involved, it is simplest to deal with it in C terms,
and only provide the in/out parameters to "jacket routines" as
they were called above.

The only other alternative, when macros are used to produce
constants is to create a C main program to spit out Ada
source module(s) at make(1) time (you can produce enumerated
values for example).  This can be useful when
your goal is to arrive at only/mostly Ada95 code to be
included in the project.

There are two disadvantages with this approach however:

1. does not work well when variables are plugged into
    macros that evaluate to expression results.
2. enumerated type values must be sorted in ascending
    value order, requiring a bit more effort on the C
    code side. This is a requirement of the Ada "for"
    statement (at least it is for GNAT -- Ada language
    lawyers can advise on the rest ;-)
-- 
Warren W. Gay VE3WWG
http://home.cogeco.ca/~ve3wwg