ALDS(1) ALDS(1)
NAME
alds - ALDS Z80 / HD64180/Z180 cross assembler
SYNOPSIS
alds [-flpdeacPsxormMSqkvtOLD] filename [filename ..... filename]
DESCRIPTION
ALDS is an assembler for the Z80 assembly language, with support for
instructions added by the HD64180/Z180 processor. ALDS is a multi-pass
assembler, with support for macros and several output options, includ-
ing the generation of absolute object files suitable for use in
EPROMs/ROMs, boot sectors, operating system resident code regions and
other applications where no relocation or linking with other modules is
required. Relocate-able object files can also be produced.
ALDS supports the full Z80 mnemonic instruction set (including the
opcodes never documented by Zilog and its licensees), as well as a num-
ber of "synthetic" instructions (made from built-in macros) that emu-
late more complex opcodes not actually available in the Z80 processor.
In addition, ALDS also is aware of the opcodes added by the Hitachi
64180/Zilog Z180 processor design, although those additional opcodes
can only be used on those processors.
Assembly language listings and cross-reference tables produced by ALDS
have a look almost identical to the Digital Equipment Corporation
"MACRO" assembler used on several of the DEC platforms of the 1970s and
1980s. (These are meant for output onto 132 column paper or video dis-
play, but a truncated 80 column format option is available.)
OPERATION
The assembler reads one or more assembly source files named file-
name.src and creates object output filename.hex (absolute object) or
filename.rel (relocatable object), and a listing file filename.lis.
The assembler may also create the file filename.gbl if there are global
symbols in the assembly.
OPTIONS
-f omits the listing and listing file. This option will speed up
the assembly if only object is required, and a listing is not
needed.
-l re-directs stdout/stderr output to a file filename.log. This
includes "pass complete" messages and each line of the source
code that contains an error.
-p directs the listing file, if produced, to be printed upon com-
pletion of the assembly.
-d will delete the listing file, if produced and printed, after
printing is complete.
-e will print the listing file ONLY if errors were not produced.
The use of the -e flag automatically elects the -p flag.
-a xxxx
will cause the assembly to ABORT should xxxx errors be encoun-
tered. The number may be expressed in decimal notation, but can
also be expressed in octal notation by starting the number with
a leading zero, or in hexadecimal notation by beginning the num-
ber with a '0x' or '0X'.
-c will output to stdout (or logfile) all INPUT lines. This is use-
ful in situations where the assembler "gets stuck" somewhere,
and the last line displayed may indicate where the problem is.
-P will cause a full listing to be produced on BOTH pass 1 and pass
2. This is useful in locating a phase error between passes.
(Phase errors are usually caused by the way in which condition-
als or macros are used that end up producing a different number
of bytes in pass 2 than what was produced in pass 1, and that
causes at least one label to reside at a different address in
pass 2 than it did in pass 1.)
-s will suppress the symbol table printing if a listing is pro-
duced.
-x will suppress the listing and produce JUST the symbol table.
-o will suppress the output of the object file. This is useful if
only a listing is desired.
-r will cause ALL symbols, referenced, unreferenced, locals, and
macro locals, to be printed in the cross reference.
-m will cause the assembler to 'mail' an appropriate message upon
completion or termination of the assembly.
-M will cause the assembler to 'mail' an appropriate message upon
completion or termination of the assembly ONLY if there are
errors.
-S will cause the assembler to output the listing to stderr, rather
than to the listing file.
-q will cause quiet mode in which output to the logfile, or std-
out/stderr will be suppressed.
-k will cause the object file to be deleted if there any errors
during the assembly.
-v will cause the assembler to output to stdout the name of the
file it's currently assembling.
-t will cause the assembler to truncate the output listing for 80
column printers.
-O path
will cause the assembler to output the object file(s) to path.
This is useful if you have one set of sources, but they are con-
ditionally assembled for several different models. You can spec-
ify, for example, the the object of this assembly should be
placed in another directory or sub-directory. For example:
alds -O model2 file
will cause the object produced from `file' to be placed in the
sub-directory of `model2' as file.[hex][rel]. Full path names
may also be used such as:
alds -O /a/dir/sub1/sub2/model2 file
-L will cause the listings to take the -O path name and place the
listings in the same directory as the objects. This option will
not work unless the -O option has been elected.
-D will cause the listing (if produced) to be deleted ONLY if there
were no errors in the assembly.
ENVIRONMENT
The setenv variable may be used with the assembler allowing the files
to be included referenced or external-ed by a one word environment
variable. As an example, you may have a directory (say /x/y/z) in
which you have normally included files. Then in your .cshrc or .login
file, you may wish to place
setenv EQU '/x/y/z'
Once done and it becomes part of your environment, you can state in
your source file:
INCLUDE 'EQU:file'
The assembler will pick up the "EQU" variable and expand it into
"/x/y/z/file".
NOTES
The assembler will make two attempts to open a file. If unsuccessful on
the first attempt, it will alter the upper/lower case of the file name
to its counterpart and attempt a second open. This behavior exists
because UNIX/XENIX environments mainly used lowercase filenames, while
TRSDOS environments mainly used or only used uppercase filenames, and
it was common to have files with the "wrong" case present in either
environment while using ALDS for cross-platform development.
The assembler will attempt to open any .gbl file with the file name
specified. Should the attempt fail, the assembler will attempt another
open of the same file with /usr/include/ prefixed to the filename.
The assembler will create a 'lock' file with the name of filename.lock
to prevent simultaneous assemblies of the same source file. This lock
file will be removed upon normal completion or if the job process is
aborted.
WARNING should the system crash or go down for some reason, the lock
file WILL NOT be removed and must be deleted manually.
This documentation describes the operation of the "C" language imple-
mentation of the ALDS assembler. A version written in Z80 assembly
language also exists, but has different command line options.
PROCESSOR INTEROPERABILITY
ALDS will assemble the so-called "undocumented" Z80 opcodes, which
exist and function correctly in all Zilog Z80 processors and most of
those made by other vendors. (Hitachi 64180 and Zilog Z180 processors
lack these opcodes. Use of the undocumented Z80 opcodes on the
64180/Z180 will result in an illegal instruction trap. If not vec-
tored, that trap will behave as though the "RST 0" instruction had been
executed, which reboots most systems.)
The SGS 2MHz version of the Z80 lack the alternate registers AF', BC',
DE' and HL'. Use of the EXX and EX AF,AF' instructions on these pro-
cessors will have unpredictable results. 2MHz Z80s made by other ven-
dors do not have this restriction.
As mentioned earlier, ALDS has a number of "synthetic" instructions
that do not actually exist in any of the Z80 or Z80-descended proces-
sors. These instructions are actually built-in macros that emit two or
more real Z80 opcodes that perform the stated operation. Some silently
use and do not preserve contents of other registers (notably "A") while
performing the stated function and flags ("F") may be altered in non-
obvious ways. Because of the side-effects, the programmer should exer-
cise care when using these macro-based instructions. (There is no
option for disabling the availability of the macro-based instructions
or warning of their use.)
ASSEMBLER DEFAULTS
- listing file produced
- symbol table listing produced
- only useful symbols are printed
- object file produced
- expansion of macros are printed
- false conditionals are not printed
- log information output to stderr
FILES
*.src Z80 source files
*.hex Absolute object output file
*.rel Relocatable object output file
*.lis Listing output file
*.gbl Global output file
*.log Log output file
*.lock Lock file
/usr/local/alds Actual assembler program
SEE ALSO
link(1) Linker for use with ALDS assembler output.
For a description of the ALDS assembler language and its directives,
see the Model II ALDS Manual.
svcnum(3) Globals file of SVC numbers (OS Specific)
sysgbl(3) Globals file of system equates (OS Specific)
BUGS
ALDS has a ridiculous number of options, and operates strangely when
run by Larry West or Kent Brinkley. (These were two TSD employees dur-
ing the early- and mid-1980s who seemed to have a knack for reporting
irreproducible results when using ALDS).
AUTHOR
Ron Light, Tandy Systems Design (software and original documentation)
Frank Durda IV (updated documentation, code fixes to reduce compiler
warnings, HD64180/Z180 extensions, platform port consolidations, and
all HTML material)
Local ALDS(1)
[Copyright 2007 Frank Durda IV, All Rights Reserved. Mirroring of any material on this site in any form is expressly prohibited. The official web site for this material is: http://nemesis.lonestar.org Contact this address for use clearances: clearance at nemesis.lonestar.org Comments and queries to this address: web_software_2011 at nemesis.lonestar.org]