Page 153 - Introduction to Microcontrollers Architecture, Programming, and Interfacing of The Motorola 68HC12

130 Chapter 5 Advanced Assemblers, Linkers, and Downloaders

5.5 Documentation

A significant part of writing large assembly-language programs is the effort to make the
program understandable to a programmer who has to debug it. Some tools to do this are
provided by state-of-the-art assemblers. Table 5.6 shows assembler directives that
significantly clarify assembler listings. The LIST and NOLIST directives can clean up a
listing by not printing parts of the program that are neither interesting nor informative.
CLIST and MLIST directives control whether conditional expressions and macros are
fully listed. Other directives, TITLE, LLEN, NOPAGE, PLEN, and TABS, control the
format of a listing, and PAGE and SPC tidy up a listing.
The INCLUDE directive permits other files to be inserted into a source code file.
The assembler saves the location after the INCLUDE directive, opens the file that is
named in the directive's operand, reads all of that file, and then returns to the saved
location to resume reading the file in which the INCLUDE directive appeared. Included
files can include other files but cannot eventually include themselves (the INCLUDE
directive is not recursive). It is common to include a file defining a program's constants,
in EQU directives, in each file that uses these constants. However, in such files, so that
they are included only once, the contents of an INCLUDE file might be written as
follows:

IFNDEF Fl
... (an entire file, except the three statements shown here)
Fl: EQU 0 ; it really doesn't matter what F1 is set to here
ENDC
The conditional statement will include the contents of a file the first time it is named as
the parameter of an INCLUDE statement. Subsequent INCLUDE statements will fail to
assemble the contents of the file because the symbolic name F1 will be defined after the
first time it is INCLUDEd.
Table 5.6. Listing Directives