ALDS(1)                                                                ALDS(1)

       alds - ALDS Z80 / HD64180/Z180 cross assembler

       alds [-flpdeacPsxormMSqkvtOLD] filename [filename ..... filename]

       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.)

       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.

       -f     omits  the  listing  and listing file. This option will speed up
              the assembly if only object is required, and a  listing  is  not

       -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-

       -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

       -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.

       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

       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

       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.

       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.)

       -    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

       *.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

       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)

       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).

       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)

Valid HTML 4.01!

[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:
Contact this address for use clearances: clearance at
Comments and queries to this address: web_software_2011 at]