## The Linker Description

### ... Invoking ASlink

####

       Starting  ASlink 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
      -p   Echo commands to stdout (default)
      -n   No echo of commands to stdout
    Alternates to Command Line Input:
      -c                   ASlink >> prompt input
      -f   file[.lnk]      Command File input
    Librarys:
      -k   Library path specification, one per -k
      -l   Library file specification, one per -l
    Relocation:
      -a   Area base address=expression
      -b   Bank base address=expression
      -g   Global symbol=expression
    Map format:
      -m   Map output generated as file1[.map]
      -m1    Linker generated symbols included in file1[.map]
      -w   Wide listing format for map file
      -x   Hexadecimal (default)
      -d   Decimal
      -q   Octal
    Output:
      -i   Intel Hex as file1[.hex]
      -s   Motorola S Record as file1[.s--]
      -t   Tandy CoCo Disk BASIC binary as file1[.bin]
      -*+  -i+/-s+/-t+  Renaming Options  -*+[ ][name][.ext]
        '-*+.ext'      (or)  '-*+  .ext'      ->  file1.ext
        '-*+name'      (or)  '-*+  name'      ->  name[.---]
        '-*+name.ext'  (or)  '-*+  name.ext'  ->   name.ext
      -o   Linked file/library -i/-s/-t output enable (default)
      -v   Linked file/library -i/-s/-t output disable
      -j   NoICE Debug output as file1[.noi]
      -y   SDCDB Debug output as file1[.cdb]
    List:
      -u   Update listing file(s) with link data as file(s)[.rst]
    Case Sensitivity:
      -z   Disable Case Sensitivity for Symbols
    End:
      -e   or null line terminates input

                                  NOTE

         When  ASlink  is  invoked  with  a  single or multiple
         filenames the first filename is  the  output  filename
         and  the  remaining files, if any, are linked together
         into the output filename.

    Most  sytems  require  the  options to be entered on the command
    line:

    aslink [-Options] [-Options with args] file1 [file2 ...]

    Some  systems  may  request  the  arguments  after the linker is
    started at a system specific prompt:

    aslink
    argv: [-Options] [-Option with args] file1 [file2 ...]

    The linker commands are explained in some more detail:

            -h      or NO ARGUMENTS show this help list

                    Simply prints the help list on stdout.

            -c      ASlink >> prompt mode.

                    The ASlink#>> prompt mode reads
                    linker commands from stdin.

            -f      file[.lnk]  Command File Input

                    The command file mode imports linker
                    commands from the specified file
                    (extension must be .lnk), imported
                    -c and -f commands are ignored.  If
                    the directory path, for a file to
                    be linked, is not specified in the
                    command file then the path defaults
                    to the command file directory path.

            -p/-n   enable/disable echoing commands to stdout.

            -i      Intel Hex as file1[.hex]
            -s      Motorola S Record as file1[.s--]
            -t      Tandy CoCo Disk BASIC binary as file1[.bin]

            -*+   -i+/-s+/-t+ Renaming Options  -o+[ ][name][.ext]
              '-*+.ext'      (or)  '-*+  .ext'      ->  file1.ext
              '-*+name'      (or)  '-*+  name'      ->  name[.---]
              '-*+name.ext'  (or)  '-*+  name.ext'  ->   name.ext

                    The file name and/or extension of the
                    output file may be changed.

            -o      Linked file/library output enabled (default)

                    Specifies that subsequent linked
                    files/libraries will enable object output.
                    (if option -i, -s, or -t was specified)

            -v      Linked file/library output disabled

                    Specifies that subsequent linked
                    files/libraries will disable object output.
                    (if option -i, -s, or -t was specified)

            -z      Disable Case Sensitivity for Symbols

                    Disables the distinction between
                    upper and lower case letters.

            -m      Map output generated as file1[.map]

                    Generate a map file (file1.map). This
                    file contains a list of the symbols
                    (by area) with absolute addresses,
                    sizes of linked areas, and other
                    linking information.

            -m1     Linker generated symbols included in file1[.map]

                    The linker creates internal symbols for
                    each area (area segment) input during
                    the linking process but normally suppresses
                    their inclusion in the map file.  This
                    option enables their inclusion in the
                    map file.

            -w      Wide listing format for map file

                    Specifies that a wide listing format
                    be used for the map file.

            -x      Hexadecimal (default)
            -d      Decimal
            -q      Octal

                    Specifies the number radix for the map file.

            -u      Update listing file(s) with link data

                    Generate updated listing file(s) derived from
                    the relocated addresses and data from the
                    linker and the hint file (file.hlr) output
                    by the assembler.

            -a      Area base address=expression

                    This specifies an area base address
                    where the expression may contain
                    constants and/or defined symbols
                    from the linked files. (one definition
                    per line in a linker command file.)

            -b      Bank base address=expression

                    This specifies a bank base address
                    where the expression may contain
                    constants and/or defined symbols
                    from the linked files. (one definition
                    per line in a linker command file.)

            -g      Global symbol=expression

                    This specifies the value for the
                    symbol where the expression may contain
                    constants and/or defined symbols
                    from the linked files. (one definition
                    per line in a linker command file.)

            -k      Library path specification, one per -k

                    This specifies one possible path to an
                    object library. More than one path is
                    allowed.  (one definition per line in
                    a linker command file.)

            -l      Library file specification, one per -l

                    This specifies a possible library file.
                    More than one file is allowed.  (one
                    definition per line in a linker command file.)

            -e      or null line, terminates input

                    This -e option terminates the processing
                    of a linker command file (-f). Any
                    lines remaining in the file are ignored.

       When  using  the command line all options and file(s) must be
    on a single line.

       When using the -c option (ASlink >>) or a command file [.lnk]
    options should precede the file(s).  The files  may  be  on  the
    same  line  as the options or on a separate line(s) one file per
    line or multiple files separated by spaces or tabs.  The use  of
    multiple  -o and -v options is available only with the interrac-
    tive, ASlink >>, or command file modes.

