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.i--) or Motorola S19 (file.s--) 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.
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).)
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.
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 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.
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.
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.
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.
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)
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.
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) 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.
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.
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.
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 ?ASlink-Warning-2K Page relocation error file module area offset Refby t Pagetest A 0000 Defin t Pagetest A 0800 ?ASlink-Warning-512K Page relocation error file module area offset Refby t Pagetest A 000000 Defin t Pagetest A 080000 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 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).
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.
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, 1 for an End of File record, or 4 for a segment 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.
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.
Record Type Field - This field signifies the start of a record and identifies the 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 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. 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.
Record Type Field - This field signifies the start of a record and identifies the 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 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. 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.