Copyright © 1982 by
Technical Systems Consultants, Inc.
111 Providence Road
Chapel Hill, North Carolina 27514
All Rights Reserved.
™FLEX is a trademark of Technical Systems Consultants, Inc.
Table of Contents Page
1. INTRODUCTION
1.1. Preface 1
1.2. Terminology 1
1.3. Linking Loader Input 2
1.4. Linking Loader Output 2
2. INVOKING THE LOADER 3
3. LIBRARIES 7
3.1. Introduction 7
3.2. Library Generation 7
4. MEMORY ASSIGNMENT 9
4.1. Relocatable and Executable Files. 9
4.2. Relocatable Modules 9
4.3. Executable Programs 10
5. LOAD AND MODULE MAPS 11
5.1. Load Maps 11
5.2. Module Maps 11
5.2.1. Module Map of a Relocatable Module 11
5.2.2. Module Map of an Absolute Program 12
6. MISCELLANEOUS 13
6.1. Transfer Address 13
7. ERROR MESSAGES 14
8. APPENDIX A 17
-iii
FLEX Linking Loader
1. INTRODUCTION
1.1. Preface
This manual describes the use and operation of the FLEX Linking Loader.
It is assumed the reader is familiar with the operation of the FLEX 6809
Relocating Assembler, and is comfortable with the concepts of
relocation and linkage editing.
Throughout the manual a couple of notational conventions are used which
are explained here. Angle brackets ('<' and '>') are often used to
enclose the description of a single item even though the description may
require several words. Square brackets ('[' and ']') are used to
enclose an optional item.
1.2. Terminology
absolute module
A subprogram assembled by the relocating assembler which makes use
of the "ABS" and "ORG" directives. Addresses in these modules are
bound to absolute locations at assembly time and cannot be
relocated by the linking loader.
file
A FLEX file containing one or more object-code modules.
file name
The name of a FLEX file.
loading
The placement of instructions and data into memory in preparation
for execution. This preparation includes linking (the matching of
symbolic references and definitions), and relocation of symbols and
address expressions.
module
A general term for either an absolute or relocatable module which
has been assembled using the 6809 relocating assembler.
module name
The name given to a module by the programmer by using the "name"
directive of the relocating assembler. If the "name" directive was
not used, the module name is the same as the FLEX file name in
which it is contained. Therefore, several modules may have the
same name. A relocatable output module of the loader may be given
a name by use of the "N" option.
-1
FLEX Linking Loader
relocatable module
A subprogram assembled by the relocating assembler which does not
contain an "ABS" directive. Addresses in a relocatable object-code
module are not bound to absolute locations at assembly time.
1.3. Linking Loader Input
Technical System Consultants Inc.'s Linking Loader will accept as input
independently assembled, relocatable and/or absolute modules.
Relocatable object-code is generated by the FLEX relocating assembler
"RELASMB" in such a way that addresses are not bound to absolute
locations at assembly time; this binding of the address fields will be
accomplished by the Linking Loader. "LLOAD" binds the addresses at the
time the object-code segments are combined to produce an executable
program. The binding or adjustment of the address fields is termed
"relocation". Relocation is necessary when an instruction expects an
absolute address as an operand. The address field of this instruction
must be increased by a "relocation constant". The relocation constant
is the address at which the module is loaded for execution.
Address fields which do not require relocation are absolute addresses
(their values remain the same regardless of the position of the
object-code segment in memory). Since the loader does not have access
to the source text, it cannot determine if an address field is absolute
or relocatable. In fact, it cannot distinguish addresses from data or
opcodes. Therefore, the assembler must indicate to the loader the
address fields which require relocation. This communication is
accomplished through "relocation records" which are appended to the
object-code produced by the assembler. Such a file is called a
"relocatable module".
Absolute object-code modules, on the other hand, have had all of its
address fields bound to absolute locations at assembly time. These
modules will not be relocated by the linking loader; rather, they will
be loaded where they were "ORGed".
1.4. Linking Loader Output
As output, "LLOAD" produces an object-code module, a load map, a module
map, and a global symbol table. The object-code module can be either a
relocatable module or an executable program. A relocatable module
produced by the loader cannot be distinguished from a relocatable module
produced by "RELASMB". Only the loader, however, can transform multiple
relocatable modules into an executable program. If absolute modules are
included as input to the loader, the output must be executable or an
error will result. An executable program cannot be distinguished from
programs produced by the absolute assembler "ASMB".
-2
FLEX Linking Loader
2. INVOKING THE LOADER
The Linking loader accepts as input previously assembled object-code
modules and produces as output:
1) A link edited, relocatable, object-code module or
2) a link edited, relocated, executable program.
The command line necessary to invoke the linking loader is as follows:
+++LLOAD [+options]
where:
the three plus signs are FLEX's ready prompt, and "LLOAD" is the
name of the linking loader command file.
"input file list" is a list of one or more FLEX file names,
separated by blanks, which contain the modules you wish to load.
The modules will be loaded in the order specified.
"options" is a list of options which must start with a plus sign
("+") and may not contain any embedded spaces. More than one list
of options may be specified, but each list must start with a plus
sign. Some of the options are single characters while others
require an argument. Those that are single letters may be grouped
together; for example: +PD. Those that require arguments may
either stand alone or be the last of a group of options; for
example: +PMA=100, where the "A=100" is an option with an argument.
The equal sign is not required in options with an argument.
Therefore, "+A=100" is equivalent to "+A100".
Following is a detailed description of each of the valid options.
+A=addr
The binary output of the linking loader is to be executable,
and its beginning load address (in hex) is to be "addr". If
this option is not selected, the binary output will be
relocatable object-code.
+B Do not create a binary file on disk. This is useful when
link-editing a program to check for errors before the final
program is completed or when obtaining a Global Symbol Table.
+C The output file is to have an extension of CMD. If the "B"
option was selected, the "C" option is ignored.
-3
FLEX Linking Loader
+D Do not print the date at the top of each page when the "P"
option is specified. If the "P" option is not specified, the
"D" option is ignored.
+F Each file specified in "input file list" is a text file
containing a list of one or more file names of object-code
modules. The file names must be on separate lines.
+G=go-time command line
After the program has been link-edited and relocated,
execution control is passed to the program, starting at the
address specified by the transfer address. The "G" option
must be the last option specified on the calling command line.
+I Include all internal symbols in the symbol table for symbolic
debugging. If the "A" option is also specified, the "I"
option has no effect. If the "I" option is not specified,
only global symbols are included in the relocatable module.
+L= A maximum of five libraries may be
specified by repeated use of the "L" option. Libraries are
only searched when an executable output program is specified
(by using the "A" option). In the following example, an
effort is made to resolve externals not found in the user's
modules by searching the libraries LIB1 and LIB2.
+++LLOAD ECHO.REL +A +L=LIB1 +L=LIB2
See the LIBRARIES chapter (chapter 3) for more information
concerning the formation and use of libraries.
+M Print the Load and Module Maps. The Load Map provides
information about the type of output file (relocatable,
executable or none) produced, the length of the resulting
object-code module and the transfer address. The Module Map
describes the load address and object-code length of each
input module.
+N=
The "module name" is given to the output module of the loader
in a manner similar to the "NAME" directive of the relocating
assembler. Since the loader does not propogate the module
names of the relocatable input modules to the output module,
the "N" option must be used to assign a name to a module. If
this option is not used, the module name will default to the
name of the file in which it is contained. Only relocatable
modules can receive module names, so "N" is ignored if "A" is
specified. The name is limited to a maximum of 8 characters.
+P Selects pagination of the printed output. The date (if the
"D" option is not specified) and a page number are included at
the top of each page.
-4
FLEX Linking Loader
+O=file-spec
Allows specification of an output binary file name. If the
"O" option is not specified, the output file name will be
"OUTPUT" on the work drive. The extension, if not specified,
will be forced to .BIN if the "A=" option was specified, or to
.REL if the "A=" option was not specified. Use of the "C"
option overrides the above defaults. If a file by this name
already exists on the specified drive, a request will be
issued to delete the old file.
+S Select printing of the Global Symbol Table. If specified, the
linking loader will print each global symbol and its address.
+Y This option overrides the prompt for deleting an existing
binary file. In other words, if the "Y" option is specified,
an existing binary file with the same name as the one to be
created will be automatically deleted without a prompt.
+U Do not print the "unresolved external" message when producing
a relocatable output module.
+Z Force zero code suppression. When the loader is being used to
produce executable output, this option will cause the deletion
of any continuous groups of 16 or more zero bytes. If only
relocatable output is being produced this option will have no
effect. Although this option has many uses, a good example
use of the option is to save disk space when storing compiled
FORTRAN programs with large arrays. If a FORTRAN program
declares a large array, the assembly code produced by the
compiler will reserve space for that array by zeroing out the
necessary area. This zeroed area will be included with the
binary code and stored on the disk. If some large arrays are
being created in the FORTRAN program this could be very
wasteful of disk space. The Z option will delete large zeroed
out areas, thus making it possible to store more on a disk.
One caution must be made when using this Z option and then
running the FORTRAN program produced by it. If the program
assumes that the arrays are already zeroed out, then using the
Z option could cause problems. One way around this is to make
sure in the FORTRAN program that no variable is used without
having a value assigned to it. Another way is to write a
short utility (see appendix A) that will zero all memory, and
then execute the FORTRAN program. The former is the
recommended approach since it is good programming practice to
make assignments or initializations to all variables before
using them.
-5
FLEX Linking Loader
EXAMPLES
1.
Link-edit the file "DOING" from drive 1 and call the output file
"DONE" which should also end up on drive 1. The code should be
executable binary output. Therefore the output file should have a
".CMD" extension.
LLOAD DOING.1 +O=1.DONE +CA=0000
This would link edit the file "DOING" from drive 1 and put the
output into "DONE.CMD" (+C option) also on drive 1, which is
executable binary code whose beginning load address is 0000 hex.
2.
Get all the information possible about a link-edit attempt of file
"DOING" but do not produce any binary output.
LLOAD DOING +BIMS
There will be no binary output from this run (+B option), but all
internal symbols will be included in the symbol table (+I option),
the Load Map and Module Map will be printed (+M option), and the
Global Symbol Table is also printed (+S option). This might be done,
if the user was trying to track down some error in a program.
-6
FLEX Linking Loader
3. LIBRARIES
3.1. Introduction
The linking loader can search up to five libraries when there are
externals which cannot be resolved from the user's modules.
A library is a special collection of relocatable modules. When an
external cannot be resolved from the user's modules, the libraries are
searched in an effort to resolve it. The linking loader will search the
libraries in the order specified on the command line. The search for an
external can be summarized as follows:
1) Can the external be resolved from the user's modules?
2) Can it be found in the user specified libraries?
When an external is resolved from a module contained in a library, the
module is loaded and is then considered a "user" module. Therefore,
library modules can reference other library modules.
3.2. Library Generation
The "LIB-GEN" utility is used to create new libraries and update
existing libraries. All modules in a library must have a name. The
name is assigned to a module by the "NAME" pseudo-op in the relocating
assembler or by the "N" option of the linking loader. It is the
responsibility of the programmer to ensure that all modules in a library
have names. "LIB-GEN" will not accept a module without a name.
The "LIB-GEN" utility is called with a command of the following general
form:
LIB-GEN O=,N=,U=,,
The arguments may be specified in any order.
The argument "O=" specifies the name of an existing library file.
The library file must have been created previously by "LIB-GEN". If
"LIB-GEN" is being called to create a new library then this should be
omitted.
The argument "N=" specifies the name of the new library. If this
file already exists, it will be deleted before the new library is
written. This argument is not needed when updating an existing library.
In this case, "LIB-GEN" will put the new library in a scratch file,
delete the old library file, and rename the scratch file, giving it the
name of the old library. It is not permitted to omit both the "O="
and "N=" arguments.
-7
FLEX Linking Loader
The argument "U=" specifies the name of a file containing
modules to add to the library, replacing existing modules in the library
if necessary. Up to nine files may be specified by repeating the "U="
argument. See the examples below.
As "LIB-GEN" runs, it produces a report, describing the action that it
has taken for each module in the library. The report includes the
module name and the file from which it was read (the old library or one
of the update files). The options are used to eliminate or shorten this
report. If the option "+L" is specified, no report will be produced.
If the option "+A" is specified, the report will only contain
information about those modules that were replaced, added, or deleted.
No information about modules copied from the old library will be given.
The "" argument is a list of module names that are to be
deleted from the old library. The names may be separated by commas or
spaces. If a name is specified that cannot be found in the old library,
a warning message is issued. If the "+L" option was specified, no
warning is issued.
EXAMPLES
1. Create a new library with the name "BINLIB" containing
Modules from
the files "ONE", "TWO", and "THREE".
LIB-GEN N=BINLIB U=ONE U=TWO U=THREE
Since a new library is being created, the "O=" argument was
omitted. Note that the "U=" argument was repeated for each update
file.
2. Update the library named "BINLIB", adding or replacing
records from
the file "NEW". Produce an abbreviated report.
LIB-GEN O=BINLIB U=NEW +A
Since no new library was specified, the new library will be given the
name of the old library.
3. Update
the library named "BINLIB", deleting the modules named
"DIAGONAL" and "TRANSPOSE". Also add new modules from the file "XYZ"
and write the new library in the file "NEWLIB".
LIB-GEN O=BINLIB U=XYZ N=NEWLIB TRANSPOSE DIAGONAL
-8
FLEX Linking Loader
4. MEMORY ASSIGNMENT
4.1. Absolute Modules
The use of the "ABS" directive signals the relocating assembler to
produce absolute object-code. Addresses in absolute modules are bound
to absolute locations by the assembler by employing the "ORG" directive.
Absolute modules cannot be relocated by the loader. In addition to not
being "relocatable", absolute modules are not executable because they
are not FLEX binary files. The relocating assembler does not have the
capability of producing executble object-code; only the absolute
assembler and the linking loader have this ability.
4.2. Relocatable Modules
If the "ABS" directive is ommitted from the assembler source code,
relocatable object-code will be produced. Relocatable modules do not
have their addresses bound to absolute locations by the relocating
assembler. This task of relocation is passed on to the loader. The
linking loader can also produce a relocatable module by combining one or
more relocatable (not absolute) modules and not using the "A" option.
Use of the "A" option causes-the linking loader to produce an executable
program.
Common blocks are not combined with other modules when the loader
produces a relocatable module. Instead, common blocks retain their
identity as separate modules and are appended to the resulting
relocatable output module. Common areas wil] be linked with the other
modules only when producing an executable program.
Relocatable modules can be given module names by the use of the "NAME"
directive of the relocating assembler. This name is used when printing
the module map. If no name was given to a module by use of the "NAME"
directive, the name of the file in which it is contained is printed.
When producing a relocatable output module, the linking loader does not
propagate any of these module names to the output module. To assign the
output module a name, use the "N" option when invoking the loader.
-9
FLEX Linking Loader
4. 3. Executable Programs
When loading modules to produce an executable program, it is guaranteed
that the user modules are loaded first in the order specified on the
command line. Common areas are loaded after the last module specified
on the command line. Libraries are loaded after the last common block,
or after the last user module on the command line if there are no common
blocks.
In this type of file, the binary is stored in a record format where each
record has it own load address and contains the object-code of one
module. The user can specify the initial program load address (IPLA) of
the first record (module) by use of the "A" option. Successive modules
are loaded in the order specified on the command line and immediately
follow the previous module. In other words, the program is loaded
continuously starting at IPLA.
The following memory map illustrates how the individual modules are
placed in relation to other modules. The module numbers are the order
in which they appear on the command line; "m" is the last module
specified. Common blocks 1-x and library modules 1-n which are loaded
to complete the program are also represented.
IPLA --> module 1
module 2
.
.
.
module m
common 1
common 2
.
.
.
common x
library 1
library 2
.
.
.
library n
-10
FLEX Linking Loader
5. LOAD AND MODULE MAP
5.1. Load Map
The "M" option controls the printing of the module and load maps. When
selected, the load map will provide information as to the type of output
produced, the length of the resulting output object-code module, the
number of input modules, and the transfer address.
5.2. Module Map
Use of the "M" option also selects printing of the module map. The
module map describes the load addresses and object-code length for each
of the input modules. The load addresses for each of the segments
(text, data, and bss) take on different meanings depending on the type
of output file produced.
5.2.1. The Module Map of a Relocatable Module
When producing a relocatable module, both the relocating assembler and
the linking loader do not "bind" or tie addresses to absolute locations;
they are made relative to a base. The following example assembled by
the relocating assembler will illustrate this point.
1 EXT PDATA
2
3 + 0000 8E 0010 START LDX #MSG1 POINT TO 1ST MESSAGE
4 +>0003 BD 0009 JSR SUB1 PRINT IT
5 + 0006 8E 001A LDX #M1SG2 POINT TO 2ND MESSAGE
6 + 0009 BF 002D SUB1 STX MSGADDR SAVE MESSAGE ADDRESS
7 X 000C BD 0000 JSR PDATA PRINT A MESSAGE
8 000F 39 RTS ALL DONE
9
10 0010 4D 45 53 53 MSG1 FCC 'MESSAGE 1',0
11 0014 4D 45 53 53 MSG2 FCC 'MESSAGE 2',0
12
13 0024 00 000000 RMBB 9
14 002D 00 00 MSGADDR RMB 2 MSSGE ADDR SAVE AREA
15
16 + END START
This example shows that the address of the first instruction of 'PDATA'
starts at '0000'. When this module is linked with other modules, each
of the addresses will be added to a base to give the address for the
output file.
-11
FLEX Linking Loader
As an example, three modules called PDATA, MAIN and CNTCH were
asssembled separately. Each was assembled with a starting address of
'0000'.
module aThe three modules were then linked to
nd the following load and module maps.
produce a relocatable
Errors Detected.
CNTCH in 1.MAIN.REL, unresolved.
PDATA in 1.MAIN.REL, unresolved.
Load Map.
No output file produced.
Program length: 0056
Transfer address: 0000
Module Map
MODULE NAME ADDR SIZE
1.MAIN
1.CNTCH
1.TEST
.REL
.REL
.REL
0000
0009
0027
0009001E002F
The program length is the sum of the lengths of all
transfer address is seen to be in the module "MAIN".
the modules. The
5.2.2. The Module Map of an Absolute Program
When creating an absolute, executable program, the user can specify the
initial program load address (IPLA), and all address expressions are
relocated relative to the IPLA. The same modules used in the
relocatable example above were linked with an IPLA of $100 to produce
the following load map:
Load Map
Absolute file produced.
Program length: 0056
Transfer addr: 0100
Module Map
MODULE NAME ADDR SIZE
1.MAIN .REL 0100 0009
1.CNTCH .REL 0109 001E
1.TEST .REL 0127 002F
The transfer address has been set to the IPLA and execution will begin
with the module "MAIN".
-12
FLEX Linking Loader
6. MISCELLANEOUS
6.1. Transfer Address
A transfer address is the location at which execution is to start when
the program is invoked. Use of the 'END' directive in the relocating
assembler can be used to indicate a transfer address.
Only one relocatable module to be included in a program should contain a
transfer address. If more than one module has a transfer address, the
linking loader will accept the first one encountered and ignore all
others.
-13
FLEX Linking Loader
7. ERROR MESSAGES
Absolute module table overflow
The number of absolute input modules cannot exceed 50. Combine
several of the modules into one and re-assemble.
Attempt to redefine entry point
Two entry points (global symbols) exist with the same name. Entry
point names must be distinct. One of the globals will have to be
renamed, its module re-assembled, and linked.
Can't go. Command line overflow
When the "g" option is specified, the linking loader builds a
multiple command line: the first command is the linking loader
invocation as supplied by the user, and the second is the
invocation of the executable output file of the linking loader.
Since a command line is limited to 128 characters, it is
conceivable that both commands may not fit. If the "go-time"
command cannot be shortened, it will be necessary to invoke the
executable output file separately after the linking process has
completed.
Error in load address
The address following the "A" option is not a valid hexadecimal
address. See the "A" option for complete specifications.
in unresolved.
An unresolved external has been detected by the loader. If the
output of the loader is to be a relocatable module, this condition
is probably expected and can be considered a warning. Use of the
"u" option will suppress this warning message. However, when
producing an executable program, this is an error.
- contains assembly errors.
An input file to the loader contained errors when assembled.
Correct the errors in the source code and re-assemble.
- illegal file specification
The file name is not a valid FLEX file specification.
- illegal input file.
The file name mentioned is not a relocatable module as built by the
relocating assembler or the loader.
invalid library specified.
The file name mentioned is not a valid library as built by the
library generator program. All libraries must be created using the
library generator.
-14
FLEX Linking Loader
- not found
The file specified could not be located.
FLEX ERROR #
A FLEX system error has been detected. Consult the FLEX manual for
definitions of the errors.
'Go' denied.
In order for the loader to execute the user's program, all of the
following conditions must hold: an output file be produced and must
be executable, the program must have a transfer address, and the
program must be error free.
'Go' pending. Warnings detected. Still go (y or n)?
Warnings were detected by the loader while preparing a program for
execution. The operator must answer with "Y" or "y" if these
warnings are to be ignored and execution initiated; any other
response will cause execution to be aborted.
Insufficient memory
There is insufficient user RAM to support the linking loader. The
minimum amount of RAM capable of comfortably supporting the linking
loader is 24K.
Linking error at $ relative to
When adding the address of an external to a field-being linked, the
carry bit was set. "Module name" is the offending input module,
and "address" is the offset of the link field from the base of the
module. This message is merely a warning to the user that an error
condition may have occurred. In some cases, this message would be
expected. Consider the following module:
NAME EXTTEST
EXT EXTRN
X 0000 8E FFFF START LDX #EXTRN-1
X 0003 C6 FF LDB #EXTRN+255
END
The loader would report the following if the address of EXTRN. was
non-zero:
Errors Detected.
Linking error at $0001 relative to EXTTEST
Linking error at $0004 relative to EXTTEST
This first message is informing us that the sum of the address of
EXTRN and -1 cannot be held in 2 bytes (the carry bit was set).
However, the address loaded into the X register when this
instruction is executed would be exactly as we would expect: one
less than the address of EXTRN. A similar situation would occur
when we force one-byte linking as in the second instruction of the
-15
FLEX Linking Loader
above module: the sum of the least significant byte of the address
of EXTRN (if non-zero) and 255 will not fit into one byte (the
carry bit was set).
Module name table overflow
All available space in the module name table has been exhausted.
Link a subset of the input modules to produce a larger relocatable
module.
not loaded. Memory conflict with loader
There is insufficient memory available to hold the entire module.
To correct this situation, break the module source code into
several smaller modules and assemble separately. This message can
also be generated when the "G" option is specified, and an absolute
module was to be loaded over the loader. In this situation, create
an executable program without using the "G" option and invoke it
directly from FLEX.
Symbol table overflow
No more room exists in the global symbol table to insert symbols.
The symbol table maximum capacity is 341 symbols. Symbols which
are not required to be global should be made internal in order to
free up more room in the table.
Too many Common Blocks.
The number of unique common modules cannot exceed 50.
Too many input modules.
The number of input relocatable, absolute, and common modules
exceeds 100. Link a subset of these modules and produce a larger
relocatable module. This single large module can then be linked
with the remaining ones.
Too many libraries specified.
More than five libraries were specified on the command line. See
the chapter LIBRARIES for further information.
Unknown option ignored -