##### Return to the Linker Index

### ... Library Path(s) and File(s)

####

       The process of resolving undefined symbols after scanning the
    input object  files  includes  the  scanning  of  object  module
    libraries.   The  linker will search through all combinations of
    the library path specifications (input by the -k option) and the
    library  file  specifications (input by the -l option) that lead
    to an existing library file.  Each library file contains a  list
    (one  file  per  line)  of  modules  included in this particular
    library.  Each existing object module is scanned for a match  to
    the undefined symbol.  The first module containing the symbol is
    then linked with the previous modules to resolve the symbol  de-
    finition.   The  library  object  modules are rescanned until no
    more symbols can be resolved.   The  scanning  algorithm  allows
    resolution  of  back references.  No errors are reported for non
    existant library files or object modules.

       The  library  file  specification may be formed in one of two
    ways:

         1.  If  the  library  file  contained an absolute path/file
             specification  then  this  is   the   object   module's
             path/file.
             (i.e.  C:\...  or C:/...)

         2.  If  the  library  file  contains  a  relative path/file
             specification then the concatenation of  the  path  and
             this  file  specification  becomes  the object module's
             path/file.
             (i.e.  \...  or /...)

       As  an example, assume there exists a library file termio.lib
    in the syslib directory specifying the following object modules:

    \6809\io_disk        first object module
    d:\special\io_comm   second object module

    and the following parameters were specified to the linker:

    -k c:\iosystem\    the first path
    -k c:\syslib\      the second path

    -l termio          the first library file
    -l io              the second library file (no such file)

    The  linker  will attempt to use the following object modules to
    resolve any undefined symbols:

    c:\syslib\6809\io_disk.rel     (concatenated path/file)
    d:\special\io_comm.rel         (absolute path/file)

    all  other path(s)/file(s) don't exist.  (No errors are reported
    for non existent path(s)/file(s).)

##### Return to the Linker Index

### ... ASlink Processing

####

       The  linker  processes  the  files  in  the  order  they  are
    presented.  The first pass through the input files  is  used  to
    define  all  program  areas, the section area sizes, and symbols
    defined or referenced.  Undefined symbols will initiate a search
    of any specified library file(s) and the importing of the module
    containing the symbol definition.  After the first pass  the  -a
    (area  base  address) and the -b (bank base address) definitions
    ,if any, are processed and the areas linked.

       The  area  linking proceeds by first examining the area types
    ABS, CON, REL, OVR and PAG.  Absolute areas (ABS) from  separate
    object  modules are always overlaid and have been assembled at a
    specific address, these are not normally relocated (if a -a  op-
    tion  is  used  on an absolute area the area will be relocated).
    Relative areas (normally defined as REL|CON) have a base address
    of 0x0000 as read from the object files, the -a option specifies
    the beginning address of  the  area.   All  subsequent  relative
    areas will be concatenated with preceding relative areas.  Where
    specific ordering is desired, the first linker input file should
    have  the area definitions in the desired order.  At the comple-
    tion of the area linking all area  addresses  and  lengths  have
    been  determined.  The areas of type PAG are verified to be on a
    256 byte boundary and that the length does not exceed 256 bytes.
    Any errors are noted on stderr and in the map file.

    The  linker  also  automatically  generates two symbols for each
    linked program area:

        'a_<area>'      The starting address of the area.

        'l_<area>'      The length of the area.

    and two symbols for each area segment:

        'm_<area>_n'    The boundary modulus of the area segment.

        's_<area>_n'    The starting address of the area segment.

    The  appended  '_n'  signifies  the area segment number within a
    linked area.

       These  symbols  are in general only useful diagnostically and
    are not visible externally.  However if the -m1 linker option is
    used these symbols will be output to the map file.

       Next  the  global symbol definitions (-g option), if any, are
    processed.  The symbol definitions have been delayed until  this
    point because the absolute addresses of all internal symbols are
    known and can be used in the expression calculations.

       Before  continuing  with the linking process the symbol table
    is scanned to determine if any symbols have been referenced  but
    not defined.  Undefined symbols are listed on the stderr device.
    If a .module directive was included in the  assembled  file  the
    module  making  the reference to this undefined variable will be
    printed.

       Constants  defined  as global in more than one module will be
    flagged as multiple definitions if their values are not  identi-
    cal.

       After  the  preceding  processes  are complete the linker may
    output a map file (-m option).  This file provides the following
    information:

         1.  Global symbol values and label absolute addresses

         2.  Defined areas and there lengths

         3.  Remaining undefined symbols

         4.  List of modules linked

         5.  List of library modules linked

         6.  List of -a, -b and -g definitions

       The final step of the linking process is performed during the
    second pass of the input files.  As the xxx.rel files  are  read
    the code is relocated by substituting the physical addresses for
    the referenced symbols and areas and may  be  output  in  Intel,
    Motorola, or Tandy CoCo Disk Basic formats.  The number of files
    linked and symbols defined/referenced is limited by the  proces-
    sor  space  available to build the area/symbol lists.  If the -u
    option is specified then the listing files (file.lst) associated
    with  the  relocation  files  (file.rel) are scanned and used to
    create a new file (file.rst) which has all  addresses  and  data
    relocated to their final values.

       The  -o/-v  options  allow the simple creation of loadable or
    overlay modules.  Loadable and overlay modules normally need  to
    be  linked  with  a  main module(s) to resolve external symbols.
    The -o/-v options can be used to enable object  output  for  the
    loadable  or overlay module(s) and suppress the object code from
    the linked main module(s).  The -o/-v  options  can  be  applied
    repeatedly  to specify a single linked file, groups of files, or
    libraries for object code inclusion or suppression.

