## The Linker Description

### ... Invoking ASlink

####

#####

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

            aslink -[options] -[option arg] files

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

            aslink
            argv:  -[options] -[option arg] files

    The allowed linker commands are:

         1.  -c         ASlink >> prompt mode.
             The  ASlink >>  prompt  mode reads linker commands from
             stdin.

         2.  -f  file   Command file mode.
             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  com-
             mand  file  then  the  path  defaults  to the .lnk file
             directory path.

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

         4.  -i/-s   Intel Hex (file.ihx) or Motorola S19 (file.s19)
             image output file.

         5.  -o/-v   Specifies      that      subsequent      linked
             files/libraries will generate object  output  (default)
             or  suppress  object  output.   (if option -s or -i was
             specified)

         6.  -z      Specifies that symbol names are case sensitive.

         7.  -m      Generate a map file (file.map).  This file con-
             tains a list of the symbols (by area) with absolute ad-
             dresses,  sizes  of  linked  areas,  and  other linking
             information.

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

         9.  -xdq    Specifies  the  number  radix  for the map file
             (Hexidecimal, Decimal, or Octal).

        10.  -u      Generate  an  updated  listing  file (file.rst)
             derived from the relocated addresses and data from  the
             linker.

        11.  file    File(s) to be linked.  Files may be on the same
             line as the above options or on a separate line(s)  one
             file  per line or multiple files separated by spaces or
             tabs.

        12.  -b  area=expression (one definition per line)
             This  specifies  an area base address where the expres-
             sion may contain constants and/or defined symbols  from
             the linked files.

        13.  -g  symbol=expression (one definition per line)
             This  specifies  the value for the symbol where the ex-
             pression may contain constants and/or  defined  symbols
             from the linked files.

        14.  -k  library directory path
             (one  definition  per line) This specifies one possible
             path to an object library.  More than one path  is  al-
             lowed.

        15.  -l  library file specification
             (one  definition  per  line)  This specifies a possible
             library file.  More than one file is allowed.

        16.  -e      or null line, terminates input to the linker.

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

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

       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 existant 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  -b
    (area  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 overlayed and have been assembled at a
    specific address, these are not normally relocated (if a -b com-
    mand  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 -b command speci-
    fies the beginning address of the area.  All subsequent relative
    areas  will  be  concatenated  with  proceeding  relative areas.
    Where specific ordering is desired, the first linker input  file
    should  have  the area definitions in the desired order.  At the
    completion 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.

       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  preceeding  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 -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  or
    Motorola  formats.   The  number of files linked and symbols de-
    fined/referenced is limited by the processor 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 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]
                    X       Hexidecimal radix
                    D       Decimal radix
                    Q       Octal radix

                    H       Most significant byte first
                    L       Least significant byte first

            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]
    format specifier (i.e.  XH indicates  a  hexidecimal  file  with
    most significant byte first) 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 for
                 byte data
             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)  with 2-byte
                 mode

         2.  n2  is  a byte index into the corresponding (i.e.  pre-
             ceeding) 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 preceeding 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

    ... Linker 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
             file        module      area        offset
      Refby  t6809l      t6809l      TEST        00FE
      Defin  tconst      tconst      .  .ABS.    0080

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

    ?ASlink-Warning-Page0 relocation error for symbol  ltwo56
             file        module      area        offset
      Refby  t6800l      t6800l      DIRECT      000D
      Defin  tconst      tconst      DIRECT      0100

    ?ASlink-Warning-Page Mode relocation error for symbol  two56
             file        module      area        offset
      Refby  t6809l      t6809l      DIRECT      0005
      Defin  tconst      tconst      .  .ABS.    0100

    ?ASlink-Warning-Page Mode relocation error
             file        module      area        offset
      Refby  t           Pagetest    PROGRAM     0006
      Defin  t           Pagetest    DIRECT      0100

    These  error messages specify the file, module, area, and offset
    within the area of the code  referencing  (Refby)  and  defining
    (Defin) the symbol.  If the symbol is defined in the same module
    as the reference the linker is unable to report the symbol name.
    The  assembler  listing file(s) should be examined at the offset
    from the specified area to located 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).

      Return to the Linker Index

    ... Intel Hex Output Format

    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  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.   Currently the
                            entry address option is not supported.

    Record Type Field    -  This  field  identifies the record type,
                            which is either 0 for data records or  1
                            for  an End of File 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 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

    Record Type Field    -  This  field  signifies  the  start  of a
                            record and  identifies  the  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  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.   Currently the
                            entry address option is not supported.

    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

    ...  Exit the ASxxxx Documentation

    ...  Home Page