378 lines
14 KiB
Groff
378 lines
14 KiB
Groff
.TH asl 1
|
|
|
|
.SH NAME
|
|
.B asl \- cross assembler for microprocessors and -controllers
|
|
|
|
.SH SYNTAX
|
|
.B asl
|
|
[ option(s) ] file(s) [ option(s) ] file(s) ...
|
|
|
|
.SH DESCRIPTION
|
|
|
|
AS is a cross assembler that can be used to write assembler programs
|
|
for a variety of different microprocessors and -controllers.
|
|
.B asl
|
|
is the UNIX/C implementation of AS. A complete description of AS is
|
|
far beyond the scope of this manual page, which is only intended as
|
|
a quick reference for AS's command line interface. For a more detailed
|
|
introduction into the usage of AS, see the user's manual.
|
|
|
|
.SH COMMAND-LINE PARAMETERS
|
|
|
|
Every argument that starts with a slash (/), plus (+) or minus (-) sign
|
|
is regarded as a command-line parameter. Some command-line parameters
|
|
take an argument as additional parameter. Every argument that is not
|
|
recognized as a command-line parameter is regarded as an assembler source
|
|
file to be assembled. A source file name that does not have an extension
|
|
is automatically extended with the default extension '.asm'.
|
|
Options are turned on with a parameter starting with
|
|
a slash (/) or minus sign (-), whereas a parameter with a leading plus sign
|
|
(+) turns an option off. In the following list, all options will be shown in
|
|
the form that is needed to change the default behaviour, which might be a
|
|
plus or minus sign, depening on wether the option is on or off by default.
|
|
|
|
.B asl
|
|
accepts the following command-line parameters:
|
|
.TP
|
|
.B -A
|
|
|
|
Change the data structure that is internally used to store the symbol table.
|
|
By default, AS uses binary trees to store macro and symbol definitions. Turning
|
|
this option on will change this to AVL-balanced trees. Depending on the ratio
|
|
of symbol entries and lookups, this might speed up assembly. Using AVL-balanced
|
|
trees helps also reducing the stack usage, which is however irrelevant for the C
|
|
version of AS.
|
|
.TP
|
|
.B -a
|
|
|
|
Instruct AS to write out the shared symbol definitions in a format suitable
|
|
for including into an AS assembler program. The file's name is constructed by
|
|
replacing the source file's extension with '.inc'. See the user manual for more
|
|
information about symbol sharing.
|
|
.TP
|
|
.B -cpu <name>
|
|
Set the target processor to <name>. Use this option if the source file does
|
|
not contain a CPU statement.
|
|
.TP
|
|
.B -alias <new name=old name>
|
|
Define a CPU alias. An alias is a name that can be used as an argument to the
|
|
CPU pseudo-instruction just like an intrinsic CPU type. Its usage will set
|
|
the same target as the old name, however the predefined symbols MOMCPU and
|
|
MOMCPUNAME will be set to the new name. This option is primarily useful for
|
|
adding a new member to a processor family that has the same core, but is
|
|
different in its internal peripherals, thus allowing to distinguish between
|
|
them.
|
|
.TP
|
|
.B -C
|
|
|
|
Add a cross reference table to the assembler listing. A cross reference
|
|
table lists all symbols that have been referenced at least once during assembly,
|
|
including the source line number(s) and count of every reference. This option
|
|
only makes sense when the generation of an assembly listing has been turned on
|
|
via the
|
|
.B -L
|
|
or
|
|
.B -l
|
|
parameters.
|
|
.TP
|
|
.B -c
|
|
|
|
Instruct AS to write out the shared symbol definitions in a format suitable
|
|
for including into a C program. The file's name is constructed by replacing
|
|
the source file's extension with '.h'. See the user manual for more information
|
|
about symbol sharing.
|
|
.TP
|
|
.B -D <name[=value]>[,...]
|
|
Pre-define symbols. Predefined symbols are entered into the global symbol
|
|
table prior to assembly of the source file(s). If no value is given for a
|
|
symbol, it is assigned the integer value 1. Value expressions may contain
|
|
arithmetic expressions as described in the user manual, but they may not
|
|
reference any other predefined or internal symbols.
|
|
.TP
|
|
.B -E [file]
|
|
Force AS to send warning and error messages to
|
|
.B file
|
|
rather than to the standard error output. The file names !0 to !4 are used
|
|
to refer to the standard input, output, error, auxilliary, and printer channels
|
|
predefined by the operating system (on some systems, some of these handles
|
|
might not exist). If the [file] specification is omitted, a name is constructed
|
|
by replacing the source file's extension with '.log'.
|
|
.TP
|
|
.B +G
|
|
Supress code generation, reducing the functionality of AS to macro
|
|
preprocessing.
|
|
.TP
|
|
.B -g [MAP/Atmel]
|
|
|
|
Instruct AS to write an additional file containing debug information. This
|
|
information covers the symbol table and the relation between source line
|
|
numbers and machine addresses. The argument specifies whether debug info
|
|
shall be written in AS's own MAP format or the object format for Atmel's AVR
|
|
tools. If no argument is given, MAP will be chosen. The file's name is
|
|
constructed by replacing the source file's extension with '.map' or '.obj'
|
|
respectively.
|
|
.TP
|
|
.B -h
|
|
|
|
Force AS to print all hexadecimal constants with lowercase letters, rather
|
|
than with uppercase letters A..F which is the default.
|
|
.TP
|
|
.B -i <path[:path...]>
|
|
Add new entries to the list of paths that are searched for include files.
|
|
New entries are prepended to the current include path list, so if multiple
|
|
paths are given with one command-line parameter, they will be entered into
|
|
the path list in reverse order.
|
|
.TP
|
|
.B -I
|
|
|
|
Add an include file list to the assembly listing. An include file list contains
|
|
all files that have been included while assembling the source files, including
|
|
multiple and nested inclusion. Nesting of inclusion is identified by different
|
|
indention. This option only makes sense when the generation of an assembly
|
|
listing has been turned on via the
|
|
.B -L
|
|
or
|
|
.B -l
|
|
parameters.
|
|
.TP
|
|
.B -L
|
|
|
|
Turn on generation of an assembly listing and send it to a file whose name is
|
|
constructed by replacing the source file's extension with '.lst'.
|
|
.TP
|
|
.B -l
|
|
|
|
Turn on generation of an assembly listing and send it to the console.
|
|
.TP
|
|
.B -M
|
|
|
|
Turn on generation of a macro definition file. A macro definition file is
|
|
a file that contains all macro definitions that have been detected during
|
|
assembly, in a format suitable for an inclusion into another file. The macro
|
|
definition file's name is constructed by replacing the source file's
|
|
extension with '.mac'.
|
|
.TP
|
|
.B -n
|
|
|
|
Force AS to extend all error and warning messages with their internal error
|
|
resp. warning number.
|
|
.TP
|
|
.B -o <name>
|
|
Tell AS to write the code output to a file <name>. By default, the code
|
|
output file's name is constructed by replacing the source file's extension
|
|
with '.p'. If multiple files are assembled with one command, this parameter
|
|
may also be given multiply. If there are less output specifications than
|
|
source file names, AS will switch back to the default naming convention after
|
|
all output specifications have been used up.
|
|
.TP
|
|
.B -shareout <name>
|
|
Tell AS to write shared symbol definitions to a file <name>, instead of
|
|
constructing the name from the source file's name. See the user manual for
|
|
more information about symbol sharing.
|
|
.TP
|
|
.B -P
|
|
|
|
Turn on generation of a macro output file. A macro output file contains the
|
|
intermediate source code that remains after macro expansion and conditional assembly.
|
|
The macro output file's name is constructed by replacing the source file's
|
|
extension with '.i'.
|
|
.TP
|
|
.B -p
|
|
|
|
Instruct AS to write out the shared symbol definitions in a format suitable
|
|
for including into a Pascal or Modula-2 program. The file's name is
|
|
constructed by replacing the source file's extension with '.inc'. See the
|
|
user manual for more information about symbol sharing.
|
|
.TP
|
|
.B -q or -quiet
|
|
Turn on silent assembly mode. In silent compilation mode, AS will not
|
|
do any console output except for warning and error messages.
|
|
.TP
|
|
.B -r [pass number]
|
|
Tell AS to output warnings when a situation appears in a source file that
|
|
forces another pass of assembly. Such situations either take place when a symbol
|
|
is undefined in the first pass or a symbol's value has changed compared to the
|
|
previous pass. This option is useful to track down sources of excessive
|
|
multi-passing, but be aware that it might yield a fairly large number of
|
|
warnings, especially in the first pass. Optionally, a pass number may be added
|
|
to this option to inhibit output until a certain pass is reached.
|
|
.TP
|
|
.B -s
|
|
|
|
Add a section list to the assembly listing. A section list contains
|
|
all sections that have been defined in the source files, marking their
|
|
nesting level by different levels of indentation. This option only
|
|
makes sense when the generation of an assembly listing has been turned
|
|
on via the
|
|
.B -L
|
|
or
|
|
.B -l
|
|
parameters.
|
|
.TP
|
|
.B -t <mask>
|
|
Turn on or off parts of the assembly listing that have no individual
|
|
command line parameter. AS internally keeps an integer value whose bits
|
|
represent certain components of the listing. A positive command line
|
|
parameter (-t or /t) sets the bits set in <mask>, whereas a negated
|
|
parameter (+t) resets the bits set in <mask>. The individual bits have
|
|
the following meaning: bit 0 = source lines and generated machine code,
|
|
bit 1 = symbol table, bit 2 = macro table, bit 3 = function table, bit 4 =
|
|
line numbering.
|
|
.TP
|
|
.B -u
|
|
|
|
Tell AS to do additional bookkeeping about which address ranges have been
|
|
used by the assembled program. This option enables the detection of overlapping
|
|
memory usage. If an assembly listing has been turned on via the
|
|
.B -L
|
|
or
|
|
.B -l
|
|
parameters, it will also contain a list of all used memory areas.
|
|
.TP
|
|
.B -U
|
|
|
|
Force AS to operate in case-sensitive mode. By default, names of symbols,
|
|
macros, user-defined functions and sections are treated in a case-insensitive
|
|
manner.
|
|
.TP
|
|
.B -w
|
|
|
|
Suppress output of warnings.
|
|
.TP
|
|
.B -x
|
|
|
|
Turn on extended error reporting. With extended error reporting, several
|
|
error and warning messages will also print the item that created the message,
|
|
e.g. the name of an unknown instruction. When this option is given twice,
|
|
the erroneous source line is additinally printed.
|
|
|
|
.SH PRESETTING PARAMETERS
|
|
|
|
Parameters need not neccessarily be given in the command line itself. Before
|
|
processing of command line parameters starts, AS will look if the
|
|
.B ASCMD
|
|
environment variable is defined. If it exists, its contents will be
|
|
treated as additional command line parameters whose syntax is absolutely
|
|
equal to normal command line parameters. An exception is made if the
|
|
variable's contents start with a '@' sign; in such a case, the string after
|
|
the '@' sign is treated as the name of a file that contains the options.
|
|
Such a file (also called a 'key file') has the advantage that it allows
|
|
the options to be written in different lines, and it does not have a size
|
|
limit. Some operating systems (like MS-DOS) have a length limit on
|
|
command lines and environment variable contents, so the key file may be
|
|
your only option if you have a lot of lengthy parameters for AS.
|
|
|
|
As parameters given in the
|
|
.B ASCMD
|
|
environment variable or a key file are processed prior to the command line
|
|
itself, and can therefore be overridden by command line parameters.
|
|
|
|
.SH NATIONAL LANGUAGE SUPPORT
|
|
|
|
AS supports the needs of different languages and countries in the sense that
|
|
it will try to adapt to the language and date/time formats valid for the
|
|
current environment. Upon startup, the COUNTRY setting made in the
|
|
CONFIG.SYS file is queried for DOS and OS/2 implementations of AS. For
|
|
UNIX systems, AS tries to read the LC_TIME resp. LC_MESSAGES environment
|
|
variables to find out the correct format for date/time outputs resp. the
|
|
local language. If this fails, the LC_ALL and finally LANG variables are
|
|
probed. If none of these environment variables points to a specific local
|
|
environment resp. contains a locale specification unknown to AS, the
|
|
standard english/C locale is used.
|
|
|
|
The messages AS can output in different languages are stored in separate
|
|
files with the extension '.msg' . AS will search for these files in the
|
|
following directories:
|
|
|
|
- The current directory
|
|
|
|
- The directory the executable of AS was loaded from (only on DOS platforms version >=3.0 or if path was explicitly specified)
|
|
|
|
- The directory specified in the AS_MSGPATH environment variable resp. the directories listed in the PATH environment variable if AS_MSGPATH does not exist.
|
|
|
|
- The LIBDIR directory set at compile time from the Makefile.
|
|
|
|
|
|
.SH RETURN CODES
|
|
|
|
Depending on the assembly's turnout,
|
|
.B asl
|
|
will generate different return codes:
|
|
.TP
|
|
.B 0
|
|
No errors, warnings might have occured.
|
|
.TP
|
|
.B 1
|
|
No command line parameters were given, AS printed a short list
|
|
of possible command line parameters and terminated thereafter.
|
|
.TP
|
|
.B 2
|
|
Errors occured during assembly of at least one source file, no
|
|
code file was generated for the corresponding source file(s).
|
|
.TP
|
|
.B 3
|
|
A fatal error occured during assembly that forced immediate
|
|
program termination. Code files may be generated, but are probably
|
|
unusuable.
|
|
.TP
|
|
.B 4
|
|
Program termination already occured during initialization. This
|
|
might be either due to a incorrect command line parameter or an error
|
|
during loading the program's overlay file (only possible on MS-DOS).
|
|
.TP
|
|
.B 255
|
|
During initialization, an internal error happened that should not
|
|
occur. If the reaction is reproducable, note down the situation and
|
|
send a bug report to the author.
|
|
|
|
.SH EXAMPLES
|
|
|
|
To assemble a source file
|
|
.B file1.asm
|
|
without any additional bells and whistles, use:
|
|
.PP
|
|
.B asl file1
|
|
.PP
|
|
which will create an output file
|
|
.B file1.p
|
|
given that there are no errors. If you additionally want a listing and
|
|
rename the output file to
|
|
.B a.out,
|
|
use
|
|
.PP
|
|
.B asl -L file1 -o a.out
|
|
.PP
|
|
To make the listing as comprehensive as possible and to get more detailed
|
|
error messages, use:
|
|
.PP
|
|
.B asl -LuCIs -t 16 -nx file1
|
|
|
|
.SH TIPS
|
|
|
|
calling AS without any parameters will print a short help containing all
|
|
command line parameters and implemented target processors, while calling
|
|
with command line parameters but without any source file name will result
|
|
in AS asking for a source file name on the console.
|
|
|
|
.SH SEE ALSO
|
|
|
|
plist(1), pbind(1), p2hex(1), p2bin(1)
|
|
|
|
.SH HISTORY
|
|
|
|
AS originally appeared as a DOS program in 1989, written in
|
|
Borland-Pascal, and was ported to C and UNIX in 1996.
|
|
|
|
.SH BUGS
|
|
|
|
There are too many options.
|
|
|
|
Command line interpreters of some operating systems reserve some
|
|
characters for their own use, so it might be necessary to give
|
|
command line parameters with certain tricks (e.g., with the help
|
|
of escape characters).
|
|
|
|
.SH AUTHOR(S)
|
|
|
|
Alfred Arnold (a.arnold@kfa-juelich.de), and a few others...
|