##### Return to the Linker Index

### ... Linker V6 (5 and 4) Input Format

####

       The  linkers'  input  object file is an ascii file containing
    the information needed by the linker  to  bind  multiple  object
    modules into a complete 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

- Object Module Format
- Header Line
- Module Line
- Merge Mode Line
- Symbol Line
- Area Line
- Bank Line
- T Line
- R Line
- P Line
- Return to the Linker Index

####

    Object Module Format

       The   first   line   of   an   object   module  contains  the
    [XDQ][HL][234] format specifier  (i.e.   XH2  indicates  a  hex-
    idecimal  file  with  most significant byte first and 16-bit ad-
    dressing) for the following designators.

##### => Section Index

####

    Header Line

            H aa areas gg global symbols

       The  header  line  specifies  the number of areas(aa) and the
    number of global symbols(gg) defined or referenced in  this  ob-
    ject module segment.

##### => Section Index

####

    Module Line

            M name

       The  module  line  specifies  the module name from which this
    header segment was assembled.  The module line will  not  appear
    if the .module directive was not used in the source program.

##### => Section Index

####

    Merge Mode Line

            G nn ii 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

       The  mode  structure  contains  the specification (or partial
    specification) of one of the assemblers' merge  modes.   Sixteen
    bits  may  be  specified  on a single line.  Each assembler must
    specify at least one merge mode.  The merging specification  al-
    lows  arbitrarily defined active bits and bit positions.  The 32
    element arrays are indexed from 0 to 31.  Index 0 corresponds to
    bit  0,  ...,  and  31 corresponds to bit 31 of a normal integer
    value.

         1.   nn is merge mode number

         2.   ii is the beginning bit position of the following data

         3.   00 ...  merge mode bit elements

                The value of the element specifies if the normal in-
                teger bit is active (bit <7> is set, 0x80) and  what
                destination  bit  (bits  <4:0>,  0  -  31) should be
                loaded with this normal integer bit.

##### => Section Index

####

    Bank Line

            B string base nn size nn map nn flags nn fsfx string

       The  B  line  defines  a  bank name as 'string'.  A bank is a
    structure containing a collection of areas.  The bank is treated
    as  a  unique linking structure seperate from other banks.  Each
    bank can have a unique base  address  (starting  address).   The
    size  specification  may  be  used to signal the overflow of the
    banks' allocated space.  The Linker combines all areas  included
    within  a  bank  as  seperate from other areas.  The code from a
    bank may be output to a unique file by specifying the File  Suf-
    fix  parameter  (fsfx).   This allows the seperation of multiple
    data and code segments into  isolated  output  files.   The  map
    parameter  is  for  NOICE processing.  The flags indicate if the
    parameters have been set.

##### => Section Index

####

    Area Line

            A label size ss flags ff [bank bb] [bndry mm]

       The  area  line  defines the area label, the size (ss) of the
    area in bytes, the area  flags  (ff),  the  optional  [bank  bb]
    specifies  the  bank  this area is a member of, and the optional
    [bndry mm] which specifies the boundary modulus  for  this  area
    segment.  The area flags specify the ABS, REL, CON, OVR, and PAG
    parameters:

            OVR/CON  (0x04/0x00 i.e.  bit position 2)

            ABS/REL  (0x08/0x00 i.e.  bit position 3)

            PAG      (0x10 i.e.  bit position 4)

       The  bank label is optional and only specified if the area is
    to be included within a bank.

       When  this area (area segment) is linked and their is a boun-
    dary modulus specified then the code/data beginning address will
    be  increased to match the boundary modulus.  This will also in-
    crease the area (area segment) size by the same amount.

