[Gm2] generating definition modules from C header files

[Gaius Mulley]

Hi,

finally I've finished the first cut of `h2def'. Below is the
documentation from gm2.info. `h2def' has quite a few limitations (see
below) but it does perform (at a guess) 90% of the task.  Some current
examples are vga.h and pthread.h (although pthread.h was modified
quite a lot). I've included these modified header files in
gm2/m2/comp/autotest/gm2/vga.h gm2/m2/comp/autotest/gm2/pthread.h

To examine the output try:

h2def -Igcc-3.2/gcc/gm2/m2/comp/autotest/gm2 \
        gcc-3.2/gcc/gm2/m2/comp/autotest/gm2/pthread.h

and 

h2def -Igcc-3.2/gcc/gm2/m2/comp/autotest/gm2 \
        gcc-3.2/gcc/gm2/m2/comp/autotest/gm2/vga.h

They both include system files of which a few dummy ones are also in
gcc-3.2/gcc/gm2/m2/comp/autotest/gm2/ some of the contents of these
files maybe non portable or wrong.

Some of the plus points of h2def are that it understands

void * = ADDRESS
unsigned int = CARDINAL
long unsigned int = LONGCARD
unsigned int = LONGINT
char = CHAR
char * = ARRAY OF CHAR
struct/typedefs = translated (unions not yet)
pointers to functions = translated
var args also translated
type *foo can be translated to ARRAY OF type

Large caveat: I've only just finished the first cut and documentation
and not yet tested these definition modules with gm2 - hence there
are probably problems - but I'd rather "release early and often"
(patches welcome :-)

enjoy,

Gaius

ps. I'll upload these changes to CVS tonight


Semi-automatic translation of C header files
============================================

   The tool `h2def' can be used to semi-automatically generate
`DEFINITION MODULE FOR "C"' modules. The tool takes as input a C header
file and generates as output a corresponding textual definition module.
While the tool will not automatically translate complex C header files
it will generate definition modules for simple header files.

   For example consider the following header file (`header.h'):

     #define MYTYPE void *
     
     extern MYTYPE h;
     
     #define LIMIT  1000
     #define FOOBAR (1+MAXIMUM)
     
     int *p, ch;
     
     extern MYTYPE func (void (*funcarray)(int, char));
     
     struct mumble {
       char *name;
       void *addr;
       struct mumble *next;
       void (*arrayfunc[5])(int, char);
     } *mylist;

   Using the following command line `h2def header.h' will generate the
module below:

     DEFINITION MODULE FOR "C" header ;
     
     VAR
        h: ADDRESS ;
     
     CONST
        LIMIT = 1000 ;
        FOOBAR = (MAXIMUM) + ( 1) ;
     
     VAR
        p: POINTER TO INTEGER ;
        ch: INTEGER ;
     
     PROCEDURE func (__gm2param0: funcarray) : ADDRESS;
     
     TYPE
        funcarray = PROCEDURE (INTEGER, CHAR) ;
     
     VAR
        mylist: POINTER TO mumble; (* var *);
     
     TYPE
        mumble = RECORD
                    name: POINTER TO CHAR ;
                    addr: ADDRESS ;
                    next: POINTER TO mumble ;
                    arrayfunc: ARRAY [0.. 5-1] OF PROCEDURE (INTEGER, CHAR) ;
                 END ;
     
     END header.

   The main limitation of `h2def' is in the preprocessing handling.  It
does not understand the C preprocessor token constructor directives `#'
and `##'.

   Support for the `#define' mechanism is limited. Initially the macro
is parsed to check whether it is a constant expression.  If it fails it
is reassigned as a macro definition.  A macro which contains C
statement code cannot be translated into a definition module. These
macros and all dependents are poisoned and are not translated.

   The `-I' option to `h2def' allows include directories to be
specified and the `-C' option states that a macro definition must be
computed at compile time.  For example consider the following header
file:

     #if !defined(FOOBAR)
     # define FOOBAR
     # define MAXIMUM 1000
     #endif

   which if processed by `h2def -CFOOBAR' yields the following code:

     DEFINITION MODULE FOR "C" ifdef ;
     
     # if (!(defined(FOOBAR)))
     CONST
        MAXIMUM = 1000 ;
     # endif
     
     END ifdef.

   The `-a' option provides a method whereby the C parameter construct
`sometype *foo' is translated in Modula-2 as `foo: ARRAY OF sometype'.

   Normally output for `h2def' will require some manual intervention.
Some header files need more help than others, for example the GNU/Linux
svga header file `vga.h' requires a little help whereas the GNU pthread
file `pthread.h' requires more.  Nevertheless the effort required is
much less than writing the modules by hand.