... Invoking ASxxxx
Starting an ASxxxx assembler without any arguments provides
the following option list and then exits:
Usage: [-Options] [-Option with arg] file1 [file2 ...]
-h or NO ARGUMENTS Show this help list
Output:
-o Enable object output (-o+ change file1[.rel])
-o+ Conditional Options -o+[ ][name][.ext]
'-o+.ext' (or) '-o+ .ext' -> file1.ext
'-o+name' (or) '-o+ name' -> name[.rel]
'-o+name.ext' (or) '-o+ name.ext' -> name.ext
-l Create list file1[.lst] (file1 <- name)
-s Create symbol file1[.sym] (file1 <- name)
Listing:
-d Decimal listing
-q Octal listing
-x Hex listing (default)
-b Display .define substitutions in listing
-bb and display without .define substitutions
-c Disable instruction cycle count in listing
-f Flag relocatable references by ` in listing file
-ff Flag relocatable references by mode in listing file
-k Disable error messages to listing file
-p Disable automatic listing pagination
-u Disable .list/.nlist processing
-w Wide listing format for symbol table
Assembly:
-i Insert assembler line before input file(s)
-v Enable out of range signed / unsigned errors
-n# Set the maximum number of 'Pass 2' scans
Symbols:
-a All user symbols made global
-g Undefined symbols made global
-z Disable case sensitivity for symbols
Debugging:
-j Enable NoICE Debug Symbols
-y Enable SDCC Debug Symbols
The ASxxxx assemblers are command line oriented. Most sytems
require the option(s) and file(s) arguments to follow the ASxxxx
assembler name:
as6809 [-Options] [-Option with arg] file1 [file2 ...]
Some systems may request the arguments after the assembler is
started at a system specific prompt:
as6809
argv: [-Options] [-Option with arg] file1 [file2 ...]
The ASxxxx options in some more detail:
-h List the ASxxxx options
Output:
-o enable object output file1.rel
The object output file name and/or extension can
be changed as desired using the -o+ option.
The list and symbol file names are changed to match
that of the object output file name. The list and
symbol file extensions cannot be changed as the
linker requires a .LST extension in order to create
the relocated, .RST, listing file.
-o+ Conditional Options -o+[ ][name][.ext]
'-o+.ext' (or) '-o+ .ext' -> file1.ext
'-o+name' (or) '-o+ name' -> name.rel
'-o+name.ext] (or) '-o+ name.ext' -> name.ext
-l create list file1[.lst] (file1 <- name)
If -s (symbol table output) is not
specified then the symbol table is
included at the end of the listing file.
-s create symbol file1[.sym] (file1 <- name)
Listing:
-d decimal listing
-q octal listing
-x hex listing (default)
The listing radix affects the
.lst, .rel, .hlr, and .sym files.
-b display .define substitutions in listing
If a .define substitution has been applied
to an assembler source line the source
line is printed with the substitution.
-bb and display without .define substitutions
If a .define substitution has been applied
to an assembler source line the source
line is first printed without substitution
followed by the line with the substitution.
-c Disable instruction cycle count in listing
This option overrides the listing option
'cyc' in the .list and .nlist directives.
Instruction cycle counts cannot be enabled
if the -c option is specified.
-f by ` in the listing file
-ff by mode in the listing file
Relocatable modes are flagged by byte
position (LSB, Byte 2, Byte 3, MSB)
*nMN paged,
uvUV unsigned,
rsRS signed,
pqPQ program counter relative.
-k disable error messages to listing file
This option inhibits the listing of
error messages in the listing file
-p disable listing pagination
This option inhibits the generation
of a form-feed character and its
associated page header in the
assembler listing.
-u disable .list/.nlist processing
This option disables all .list and
.nlist directives. The listing mode
is .list with the options err, loc,
bin, eqt, cyc, lin, src, pag, lst,
and md. The options cyc and pag are
overridden by the -c and -p command
line options.
-w wide listing format for symbol table
Assembly:
-i Insert assembler line before input file(s)
This option inserts an assembly source
line before the first file to be assembled.
e.g.: -i BUILD=2
If the insert contains white space then
delimit the insert. Inserted lines are
by default not listed. To list an inserted
line preced the insert with a .list insert.
e.g.: -i .list -i BUILD=2
-v Enable out of range signed / unsigned errors
This option enables checking for out of
range signed / unsigned values in symbol
equates and arithmetic operations. This
option has some ambiguities as internally
the assemblers use unsigned arithmetic
for calculations. (e.g. for a 2-byte machine
-32768 and 32768 are both represented as 0x8000)
-n# Set the maximum number of 'Pass 2' scans
Specify a maximum number of 'Pass 2' scans
to resolve multiple level forward referencing
and variable length instruction formats.
Symbols:
-a all user symbols made global
All defined (not local or external)
variables and symbols are flagged
as global.
-g undefined symbols made global
Unresolved (external) variables
and symbols are flagged as global.
-z disable case sensitivity for symbols
Debugging:
-j enable NOICE debug symbols
-y enable SDCC debug symbols
The file name for the .lst, .rel, .hlr, and .sym files is the
first file name specified in the command line. All output files
are ascii text files which may be edited, copied, etc. The out-
put files are the concatenation of all the input files, if files
are to be assembled independently invoke the assembler for each
file.
The .rel file contains a radix directive so that the linker
will use the proper conversion for this file. Linked files may
have different radices.
The ASxxxx assemblers also have several 'hidden' options
which are not shown in the usage message. These are:
-r Include assembler line numbers
in the .hlr hint file
-rr Also include non listed line
numbers in the .hlr hint file
-t Show Assembler Pass Count (-n#),
Include File and Macro Expansion
levels, and memory allocations for
the assembler and macro processor
-tt Show Assembler Pass Count (-n#),
Include File and Macro Expansion
levels, and memory allocations for the
assembler and macro processor without
the macro allocation optimization
... Errors
The ASxxxx assemblers provide limited diagnostic error codes
during the assembly process, these errors will be noted in the
listing file and printed on the stderr device.
The assembler reports the errors on the stderr device as
?ASxxxx-Error-<*> in line nnn of filename
where * is the error code, nnn is the line number, and filename
is the source/include file. This line is followed by a generic
error message for the <*> error code.
The errors are:
<.> This error is caused by an absolute direct assign-
ment of the current location counter
. = expression (incorrect)
rather than the correct
. = . + expression
<a> Indicates a machine specific addressing or address-
ing mode error.
<b> Indicates a direct page boundary error.
<c> Indicates modulus of .bndry directives to large.
<d> Indicates a direct page addressing error.
<e> Caused by a .error or .assume directive.
<i> Caused by an .include file error or an .if/.endif
mismatch.
<m> Multiple definitions of the same label, multiple
.module directives, multiple conflicting attributes
in an .area or .bank directive or the use of .hilo
and lohi within the same assembly.
<n> An .mexit, .endm, or .narg directive outside of a
macro, repeat block or indefinite repeat block.
<o> Directive or mnemonic error or the use of the .org
directive in a relocatable area.
<p> Phase error: label location changing between passes
2 and 3. Normally caused by having more than one
level of forward referencing.
<q> Questionable syntax: missing or improper operators,
terminators, or delimiters.
<r> Relocation error: logic operation attempted on a
relocatable term, addition of two relocatable terms,
subtraction of two relocatable terms not within the
same programming area or external symbols.
<s> String Substitution / recursion error.
<u> Undefined symbol encountered during assembly.
<z> Divide by 0 or Modulus by 0 error: result is 0.
Most assemblers now include more descriptive error messages
for <a>, <o>, and <q> errors. Those assemblers updated to pro-
vide the expanded error messages will show three lines on the
stdout device as shown by this error:
?ASxxxx-Error-<a> in line 1867 of tez80e.asm
<a> '1867 ld.l sp,(var1) ;a'
<a> Only .SIS and .LIL suffixes allowed.
The first line is the basic error in line xxxx message. The
second line lists the actual line in error followed by a third
line containing the more specific error.
The listing file (.lst) will have the first and third lines
of the error message inserted preceding the line containing the
error.
... Listing File
The (-l) option produces an ascii output listing file. Each
page of output contains a five line header:
1. The ASxxxx program name and page number
2. Assembler Radix, Address Bits, Date, and Time
3. Title from a .title directive (if any)
4. Subtitle from a .sbttl directive (if any)
5. Blank line
Each succeeding line contains five fields:
1. Error field (first two characters of line)
2. Current location counter
3. Generated code in byte format
4. Opcode cycles count
5. Source text line number
6. Source text
The error field may contain upto 2 error flags indicating any
errors encountered while assembling this line of source code.
The current location counter field displays the 16-bit,
24-bit, or 32-bit program position. This field will be in the
selected radix.
The generated code follows the program location. The listing
radix determines the number of bytes that will be displayed in
this field. Hexidecimal listing allows six bytes of data within
the field, decimal and octal allow four bytes within the field.
If more than one field of data is generated from the assembly of
a single line of source code, then the data field is repeated on
successive lines.
The opcode cycles count is printed within the delimiters [ ]
on the line with the source text. This reduces the number of
generated code bytes displayed on the line with the source list-
ing by one. (The -c option disables all opcode cycle listing.)
The source text line number is printed in decimal and is fol-
lowed by the source text. A Source line with a .page directive
is never listed. (The -u option overrides this behavior.)
Two additional options are available for printing the source
line text. If the -b option is specified then the listed source
line contains all the .define substitutions. If the -bb option
is specified then the original source line is printed before the
source line with substitutions.
Two data field options are available to flag those bytes
which will be relocated by the linker. If the -f option is
specified then each byte to be relocated will be preceded by the
'`' character. If the -ff option is specified then each byte to
be relocated will be preceded by one of the following
characters:
1. * paged relocation
2. u low byte of unsigned word or unsigned byte
3. v high byte of unsigned word
4. p PCR low byte of word relocation or PCR byte
5. q PCR high byte of word relocation
6. r low byte relocation or byte relocation
7. s high byte relocation
Assemblers which use 24-bit or 32-bit addressing use an ex-
tended flagging mode:
1. * paged relocation
2. u 1st byte of unsigned value
3. v 2nd byte of unsigned value
4. U 3rd byte of unsigned value
5. V 4th byte of unsigned value
6. p PCR 1st byte of relocation value or PCR byte
7. q PCR 2nd byte of relocation value
8. P PCR 3rd byte of relocation value
9. Q PCR 4th byte of relocation value
10. r 1st byte of relocation value or byte relocation
11. s 2nd byte of relocation value
12. R 3rd byte of relocation value
13. S 4th byte of relocation value
... Symbol Table File
The symbol table has two parts:
1. The alphabetically sorted list of symbols and/or labels
defined or referenced in the source program.
2. A list of the program areas defined during assembly of
the source program.
The sorted list of symbols and/or labels contains the follow-
ing information:
1. Program area number (none if absolute value or exter-
nal)
2. The symbol or label
3. Directly assigned symbol is denoted with an (=) sign
4. The value of a symbol, location of a label relative to
the program area base address (=0), or a **** indicat-
ing the symbol or label is undefined.
5. The characters: G - global, L - local, R - relocatable,
and X - external.
The list of program areas provides the correspondence between
the program area numbers and the defined program areas, the size
of the program areas, and the area flags (attributes).
... Object File
The object file is an ascii file containing the information
needed by the linker to bind multiple object modules into a com-
plete loadable memory image. The object module contains the
following designators:
[XDQ][HL][234]
X Hexidecimal radix
D Decimal radix
Q Octal radix
H Most significant byte first
L Least significant byte first
2 16-Bit Addressing
3 24-Bit Addressing
4 32-Bit Addressing
H Header
M Module
G Merge Mode
B Bank
A Area
S Symbol
T Object code
R Relocation information
P Paging information
Refer to the linker for a detailed description of each of the
designators and the format of the information contained in the
object file.
... Hint File
The hint file is an ascii file containing information needed
by the linker to convert the listing file into a relocated list-
ing file. Each line in the .hlr file corresponds to a single
line in the listing file. The text line usually contains 3 or 4
parameters in the radix selected for the assembler as shown in
the following table:
Line Position: 123456789012
------------
Octal: 111 222 333
Decimal: 111 222 333
Hex: 11 22 33
Parameter 1 specifies the parameters listed in the line.
A bit is set for each listing option enabled during the
assembly of the line.
BIT 0 - LIST_ERR Error Code(s)
BIT 1 - LIST_LOC Location
BIT 2 - LIST_BIN Generated Binary Value(s)
BIT 3 - LIST_EQT Assembler Equate Value
BIT 4 - LIST_CYC Opcode Cycles
BIT 5 - LIST_LIN Line Numbers
BIT 6 - LIST_SRC Assembler Source Code
BIT 7 - HLR_NLST Listing Inhibited
Parameter 2 is the internal assembler listing mode
value specified for this line during the assembly process:
0 - NLIST No listing
1 - SLIST Source only
2 - ALIST Address only
3 - BLIST Address only with allocation
4 - CLIST Code
5 - ELIST Equate only
6 - ILIST IF conditional evaluation
Parameter 3 is the number of output bytes listed
for this line.
The 4th parameter is only output if an equate references a
value in a different area. The area name is output in the fol-
lowing format following the 3 parameters described above:
Line Position: 123456789012
------------
Area Name: equatearea
When the line number is output to the .hlr file (-r option)
the line number is prepended to the 3 or 4 parameters described
above. The line number is always in decimal in the following
format:
Line Position: 1234567
-------
Decimal: LLLLL
Thus the four formats (for each radix) that may be present in
a .hlr file are:
Line Position: 123456789012345678901234567890
------------------------------
11 22 33
11 22 33 equatearea
LLLLL 11 22 33
LLLLL 11 22 33 equatearea
The linker understands these formats without any user inter-
action.
... Exit the ASxxxx Documentation
... Home Page
Last Updated: September 2023