You must specially prepare a header file to generate the assembler include file. A pragma anywhere in the header file can enable assembler output:
#pragma CREATE_ASM_LISTING ON
The Compiler generates only those macro definitions and declarations subsequent to this pragma. The compiler stops generating elements when #pragma CREATE_ASM_LISTING: Create an Assembler Include File Listing occurs with an OFF parameter.
#pragma CREATE_ASM_LISTING OFF
Not all entries generate legal assembler constructs. The compiler does not check for legal assembler syntax when translating macros. Put macros containing elements not supported by the assembler in a section controlled by #pragma CREATE_ASM_LISTING OFF.
The compiler only creates an output file when the -La option is specified and the compiled sources contain #pragma CREATE_ASM_LISTING ON (refer the following listing).
#pragma CREATE_ASM_LISTING ON typedef struct { short i; short j; } Struct; Struct Var; void f(void); #pragma CREATE_ASM_LISTING OFF
When the compiler reads this header file with the -La=a.inc a.h option, it generates the following.
Struct_SIZE EQU $4 Struct_i EQU $0 Struct_j EQU $2 XREF Var Var_i EQU Var + $0 Var_j EQU Var + $2 XREF f
You can now use the assembler INCLUDE directive to include this file into any assembler file. The content of the C variable, Var_i, can also be accessed from the assembler without any uncertain assumptions about the alignment used by the compiler. Also, whenever a field is added to the structure Struct, the assembler code must not be altered. You must, however, regenerate the a.inc file with a make tool.
The Compiler does not create the assembler include file every time it reads the header file, but only when the header file changes significantly. Specify the -La option only when the compiler must generate a.inc. If -La is always present, a.inc is always generated. A make tool always restarts the assembler because the assembler files depend on a.inc. Such a makefile might be similar to the following listing.
a.inc : a.h $(CC) -La=a.inc a.h a_c.o : a_c.c a.h $(CC) a_c.c a_asm.o : a_asm.asm a.inc $(ASM) a_asm.asm
The order of elements in the header file is the same as the order of the elements in the created file, except that comments may be inside elements in the C file. In this case, the comments may be before or after the whole element.
The order of defines does not matter for the compiler. The order of EQU directives does matter for the assembler. If the assembler has problems with the order of EQU directives in a generated file, you must change the corresponding header file accordingly.