##### => Section Index

####

    Symbol Line

           S name Defnnnn

                   or

           S name Refnnnn

      The symbol line defines (Def) or references (Ref) the identi-
    fier name with the value nnnn.  The defined value is relative to
    the  current area base address.  References to constants and ex-
    ternal global symbols will always appear before the  first  area
    definition.  References to external symbols will have a value of
    zero.

      Version  6  supports a modified form of the symbol definition
    line used to pass complex expressions to the linker.  These  de-
    finitions  are  never shown in the associated symbol listings or
    generated map file.

           S name =D nnnn

                   or

           S name =Rn^Z( exression )

      The '=D ' pefixes a value normally associated with a relocat-
    able program counter value.

      The '=Rn' prefixes an expression.  The 'n' has a value from 1
    to 3 specifying the MSB byte number (1 - <15:8>, 2 - <23:16>, or
    3  - (31:24>) defined by the assembler.  This informs the linker
    how to interpret > in an expression.

      The  evaluation includes the '^Z', the enclosing parenthesis,
    and the expression.  The '^Z' will be ^Q, ^D, or  ^X  indicating
    the  default  radix  to be used when evaluating any valid arith-
    metic or logical expression.

      These are examples of symbol definitions that might be passed
    to the linker:

    S N Def0012
    S xN Ref0000
    S tst9_1 =D 139A
    S tst9_2 =R1^D(tst9_1+N + xN)

    The  linker will evaluate the value for tst9_2 using the defined
    value of 2 for N, the defined value of 139A for tst9_1, and  the
    external value xN.  The value of xN will be supplied by an addi-
    tional linked file or a linker -g option.

    S vb Ref0000
    S reloc_8 =R1^X(<(vb/2 + 20 + 1000 + vb))

    The  linker will evaluate the expression using hexadecimal radix
    for the 20 and 1000 constants, the external value of vb,  and  <
    to get the LSB value.  The value of vb wil be supplied by an ad-
    ditional linked file or the linker -g option.

      The  symbol  names are derived from the assembler source file
    name and labels (not from an include file name).  As an example:

    3$:     jmp     3$ + va + vb

    generates the following symbols (in Octal)

    S va Ref000000
    S vb Ref000000
    S rl_pdp11.lbl3.3$ =D 000100
    S rl_pdp11_14 =R1^D(rl_pdp11.lbl3.3$ + va + vb)

    rl_pdp11  is  the  file name, lbl3 is a program label, and 3$ is
    the temporary symbol following the label lbl3.   This  label  is
    created because 3$ as a temporary label cannot be made global.

##### => Section Index

####

    T Line

            T xx xx nn nn nn nn nn ...

       The  T  line contains the assembled code output by the assem-
    bler with xx xx being the offset address from the  current  area
    base address and nn being the assembled instructions and data in
    byte format.  (xx xx and nn nn can be 2, 3, or 4 bytes as speci-
    fied by the .REL file header.)

##### => Section Index

####

    R Line

            R 0 0 nn nn n1 n2 xx xx ...

       The R line provides the relocation information to the linker.
    The nn nn value is the current area index, i.e.  which area  the
    current  values  were  assembled.  Relocation information is en-
    coded in groups of 4 bytes:

         1.  n1 is the relocation mode and object format.
             1.  bits <1:0> specify the number of bytes to output
             2.  bits <2:3> normal(0x00) /   MSB   (0x0C)
                            signed(0x04) / unsigned(0x08)
             3.  bit 4  normal(0x00)/page   '0' (0x10) reference
             4.  bit 5  normal(0x00)/page 'nnn' (0x20) reference
                        PAGX mode if both bits are set (0x30)
             5.  bit 6  normal(0x00)/PC relative(0x40) relocation
             6.  bit 7  relocatable area(0x00)/symbol(0x80)

         2.  n2 is a byte index and a merge mode index
             1.  bits <3:0>  are a byte index into the corresponding
                 (i.e.  preceding) T line data (i.e.  a  pointer  to
                 the data to be updated by the relocation).
             2.  bits <7:4> are an index into a selected merge mode.
                 Currently mode 0 simply specifies to  use  standard
                 byte processing modes and merging is ignored.

         3.  xx xx  is the area/symbol index for the area/symbol be-
             ing referenced.  the corresponding area/symbol is found
             in the header area/symbol lists.

    The groups of 4 bytes are repeated for each item requiring relo-
    cation in the preceding T line.

##### => Section Index

####

    P Line

            P 0 0 nn nn n1 n2 xx xx

       The  P  line provides the paging information to the linker as
    specified by a .setdp directive.  The format of  the  relocation
    information is identical to that of the R line.  The correspond-
    ing T line has the following information:
            T xx xx aa aa bb bb

       Where  aa aa is the area reference number which specifies the
    selected page area and bb bb is the base address  of  the  page.
    bb bb will require relocation processing if the 'n1 n2 xx xx' is
    specified in the P line.  The linker will verify that  the  base
    address is on a 256 byte boundary and that the page length of an
    area defined with the PAG type is not larger than 256 bytes.

       The  linker  defaults any direct page references to the first
    area defined in the input REL file.  All ASxxxx assemblers  will
    specify the _CODE area first, making this the default page area.

##### => Section Index

####

    24-Bit and 32-Bit Addressing

       When  24-bit  or  32-bit  addressing is specified in the file
    format line [XDQ][HL][234] then the S and T Lines have  modified
    formats:
            S string Defnnnnnn                      (24-bit)
            S string Refnnnnnn                      (24-bit)
            T xx xx xx nn nn nn nn nn ...           (24-bit)

            S string Defnnnnnnnn                    (32-bit)
            S string Refnnnnnnnn                    (32-bit)
            T xx xx xx xx nn nn nn nn nn ...        (32-bit)

       The  multibyte  formats for byte data replace the 2-byte form
    for 16-bit data with 3-byte or 4-byte data for 24-bit or  32-bit
    data  respectively.  The 2nd byte format (also named MSB) always
    uses the second byte of the 2, 3, or 4-byte data.

##### => Section Index

### ... Linker V6 (5 and 4) Error Messages

####

       The linker provides detailed error messages allowing the pro-
    grammer to quickly find the errant code.   As  the  linker  com-
    pletes  pass 1  over  the  input  file(s)  it  reports  any page
    boundary or page length errors as follows:

    ?ASlink-Warning-Paged Area PAGE0 Boundary Error

    and/or

    ?ASlink-Warning-Paged Area PAGE0 Length Error

    where PAGE0 is the paged area.

       Also  during  Pass   1  any bank size (length) errors will be
    reported as follows:

    ?ASlink-Warning-Size limit exceeded in bank BANK
    where BANK is the bank name.

       During  Pass  two the linker reads the T, R, and P lines per-
    forming the necessary relocations and  outputting  the  absolute
    code.  Various errors may be reported during this process
    The P line processing can produce only one possible error:

    ?ASlink-Warning-Page Definition Boundary Error
             file        module      pgarea    pgoffset
      PgDef  t6809l      t6809l      PAGE0         0001

    The error message specifies the file and module where the .setdp
    direct was issued and indicates  the  page  area  and  the  page
    offset value determined after relocation.

    The R line processing produces various error messages:

    ?ASlink-Warning-Signed value error
    ?ASlink-Warning-Unsigned value error
    ?ASlink-Warning-Byte PCR relocation error
    ?ASlink-Warning-Word PCR relocation error
    ?ASlink-Warning-3-Byte PCR relocation error
    ?ASlink-Warning-4-Byte PCR relocation error
    ?ASlink-Warning-Page0 relocation error
    ?ASlink-Warning-PageN relocation error
    ?ASlink-Warning-PageX relocation error
    ?ASlink-Warning-Signed Merge Bit Range error
    ?ASlink-Warning-Unsigned/Overflow Merge Bit Range error

    These  error  messages  also specify the file, module, area, and
    offset within the area of the code referencing (Refby)  and  de-
    fining (Defin) the symbol:

    ?ASlink-Warning-Signed value error for symbol  two56
             file        module      area        offset
      Refby  t           Pagetest    PROGRAM     0006
      Defin  t           Pagetest    DIRECT      0100

    If the symbol is defined in the same module as the reference the
    linker is unable to report the symbol name.  The assembler list-
    ing  file(s) should be examined at the offset from the specified
    area to locate the offending code.

       The errors are:

         1.  The  Signed value error indicates an indexing value ex-
             ceeded the maximum negative or maximum  positive  value
             for the current variable size.

         2.  The  Unsigned  value  error indicates an indexing value
             was greater than maximum positive value for the current
             variable size.

         3.  The  byte PCR error is caused by exceeding the pc rela-
             tive byte branch range.

         4.  The  word PCR error is caused by exceeding the pc rela-
             tive word branch range.

         5.  The  3-byte PCR error is caused by exceeding the pc re-
             lative 3-byte branch range.

         6.  The  4-byte PCR error is caused by exceeding the pc re-
             lative 4-byte branch range.

         7.  The  Page0  error is generated if the direct page vari-
             able is not in the page0 range of 0 to 255.

         8.  The  PageN  error is generated if the direct page vari-
             able is not within the Nth page range of 0 to 255.

         9.  The  PageX  error is generated if the direct page vari-
             able is not within the extended page range.

        10.  The  Signed Merge Bit Range error indicates an indexing
             value exceeded the maximum negative or maximum positive
             value for the current signed merge variable size.

        11.  The  Unsigned/Overflow  Merge Bit Range error indicates
             an indexing value was  greater  than  maximum  positive
             value for the current unsigned merge variable size.

##### Return to the Linker Index

### ... Linker V3 Input Format

####

       The  linkers'  input  object file is an ascii file containing
    the information needed by the linker  to  bind  multiple  object
    modules into a complete 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
            A       Area
            S       Symbol
            T       Object code
            R       Relocation information
            P       Paging information

- Object Module Format
- Header Line
- Module Line
- Symbol Line
- Area Line
- T Line
- R Line
- P Line
- Return to the Linker Index

####

    Object Module Format

       The   first   line   of   an   object   module  contains  the
    [XDQ][HL][234] format specifier  (i.e.   XH2  indicates  a  hex-
    idecimal  file  with  most significant byte first and 16-bit ad-
    dressing) for the following designators.

##### => Section Index

####

    Header Line

            H aa areas gg global symbols

       The  header  line  specifies  the number of areas(aa) and the
    number of global symbols(gg) defined or referenced in  this  ob-
    ject module segment.

##### => Section Index

####

    Module Line

            M name

       The  module  line  specifies  the module name from which this
    header segment was assembled.  The module line will  not  appear
    if the .module directive was not used in the source program.

##### => Section Index

####

    Symbol Line

            S string Defnnnn

                    or

            S string Refnnnn

       The  symbol line defines (Def) or references (Ref) the symbol
    'string' with the value nnnn.  The defined value is relative  to
    the  current  area  base  address.   References to constants and
    external global symbols will always appear before the first area
    definition.  References to external symbols will have a value of
    zero.

##### => Section Index

####

    Area Line

            A label size ss flags ff

       The  area  line  defines the area label, the size (ss) of the
    area in bytes, and the area flags (ff).  The area flags  specify
    the ABS, REL, CON, OVR, and PAG parameters:

            OVR/CON  (0x04/0x00 i.e.  bit position 2)

            ABS/REL  (0x08/0x00 i.e.  bit position 3)

            PAG      (0x10 i.e.  bit position 4)

##### => Section Index

####

    T Line

            T xx xx nn nn nn nn nn ...

       The  T  line contains the assembled code output by the assem-
    bler with xx xx being the offset address from the  current  area
    base address and nn being the assembled instructions and data in
    byte format.

##### => Section Index

####

    R Line

            R 0 0 nn nn n1 n2 xx xx ...

       The R line provides the relocation information to the linker.
    The nn nn value is the current area index, i.e.  which area  the
    current  values  were  assembled.  Relocation information is en-
    coded in groups of 4 bytes:

         1.  n1  is  the  relocation mode and object format, for the
             adhoc extension modes refer to asxxxx.h or aslink.h
             1.  bit 0  word(0x00)/byte(0x01)
             2.  bit 1  relocatable area(0x00)/symbol(0x02)
             3.  bit 2  normal(0x00)/PC relative(0x04) relocation
             4.  bit 3  1-byte(0x00)/2-byte(0x08)  object format
             5.  bit 4  signed(0x00)/unsigned(0x10) byte data
             6.  bit 5  normal(0x00)/page '0'(0x20) reference
             7.  bit 6  normal(0x00)/page 'nnn'(0x40) reference
             8.  bit 7  LSB  byte(0x00)/MSB  byte(0x80)

         2.  n2  is  a byte index into the corresponding (i.e.  pre-
             ceding) T line data (i.e.  a pointer to the data to  be
             updated  by  the  relocation).   The T line data may be
             1-byte or  2-byte  byte  data  format  or  2-byte  word
             format.

         3.  xx xx  is the area/symbol index for the area/symbol be-
             ing referenced.  the corresponding area/symbol is found
             in the header area/symbol lists.

    The groups of 4 bytes are repeated for each item requiring relo-
    cation in the preceding T line.

##### => Section Index

####

    P Line

            P 0 0 nn nn n1 n2 xx xx

       The  P  line provides the paging information to the linker as
    specified by a .setdp directive.  The format of  the  relocation
    information is identical to that of the R line.  The correspond-
    ing T line has the following information:
            T xx xx aa aa bb bb

       Where  aa aa is the area reference number which specifies the
    selected page area and bb bb is the base address  of  the  page.
    bb bb will require relocation processing if the 'n1 n2 xx xx' is
    specified in the P line.  The linker will verify that  the  base
    address is on a 256 byte boundary and that the page length of an
    area defined with the PAG type is not larger than 256 bytes.

       The  linker  defaults any direct page references to the first
    area defined in the input REL file.  All ASxxxx assemblers  will
    specify the _CODE area first, making this the default page area.

##### => Section Index

####

    24-Bit and 32-Bit Addressing

       When  24-bit  or  32-bit  addressing is specified in the file
    format line [XDQ][HL][234] then the S and T Lines have  modified
    formats:
            S string Defnnnnnn                      (24-bit)
            S string Refnnnnnn                      (24-bit)
            T xx xx xx nn nn nn nn nn ...           (24-bit)

            S string Defnnnnnnnn                    (32-bit)
            S string Refnnnnnnnn                    (32-bit)
            T xx xx xx xx nn nn nn nn nn ...        (32-bit)

       The  multibyte  formats for byte data replace the 2-byte form
    for 16-bit data with 3-byte or 4-byte data for 24-bit or  32-bit
    data  respectively.  The 2nd byte format (also named MSB) always
    uses the second byte of the 2, 3, or 4-byte data.

##### => Section Index

### ... Linker V3 Error Messages

####

       The linker provides detailed error messages allowing the pro-
    grammer to quickly find the errant code.   As  the  linker  com-
    pletes  pass 1  over  the  input  file(s)  it  reports  any page
    boundary or page length errors as follows:

    ?ASlink-Warning-Paged Area PAGE0 Boundary Error

    and/or

    ?ASlink-Warning-Paged Area PAGE0 Length Error

    where PAGE0 is the paged area.

       During  Pass  two the linker reads the T, R, and P lines per-
    forming the necessary relocations and  outputting  the  absolute
    code.  Various errors may be reported during this process.

    The P line processing can produce only one possible error:

    ?ASlink-Warning-Page Definition Boundary Error
             file        module      pgarea      pgoffset
      PgDef  t6809l      t6809l      PAGE0       0001

    The error message specifies the file and module where the .setdp
    direct was issued and indicates  the  page  area  and  the  page
    offset value determined after relocation.

    The R line processing produces various errors:

    ?ASlink-Warning-Byte PCR relocation error for symbol  bra2
    ?ASlink-Warning-Unsigned Byte error for symbol  two56
    ?ASlink-Warning-Page0 relocation error for symbol  ltwo56
    ?ASlink-Warning-Page Mode relocation error for symbol  two56
    ?ASlink-Warning-Page Mode relocation error
    ?ASlink-Warning-2K Page relocation error
    ?ASlink-Warning-512K Page relocation error

    These  error  messages  also specify the file, module, area, and
    offset within the area of the code referencing (Refby)  and  de-
    fining (Defin) the symbol:

    ?ASlink-Warning-Unsigned Byte error for symbol  two56
             file        module      area        offset
      Refby  t6800l      t6800l      DIRECT      0015
      Defin  tconst      tconst      .  .ABS.    0100

    If the symbol is defined in the same module as the reference the
    linker is unable to report the symbol name.  The assembler list-
    ing  file(s) should be examined at the offset from the specified
    area to locate the offending code.

       The errors are:

         1.  The  byte PCR error is caused by exceeding the pc rela-
             tive byte branch range.

         2.  The Unsigned byte error indicates an indexing value was
             negative or larger than 255.

         3.  The  Page0  error is generated if the direct page vari-
             able is not in the page0 range of 0 to 255.

         4.  The page mode error is generated if the direct variable
             is not within the current direct page (6809).

         5.  The  2K  Page  relocation  error  is  generated  if the
             destination is not within the current  2K  page  (8051,
             DS8xCxxx).

         6.  The  512K  Page  relocation  error  is generated if the
             destination  is  not  within  the  current  512K   page
             (DS80C390).

##### Return to the Linker Index

### ... Hint File Format For Relocated Listings

####

       The hint file is an ascii file containing information to help
    the linker convert the listing file  into  a  relocated  listing
    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 present it 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.

       If  a  hint  file  does not exist then the linker attempts to
    convert the list file to a relocated list file using some  basic
    assumptions  about the parameters listed in each line.  The con-
    version without a hint file  requires  at  least  these  listing
    parameters:   LOC,  BIN,  MEB, and ME.  The 'equate' values will
    not be updated.

##### Return to the Linker Index

### ... Intel IHX Output Format (16-Bit)

####

    Record Mark Field    -  This  field  signifies  the  start  of a
                            record, and consists of an  ascii  colon
                            (:).

    Record Length Field  -  This   field   consists   of  two  ascii
                            characters which indicate the number  of
                            data   bytes   in   this   record.   The
                            characters are the result of  converting
                            the  number  of  bytes  in binary to two
                            ascii characters, high digit first.   An
                            End  of  File  record contains two ascii
                            zeros in this field.

    Load Address Field   -  This  field  consists  of the four ascii
                            characters which result from  converting
                            the binary value of the address in which
                            to begin loading this record.  The order
                            is as follows:

                                High digit of high byte of address.
                                Low digit of high byte of address.
                                High digit of low byte of address.
                                Low digit of low byte of address.

                            In an End of File record this field con-
                            sists of either four ascii zeros or  the
                            program  entry address.  (Note:  The use
                            of the end of file record to  specify  a
                            start  address for a 16-Bit addresses is
                            not part of the official Intel  specifi-
                            cation.)

    Record Type Field    -  This  field  identifies the record type,
                            which is either 0 for data, 1 for an End
                            of  File, or 5 for an Extended Start Ad-
                            dress record.  It consists of two  ascii
                            characters,  with  the high digit of the
                            record type first, followed by  the  low
                            digit of the record type.

    Data Field           -  This  field consists of the actual data,
                            converted to two ascii characters,  high
                            digit first.  There are no data bytes in
                            the standard End of File record.

    Checksum Field       -  The  checksum  field is the 8 bit binary
                            sum of the record length field, the load
                            address  field,  the  record type field,
                            and the data field.  This  sum  is  then
                            negated  (2's  complement) and converted
                            to  two  ascii  characters,  high  digit
                            first.

##### Return to the Linker Index

### ... Motorola S1-S9 Output Format (16-Bit)

####

    Record Type Field    -  This  field  signifies  the  start  of a
                            record and identifies the record type as
                            follows:

                                Ascii S1 - Data Record
                                Ascii S9 - End of File Record

    Record Length Field  -  This  field  specifies the record length
                            which includes the  address,  data,  and
                            checksum   fields.   The  8  bit  record
                            length value is converted to  two  ascii
                            characters, high digit first.

    Load Address Field   -  This  field  consists  of the four ascii
                            characters which result from  converting
                            the binary value of the address in which
                            to begin loading this record.  The order
                            is as follows:

                                High digit of high byte of address.
                                Low digit of high byte of address.
                                High digit of low byte of address.
                                Low digit of low byte of address.

                            In an End of File record this field con-
                            sists of either four ascii zeros or  the
                            program  entry  address.

    Data Field           -  This  field consists of the actual data,
                            converted to two ascii characters,  high
                            digit first.  There are no data bytes in
                            the End of File record.

    Checksum Field       -  The  checksum  field is the 8 bit binary
                            sum of the record length field, the load
                            address field, and the data field.  This
                            sum is then  complemented  (1's  comple-
                            ment)   and   converted   to  two  ascii
                            characters, high digit first.

##### Return to the Linker Index

### ... Motorola S2-S8 Output Format (24-Bit)

####

    Record Type Field    -  This  field  signifies  the  start  of a
                            record and  dentifies the record type as
                            follows:

                                Ascii S2 - Data Record
                                Ascii S8 - End of File Record

    Record Length Field  -  This  field  specifies the record length
                            which includes the  address,  data,  and
                            checksum   fields.   The  8  bit  record
                            length value is converted to  two  ascii
                            characters, high digit first.

    Load Address Field   -  This  field  consists  of  the six ascii
                            characters which result from  converting
                            the binary value of the address in which
                            to begin loading this record.  The order
                            is as follows:

                                High digit of 3rd byte of address.
                                Low digit of 3rd byte of address.
                                High digit of high byte of address.
                                Low digit of high byte of address.
                                High digit of low byte of address.
                                Low digit of low byte of address.

                            In an End of File record this field con-
                            sists of either six ascii zeros  or  the
                            program  entry  address.

    Data Field           -  This  field consists of the actual data,
                            converted to two ascii characters,  high
                            digit first.  There are no data bytes in
                            the End of File record.

    Checksum Field       -  The  checksum  field is the 8 bit binary
                            sum of the record length field, the load
                            address field, and the data field.  This
                            sum is then  complemented  (1's  comple-
                            ment)   and   converted   to  two  ascii
                            characters, high digit first.

##### Return to the Linker Index

### ... Motorola S3-S7 Output Format (32-Bit)

####

    Record Type Field    -  This  field  signifies  the  start  of a
                            record and identifies the  record type as
                            follows:

                                Ascii S3 - Data Record
                                Ascii S7 - End of File Record

    Record Length Field  -  This  field  specifies the record length
                            which includes the  address,  data,  and
                            checksum   fields.   The  8  bit  record
                            length value is converted to  two  ascii
                            characters, high digit first.

    Load Address Field   -  This  field  consists of the eight ascii
                            characters which result from  converting
                            the binary value of the address in which
                            to begin loading this record.  The order
                            is as follows:

                                High digit of 4th byte of address.
                                Low digit of 4th byte of address.
                                High digit of 3rd byte of address.
                                Low digit of 3rd byte of address.
                                High digit of high byte of address.
                                Low digit of high byte of address.
                                High digit of low byte of address.
                                Low digit of low byte of address.

                            In an End of File record this field con-
                            sists of either eight ascii zeros or the
                            program  entry  address.

    Data Field           -  This  field consists of the actual data,
                            converted to two ascii characters,  high
                            digit first.  There are no data bytes in
                            the End of File record.

    Checksum Field       -  The  checksum  field is the 8 bit binary
                            sum of the record length field, the load
                            address field, and the data field.  This
                            sum is then  complemented  (1's  comple-
                            ment)   and   converted   to  two  ascii
                            characters, high digit first.

##### Return to the Linker Index

### ... Tandy Color Computer Disk Basic Format

####

    Record Preamble      -  This  field  is either $00 (for start of
                            new record) or $FF (for last  record  in
                            file).

    Record Length Field  -  This  field specifies the number of data
                            bytes which follows the  address  field.
                            The  length  is  in  binary  MSB  to LSB
                            order.

                                16-Bit Length - 2-bytes
                                24-Bit Length - 3-bytes
                                32-Bit Length - 4-bytes

    Load Address Field   -  This field consists of the address where
                            the record will be loaded  into  memory.
                            The  address  is  in  binary  MSB to LSB
                            order.

                                16-Bit Address - 2-bytes
                                24-Bit Address - 3-bytes
                                32-Bit Address - 4-bytes

    Data Field           -  This field consists of the actual binary
                            data.

       After  the  last  code  segment,  a final record like the one
    above is placed.  In this final segment, the Record Preamble  is
    $FF, the Record Length Field is $0000 and the Load Address Field
    is the execution address.

##### Return to the Linker Index

... Exit the ASxxxx Documentation

... Home Page

###### Last Updated: May 2026