home *** CD-ROM | disk | FTP | other *** search
/ Dream 44 / Amiga_Dream_44.iso / RiscPc / programmation / headerg.zi / HeaderGen / Doc < prev    next >
Text File  |  1996-02-07  |  11KB  |  284 lines
  1.  
  2.     HeaderGen 1.10
  3.  
  4.     Documentation
  5. ____________________________________________________________________________________
  6.  
  7.  
  8. HeaderGen is a coding tool for use with Acorn ANSI C and ObjAsm.
  9.  
  10. HeaderGen is (c) Frank F÷hl. This version is PD and may be copied freely, as long as
  11. all files are included and unaltered.
  12.  
  13.  
  14.  
  15.     Å Purpose:
  16.  
  17. Generate header files of C and Assembler source files, and generate C headers from
  18. Assembler sources as well as Assembler headers from C headers.
  19.  
  20.  
  21.  
  22.     Å Syntax:
  23.  
  24. HeaderGen -CtoC     [keyword args]  <C source>   <C header>
  25. HeaderGen -ASMtoASM [keyword args]  <ASM source> <ASM header>
  26. HeaderGen -ASMtoC   [keyword args]  <ASM source> <C header>
  27. HeaderGen -CtoASM   [keyword args]  <C header>   <ASM header>
  28.  
  29. Keyword options:
  30.  
  31. -ExtIdent <string>   Use <string> to identify external labels (with -ASMtoASM,-ASMtoC)
  32.                      or to identify external functions/variables (with -CtoC, -CtoASM)
  33. -I <dir>[,<dir>...]  Include <dir>s on the include file search path (with -CtoASM)
  34. -via <file>          Read extra command line parameters from <file>
  35.  
  36.  
  37.  
  38.     Å Limitations and known bugs
  39.  
  40. Parsing of C source files is not perfect (I haven't bothered to look up the syntax
  41. diagrams), but I think it's now fairly sufficient. If anything goes wrong with
  42. parsing C sources you will get errors or warnings from HeaderGen, as usual.
  43.  
  44. Bitfields are not supported.
  45.  
  46. It's possible in C, when declaring variables, to omit a type definition when a
  47. storage class is given, eg. to write "static counter;", where, I suppose, an "int"
  48. is assumed as default. HeaderGen can't cope with this, the type must be given.
  49. (There may be further such obscure abbreviations that aren't handled properly.)
  50.  
  51. Most preprocessor statements are ignored, only the #include's and #define's are
  52. recognized with the -CtoASM action (see below), the #define's only to a limited
  53. degree.
  54.  
  55. HeaderGen has no C++ support, but it parses '#ifdef __cplusplus' lines and ignores
  56. the contents of these conditional blocks.
  57.  
  58. HeaderGen -CtoASM parses all Clib and RISC_OSlib headers fine, with the exceptions
  59. 'kernel.h' (because a bitfield is used, urghh)
  60. 'signal.h' (hopelessly cryptic function pointer)
  61. 'colourpick.h' (silly bracketing)
  62.  
  63. The length of the words and low level syntax structures scanned in the input files
  64. is limited to 2048 characters, so there might be problems with very long explicit
  65. character strings for example. You'll get a 'word overflow' error if this occurs.
  66.  
  67. The number of words in a via-file is limited to 2048.
  68.  
  69.  
  70.  
  71.     Å How to use HeaderGen
  72.  
  73. All four actions have in common that the generated code is appended to the target
  74. file immediately after the first occurrence of the sequence '/* Auto */' (in C files)
  75. or '; Auto' (in ASM files), deleting everything following it. If the sequence is not
  76. found in the file, then it will be appended along with the generated code. The header
  77. file is generated if it isn't already there.
  78.  
  79. As there are a few serious limitations with parsing C sources, a method has been
  80. implemented to prevent critical sections of code from being parsed by HeaderGen.
  81. You can disable parsing by writing
  82.  
  83.     #define __headergen_stop
  84.  
  85. end re-enable parsing by writing
  86.  
  87.     #define __headergen_start
  88.  
  89. in a C source file. These statements act simply as markers for HeaderGen's scanner.
  90. Note that you don't have to write '#define __headergen_start' at the beginning, the
  91. entire file will be parsed by default.
  92.  
  93. The makefile skeleton shows how HeaderGen can be effectively incorporated into
  94. makefiles.
  95.  
  96. The following sections describe the four actions in detail.
  97.  
  98.  
  99.  
  100.     HeaderGen -CtoC
  101.     ===============
  102.  
  103.  generates prototypes of external functions and variables and appends them to the
  104. named C header. This is similar to Zap's MJE_GENERATEHEADER function, however,
  105. unlike Zap, HeaderGen can also handle external variables.
  106.  
  107. Functions and global variables are considered to be external if they contain the
  108. 'ExtIdent' string (see keyword options). This is to allow for global objects that are
  109. only visible within the program module where they are defined. The default ExtIdent
  110. string is the empty string, which will match any global symbol. If you wish to use
  111. this feature, then I'd recommend using the name of the program module as ExtIdent
  112. string, as shown in the sample makefile. You can then use this string as a prefix of
  113. your external symbols.
  114.  
  115.     Å One little problem with -CtoC
  116.  
  117. If you declare a (comma-separated) list of global variables of the same type, the
  118. ExtIdent string will only be checked against the first variable name. According to
  119. the result, the whole list is either 'extern'ed or not. If this causes inconvenience,
  120. split the list up into single <type> <var>; declarations.
  121.  
  122.  
  123.  
  124.     HeaderGen -ASMtoASM
  125.     ===================
  126.  
  127. appends all external labels defined in the ASM source to the ASM header, each preceded
  128. by an IMPORT/EXPORT directive. The directive is implemented as an Asm variable which
  129. is defined at the beginning of the header. This variable expands to 'EXPORT' if the
  130. Asm variable __<file>_s has already been defined, to 'IMPORT' otherwise, where <file>
  131. is the name of the program module. You need to write a 'GBLA __file_s' in every source
  132. file, before it 'GET's its own header, for the header to 'know' whether it is supposed
  133. to IMPORT or to EXPORT the external labels. They are EXPORTed when the header is
  134. included from its own source file, IMPORTed otherwise.
  135.  
  136. Consequently, you don't need to worry about importing or exporting externals, just
  137. sign your external labels as external, include the ASM header into its own source file
  138. and into any source file where the externals shall be visible, and everything's ok.
  139.  
  140. Labels found in the source file are considered to be external if they contain the
  141. ExtIdent string.
  142.  
  143. If additional 'EXPORT <label>' statements are present in the Asm source, then the
  144. corresponding 'IMPORT's will be appended to the header, regardless of the ExtIdent
  145. string, so even if you don't wish to use an external identifier string, you can still
  146. use -ASMtoASM. In this case you should disactivate the externals identification by
  147. using "-ExtIdent @@@" or something, thus no labels will automatically be considered as
  148. external.
  149.  
  150. $-prefixed symbols and lines with Asm directives are ignored by this operation.
  151.  
  152.  
  153.  
  154.     HeaderGen -ASMtoC
  155.     =================
  156.  
  157.  appends all external labels to the C header, preceded by 'extern'. A label is
  158. considered to be external, either if it contains the ExtIdent string or if it is
  159. explicitly EXPORTed.
  160.  
  161. If there's a comment of the form '; (<type>)' following the label, then <type> is
  162. considered to be the type of the object at the label's address. The default type
  163. is 'int'. If a comment of the form '; (<type>) (<arg0>,,,<argN>)' is found, then the
  164. label is converted to a function prototype with the given type and argument list, eg:
  165.  
  166.            this                    is converted to           this
  167. -------------------------------------------|------------------------------------------
  168. counter    DCD 0 ; (int)                   |     extern int counter;
  169.                                            |
  170. DotPlot          ; (void) (int x,int y)    |     extern void DotPlot(int x,int y);
  171.                                            |
  172.            EXPORT DrawLine ; (void) (void) |     extern void DrawLine(void);
  173.                                            |
  174.  
  175. Note that when 'EXPORT' is used, the (type) and (arg list) comments must follow the
  176. 'EXPORT' statement, and NOT be in the label definition line!
  177.  
  178. Storage areas, data structures and ASM directives are ignored. If you want to declare
  179. constants, or lay out data structures, then do it in a C header (that's the point of
  180. the entire program, BTW ;-)
  181.  
  182.  
  183.  
  184.     HeaderGen -CtoASM
  185.     =================
  186.  
  187. This is the most complex action. It is used to convert all 'typedef', 'struct',
  188. 'union' and 'enum' definitions and (to a limited degree) macro definitions within a
  189. C header into appropriate ASM code. It also IMPORTs all functions and variables that
  190. are signed as external in the C header.
  191.  
  192. The program recognizes enum/struct/union templates as well as typedefs. The templates
  193. are referred to in the ASM code with the prefixes 'struct_' or 'union_' or 'enum_'
  194. to avoid ambiguity. All 'typedef'd structures are laid out explicitly in Asm code,
  195. and all non-anonymous 'struct' templates as well, for example the C code
  196.  
  197.     typedef struct { int a,b; } dummy;
  198.  
  199. will generate the Asm code:
  200.  
  201.                     ^ 0    ; structure 'dummy'
  202.     |dummy.a|            # 4
  203.     |dummy.b|            # 4
  204.     dummy                * 8
  205.  
  206. but the C statements
  207.  
  208.     typedef struct dummy0 dummy;
  209.     struct dummy0 { int a,b; };
  210.  
  211. will generate two Asm structures, one for the struct template 'dummy0', and one for
  212. the typedef'd type 'dummy':
  213.  
  214.                     ^ 0    ; structure 'struct_dummy0'
  215.     |struct_dummy0.a|        # 4
  216.     |struct_dummy0.b|        # 4
  217.     struct_dummy0            * 8
  218.  
  219.                     ^ 0    ; structure 'dummy'
  220.     |dummy.a|            # 4
  221.     |dummy.b|            # 4
  222.     dummy                * 8
  223.  
  224. Structure members are aligned correctly, ie char's are byte-aligned, short int's
  225. are half-word-aligned and all the rest is word-aligned. Alignment gaps are inserted
  226. into the ASM structure code as appropriate. The size of structures is correctly
  227. rounded up to integers.
  228.  
  229. The members of enumerated data types may optionally have an expression assigned,
  230. which may contain hex and decimal integers and the operators + - * / % << >>.
  231.  
  232. Union members are not converted (as their offsets are all zero, if I've got it right).
  233. Thus the size of a union is declared as the maximum of its members' sizes.
  234.  
  235. The program tries to follow any '#include' directive present in the C header. All
  236. secondary headers are parsed, but only the main file's code is converted to Asm code.
  237. The secondary headers are looked for in the root directory, the work directory and in
  238. the directories specified by the '-I' arguments. Every header is included only once.
  239.  
  240.  
  241.     Å Macro Conversion
  242.  
  243. Numerical definition macros such as
  244.  
  245.     #define no 100
  246.     #define product (10*no/2)
  247.  
  248. are recognized and converted. The expression may contain hex and decimal integers
  249. and the operators + - * / % << >>. However things like
  250.  
  251.     #define size (10*sizeof(int))
  252.     #define BOOL int
  253.  
  254. won't do. In the latter case, a 'typedef int BOOL;' will do the job, or just replace
  255. the 'BOOL's by 'int's within the type definition header.
  256.  
  257. The program can also handle string definition macros such as
  258.  
  259.     #define text "some text"
  260.  
  261. which will be converted into an Asm string variable.
  262.  
  263. All function and expression macros are ignored.
  264.  
  265. Macros are recognized as array dimensions (relevant when converting array typedefs,
  266. for example), but ONLY IF THEY EXPAND TO A SINGLE INTEGER. More complex expressions
  267. won't do.
  268.  
  269.  
  270.  
  271.     *  *  *
  272.  
  273. This piece of code is quite hard to debug, so I would appreciate any bug reports
  274. in particular, of course any suggestions too. To contact me mail to
  275.  
  276. foehlfk@tick.informatik.uni-stuttgart.de
  277.  
  278. or snail to
  279.  
  280. Frank F÷hl
  281. Siemensstr. 7
  282. 71636 Ludwigsburg
  283. Germany
  284.