home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ftp.uni-stuttgart.de/pub/systems/acorn/
/
Acorn.tar
/
Acorn
/
acornet
/
dev
/
drlink.spk
/
Drlink_doc
< prev
next >
Wrap
Text File
|
1995-07-30
|
49KB
|
1,101 lines
The 'Drlink' AOF Linker
~~~~~~~~~~~~~~~~~~~~~~~
Disclaimer
~~~~~~~~~~
The 'Drlink' linker is provided 'as is' and people using it do so
entirely at their own risk. No liability whatsoever will be
accepted for any loss or damage arising from the use of this
software.
Introduction
~~~~~~~~~~~~
Drlink is a linker that is intended to be a partial substitute for
the Acorn linker, 'link'. It is aimed at people with compilers
that generate object files in Acorn's AOF format but who do not
have a copy of 'link', for example, people who want to use the DDE
Pascal compiler or TLA or perhaps their own homebrew compilers.
Drlink accepts object files in Acorn's AOF format and libraries in
Acorn's ALF format and links them to produce an executable image
in either Acorn's AIF format or a plain binary image. It can also
be used to link relocatable modules or to create partially-linked
AOF files. Drlink is modelled very closely on the version of
'link' that comes with release 3 of Acorn's C compiler but it is
not really a complete replacement for it as it does not have the
same range of facilities. What is there, it is hoped, should be
adequate in most cases. Drlink is designed to link 'ordinary'
programs and cannot do some of the fancy things link can, such as
create image files that use overlays. Of course, some of these
features could be added at a later date but the current version of
Drlink, 0.28, does not support them. On the other hand, it does
contain some features found on later releases of 'link' such as
the ability to increase the size of the wimpslot if necessary when
running in a task window and support for extended command lines.
Other features include the ability to scan libraries more than
once when resolving symbols and, assuming the right compiler
options have been used when compiling programs, being able to
leave out unused functions from executable images. Hopefully
features like these will make the linker attractive to people who
use link as well.
Thanks...
~~~~~~~~~
I would like to thank the many people on Arcade who have tested
Drlink for me over the months and who made many helpful and useful
suggestions. Drlink would never have reached the state it has
today without their generous assistance.
Using Drlink
~~~~~~~~~~~~
Drlink is a command line-based program and has the same command
syntax as 'link'. It can be used in the same environments as
'link', for example, with amu. If it is renamed as 'link', then
it can be dynamically invoked from either the Acorn C or DDE
Pascal compilers as well. It accepts the same options as 'link',
although a number of them are unsupported and will be flagged as
errors. Drlink also supports extended command lines. (Further
information on this can be found in the section 'Extended Command
Line Support' below.)
The command syntax is:
drlink <list of files> <options>
where:
<list of files> is the list of object files and libraries to be
included in the linked program.
<options> is the options to be used when linking the
program.
Options and object file names can be freely intermixed. The linker
processes all the options before moving on to the link itself.
Filenames
Each filename in the list of object files should be fully
qualified, that is, Drlink makes no assumptions as to where the
object files are to be found. Wildcards are permitted, in which
case Drlink loads all the files that match the wildcard. If the
directory containing the object files is called 'o', then Drlink
will also accept 'back-to-front' filenames, for example, 'sieve.o'
instead of 'o.sieve'. If a path is used as part of a filename, for
example, 'C:', the way Drlink treats the filename depends on
whether it contains wildcards or not. If it does not, then every
directory on the path will be searched to find the file until
either the file is found or the end of the list is reached. On the
other hand, if the filename contains wildcards, only the first
directory listed on the path will be checked. (This is how link
behaves.) Examples:
o.sieve
o.dhry1 o.dhry2 c:o.stubs
o.dhry* c:o.ansilib
dhry*.o c:ansilib.o
o.* c:o.*
O.world scsi::Arc.$.programs.!Pascal.O.Plib C:O.stubs
Drlink ignores the case of object file and library names.
Options
As noted above, Drlink recognises the same options as 'link',
even if it does flag a number as unsupported, plus has a number of
its own. Options take the form of a '-' followed by the option
name. Some options are followed by an argument. One or more blanks
should be left between the option name and the argument. The case
of the option and any argument is ignored. Options that are
supported are:
-aif Create an AIF image file.
This is the standard format for programs running
under RISCOS where a small header is attached to
the start of the program containing various bits
and pieces of information. It is the default option
used for the image type when no type is explicitly
given unless the '-base' option is used when '-bin'
is the default value.
-aof Create a partially-linked AOF file.
The image file created takes the form of an AOF
file where as many references as possible between
the object files included in the link are resolved
and then the object files are merged together to
form another object file in AOF format that can be
used in a future link.
There are a couple of points to watch out for here:
a) To include debug information in the AOF file,
either '-debug' or '-keepdebug' must be used.
b) All local symbol names are lost, so they will
not appear in the low-level debug tables if
these are generated in the final image.
-base <address>
This option allows the initial load address of the
read-only part of the image file to be specified.
The read-only part normally contains code.
<address> is taken to be decimal by default but if
prefixed by '&' or '0x' it will be treated as a
hexadecimal value. It can be postfixed by 'k' or
'm' to indicate the address is in kilobytes or
megabytes. The case of the 'k', 'm', 'x' or any of
the hex digits 'a' to 'f' is ignored. The value of
<address> is rounded up to the next word boundary
if it is not already so aligned.
The initial load address can only be specified for
a binary image file.
Image files created when this option is used do not
have a filetype but have 'load' and 'excute'
addresses instead. The load address is set to
whatever was specified on '-base' and the 'execute'
address to the program's entry point address. The
files themselves contain plain binary images as
created by the option '-bin'. This behaviour is
different to that of 'link'.
-bin Create a plain binary image file.
A binary image file does not have the header that
AIF files have on them and consist of nothing but
the linked program. This has two consequences.
Firstly, and most importantly, zero-initialised
data areas will not be cleared to zeros when the
program starts running as the routine to do this is
part of the AIF header. Secondly, if debugging
tables are included in the executable image, there
is nothing to indicate where they are.
Note that when the option '-base' is used and the
image file type is not given, '-bin' is assumed to
be the image type.
-case Ignore the case of symbols when trying to resolve
symbol references. If this option is omitted, then
the case of the letters in symbol names is treated
as significant.
-debug Include debugging information in the image file. If
this option is omitted, any debugging tables
generated by the compiler that produced the AOF
file will be left out of the final image file. If
it is specified then any debugging tables found
will be included, along with some low-level tables
the linker itself creates. In the case where the
AOF files to be linked do not contain debugging
tables, only the linker's low-level tables will be
included.
There is a second debug option, '-keepdebug', that
can be used to selectively include debugging
tables. Only one of '-keepdebug' or '-debug' should
be used. If both options are used, '-debug' takes
precedence.
Note that if this option and '-bin' is used then
the debugging tables will still be included
although they will not really be of much use as
debuggers such as 'asd' would not be able to find
them. On the other hand, a routine in the program
might be able to locate them and for this reason
they are still included in the image file.
-edit <name>
Gives the name of a file from which 'link edit'
commands are to be taken. For more information,
refer to the section 'Link Edit Commands' below.
-help Print a summary of Drlink options.
-map Print a list of areas (read-only code, data,
debugging tables, etc) in the image file giving
their addresses, sizes and types and the name of
the original AOF files that contained the areas.
-module Create a relocatable module in RMF format.
-output <name>
Write the executable image file to file <name>. If
this option is omitted, the program is written to
the file '!Runimage' in the current directory.
-relocatable
Create a reloctable AIF image file.
-rmf Create a reloctable module in RMF format.
-verbose Print messages as the link progresses saying how
far it has got. Some extra warning messages are
also produced if the linker finds aspects of the
link that look a bit iffy, for example, it will
print warning messages about unresolved 'weak'
external references. Normally, the linker keeps
quiet about such things.
-via <name>
According to the documentation on 'link', this
option allows the list of files to be included in
the link to be specified in file <name>. In fact,
the file can also contain link options and this is
how the option '-via' has been implemented in
Drlink. When this option is encountered, input is
switched to the file <name> and the list of files
and options taken from that file until end-of-file
is reached whereupon input reverts back to the
command line. The only option that is not valid in
a '-via' file is '-via'. This option can be used
as many times as is necessary on the command line.
The format of the filenames and options in the file
<name> is exactly the same as when specified on the
command line, except they can be spread over as
many lines in the file as necessary. Any 'newline'
characters in the file are treated as if they were
blanks.
-workspace <size>
For a relocatable AIF image file, reserve <size>
bytes of memory after the image when relocating
it. <size> is rounded up to a whole number of
words. <size> is taken to be decimal by default
but can be prefixed by '&' or '0x' to give a
hexadecimal value. It can be postfixed by 'k' or
'm' to indicate the size is in kilobytes or
megabytes. The case of the 'k', 'm', 'x' or any of
the hex digits 'a' to 'f' is ignored.
All other 'link' options are recognised but are unsupported. They
are: dbug, entry, overlay and xref.
The linker has the following extra options of its own:
-acornmap If option '-symbols' is used to print a symbol
listing, then it will be created in a format
similar to that produced by 'link'.
-areamap <name>
This option causes the linker to write a map of the
areas in the executable image to file <name>. If
option '-nounused' is used as well, a list of areas
left out of the image file is produced as well. The
format of the list is exactly the same as that
produced by the '-map' option.
-data <address>
'-data' allows the address of the start of the
read/write portion of the image file to be
specified. <address> is assumed to be a decimal
value by default but prefixing it with '&' or '0x'
means it will be taken to be in hexadecimal. It can
be postfixed by 'k' or 'm' to indicate the address
is in kilobytes or megabytes. The case of 'k', 'm',
'x' or any hex digits is ignored. The value of
<address> will be rounded up to the next word
boundary.
This option can only be used when linking a binary
image file. Other image formats, for example, AIF,
make assumptions as to where the read/write part of
the image is to be found and therefore use of
'-data' is restricted to binary files only.
The linker built-in symbol 'Image$$RW$$Base' is set
to the address of the start of the read/write
portion of the file, so the addresss of the data
can be found in a program by including a reference
to this symbol.
Note that this option should only be used with the
greatest of care. It allows the address of the
start of the read/write portion of the image to be
given. The point of this is to allow data to be
placed at a specific address in memory. However, it
is also possible for executable code areas to go in
the read/write part of the image. If '-data' is
used, any such code will be treated as though it
will be at <address> at run time but due to the
format of the image file, when the program is run,
the code will not be placed at <address>. The same
is true for any pre-defined data. Therefore, if
this option is being used, the following points
should be observed:
1. Executable code should be placed in read-only
code areas only.
2. Constants should be placed in read-only data
areas only.
3. The initial values of any other items of data
will be undefined.
-debimage If this option is specified and the image file to
be written contains debugging tables, the filetype
of the image file is set to 'DebImage' instead of
'Absolute'. If this option is not used, the
filetype of the image file is always set to
'Absolute'.
-keepdebug <file list>
The purpose of this option is to allow debugging
information to be included selectively in the image
file. <file list> is a list of the object files and
library members where any compiler generated
debugging tables found are to be kept. Debugging
tables in any other files or members are ignored.
Any linker-generated low-level debugging tables
will only include entries for the files in <file
list>.
The format of <file list> is a string of names of
files and library members separated by commas with
no other intervening characters or a string of
names enclosed in double quotes separated by one or
more blanks. The names should exactly match the
names of the files or library members to which they
refer, although the case of the names is ignored.
Wildcarded names are not permitted, although the
case where a name in <file list> matches a file
name in the list of files to link that resulted
from expanding a wildcarded name is allowed.
Only one of the debugging options should be used at
a time. If both are found on the command line then
'-debug' takes precedence over '-keepdebug' and the
image file will contain all the debugging tables
the linker finds.
-leaveweak This instructs the linker to leave weak externals
unresolved if satisfying them would cause library
members to be loaded. This is the way the AOF
version 3 documentation says the linker should
behave, and is the opposite to the AOF 2 docs. By
default, Drlink will attempt to resolve weak
externals. This options makes it behave as per AOF 3.
-lib <library list>
<library list> is a list of libraries that Drlink
will search when attempting to resolve symbol
references. The list can take two forms. Either it
can supplied as a string of library names separated
by commas with no intervening blanks or any other
white space characters or the list can be enclosed
in double quotes with the names separated by one
or more blanks. Wildcarded library names are not
permitted.
This option should not be needed in the normal
course of events. Drlink can tell the difference
between AOF files and libraries without having to
be told which is which but this is not the purpose
of the option. Its purpose is to reduce the
amount of memory used by the linker. The way the
Drlink works is to read *all* the files given on
the command line into memory including any
libraries. Whilst this speeds up pulling members
out of the libraries, it can be quite expensive in
terms of memory. Libraries specified after '-lib'
will not be brought into memory and members will
be loaded from them as required.
Note that any 'old style' libraries listed after
'-lib' will be loaded immediately, that is, they
will not be added to the list of libraries to be
searched later.
-nounused This option is used to control whether unreferenced
areas in the image file will be left out. By
default, all areas are left in but if '-nounused'
is specified, the linker checks each area in the
executable image and leaves out any that it finds
are not referenced by any other areas.
The purpose of this option is basically to strip
out any unused functions in a program. To achieve
this, it is necessary first to compile the program
with the '-zo' C (and DDE Pascal) compiler option.
This has the effect of spliting each function up
into its own self-contained 'area' in the object
code file. If '-nounused' is specified, the linker
examines all the areas and discards any that it
finds are not referenced from any other areas. In
fact, if the linker finds that, as a result of
throwing away an area, others that it referenced
now become unused, it will discard those other
areas as well. Unfortunately, it will not detect
cases where there are loops, that it, if area 'a'
calls only area 'b' and area 'b' calls only area
'a', it will not detect that it is safe to throw
away both areas. On the other hand, it can handle
the case where an otherwise unused area calls only
itself.
Note that if the '-verbose' option is used, Drlink
will print a list of areas that have been left out
of the image file, along with the name of the first
symbol in the area if it can find one. This should
hopefully be the name of the function contained in
that area in an AOF file produced by the C
compiler.
This option is not present in the C release 3
linker but it might be available in other AOF
linkers.
WARNING: It should be remembered that the '-zo' C
compiler option is undocumented. In versions 3 and
4 of the compiler, it contains a serious bug that
affects the addresses of character strings in the
executable image. Under certain conditions, these
addresses are *wrong*. There is a workaround for
this, however. If '-zo' is used then '-fw' should
be used as well, that is, you should say, for
example: 'cc -zo -fw -c c.world'.
-pagealign Pagealign instructs the linker to align the end of
the last read-only area in the image file on a page
boundary. The pagesize of the machine on which the
linker is being run is used in the calculations.
-rescan This tells the linker to scan libraries more than
once if necessary when searching for symbols.
'link' scans them only once so it is important to
specify libraries in the correct order. Drlink also
works like this unless '-rescan' is used, in which
case it will continue searching the libraries in
the order in which they were specified on the
command line until all symbols have been found or
all libraries have been checked for a particular
symbol.
This option is not present in the C release 3
linker but it might be available in other AOF
linkers.
-symbols <file>
Create a file listing all the relocatable symbols
in the image file. They are listed in address
order.
If option '-acornmap' is used, the symbol listing
will be produced in a format similar to that of
'link' instead of using Drlink's format.
-throwback If this option is used and it is possible to use
'throwback' then all warning, error and fatal error
messages will be displayed in a 'throwback' window.
Note that only errors found after the option has
been encountered in the command line will be sent
to the 'throwback' window. Any found before that
point as well as any informational messages will
still be displayed at the command line in the
normal way. To display all errors in the
'throwback' window, this option should be the first
one supplied on the command line.
Note that in order to use this facility, it is
necessary to have the 'DDEUtils' module loaded and
an editor that supports 'throwback', for example,
Dominic Symes' editor, !Zap.
Note that the 'throwback' file name is set to that
of the image file to be created, and the effects of
clicking on one of the error messages shown in the
window is undefined. 'Throwback' is meant to be
used for source files, not object code!
Note that most options can be abbreviated to one or two letters.
The minimum abbreviation for each option is:
-acornmap -aco
-aif -ai
-aof -ao
-areamap -area
-base -b
-bin -bi
-case -c
-data -da
-debimage -debi
-debug -d
-edit -e
-help -h
-keepdebug -keep
-leaveweak -leave
-lib -lib
-map -map
-module -m
-nounused -no
-output -o
-pagealign -pag
-relocatable -r
-rescan -res
-rmf -rm
-symbols -s
-throwback -th
-verbose -v
-via -via
-workspace -w
Examples:
drlink o.sieve c:o.stubs
drlink sieve.o c:stubs.o
drlink o.dhry1 o.dhry2 c:o.ansilib
drlink o.dhry1 o.dhry2 c:o.stubs -o dhry
drlink o.* -no -o PDC
drlink o.life c:o.risc_oslib c:o.stubs -map -v
drlink o.life -lib c:o.risc_oslib,c:o.ansilib
drlink o.life -lib "c:o.risc_oslib c:o.ansilib"
drlink -throw o.balls64 p:o.plib c:o.risc_oslib P:O.Stubs
drlink o.balls64 -via pasclibs -map -v
The default options are to generate an AIF image file, to treat
the case of symbols names as significant, not to include debugging
information, to include all areas in the image file, not to
produce an area map or symbol listing and to keep quiet about what
the linker is doing.
In normal use, it should not really be necessary to use any of the
linker options and running Drlink should just be a case of
typing the command and the list of files and libraries to include
in the linked image file, perhaps using the '-d' option to include
debugging tables or '-o' to change the name of the linked image
file.
Return Codes
~~~~~~~~~~~~
If a link works, Drlink gives a return code of zero. If it fails,
it posts a return code of twelve. A fatal error produces a return
code of sixteen.
Extended Command Line Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Drlink can make use of the extended command line facility that
is provided by the 'DDEUtils' module. This allows the command line
passed to Drlink to be of any length and not restricted to the
normal limit of 255 characters. If the linker finds there is an
extended command line available, it uses that in preference to the
standard command line, which it completely ignores.
In order to use this facility, it is necessary to have the module
'DDEUtils' loaded and to use software that can set up extended
command lines, for example, the version of 'amu' that comes with
release 4 of the C compiler.
Link Edit Commands
~~~~~~~~~~~~~~~~~~
This is a feature that allows symbols in the AOF files to be
edited in various ways. Four operations are possible:
1. Rename a symbol in an AOF file.
2. Change a symbol reference in an AOF file.
3. Hide a symbol in an AOF file by making it 'local'.
4. Reveal a symbol in an AOF file by making it 'global'.
The purpose of these commands is to resolve problems where
different AOF files define symbols with the same name or to enable
what would be unresolved symbol references to be replaced with
references to defined symbols. Note that all that the commands do
is act as a filter on the AOF files before they are passed to the
main link routines and that if, for example, a symbol reference is
changed, then there are no checks to make sure that the new symbol
refers to the same sort of 'thing' as the old.
The commands are read from the file specified on the option
'-edit'. Note that, unlike 'link', multiple 'link edit' files
can be supplied. The general format of the commands is:
<command> <filename> ( <one or two symbol names> )
<command> is one of the four commands described below and <filename>
is the name of the AOF file or library member that will be
affected by the command. Depending on the command, either one or
two symbol names follows in brackets. The commands are free-form
and can be spread over as many lines as necessary in the file.
Several commands can be stacked on one line and there is no limit
on the number of commands in a file. At least one space should be
left between the command and the filename but they are optional
after that. The case of the link edit commands themselves is
ignored as is that of any file names, but the case of symbol names
is taken as significant, unless the option '-case' is specified on
the command line as well in which case it is ignored. It is
possible for several commands to refer to the same symbol, so
that, for example, the name of a symbol could be changed in one
file and references to it in another file could also be changed to
that name as well. The order of the commands in the file is, in
general, unimportant, but also refer to the note below. If, on the
other hand, a symbol is to be renamed and its scope changed at the
same time, then both edit commands should refer to the symbol by
the symbol's old name.
Rename a Symbol
The format of the command is:
rename <filename> ( <old name> , <new name> )
The effect of the command is to rename the symbol <old name>
defined in file <filename> as <new name>. All references to the
symbol should use <newname>.
Change a Symbol Reference
The format of this command is:
change <filename> ( <old name> , <new name> )
It changes external references to symbol <old name> in file
<filename> to <new name>.
Hide a Symbol
This command's format is:
hide <filename> ( <symbol name> )
If the symbol <symbol name> in file <filename> is marked as being
visible to any file that references it, its scope is change to
'local' so that it can only be referenced in the file in which it
was declared.
Reveal a Symbol
This command has the format:
reveal <filename> ( <symbol name> )
If the symbol <symbol name> in file <filename> is marked as a
'local' symbol, that is, can only be referenced in the file file
in which it was declared, its scope is changed to 'global' so that
any file can reference it.
Examples:
hide o.sieve(main)
rename o.miscprocs(isalnum,isalfanum)
change o.lexicals(isalnum,isalfanum)
change o.preproc(isalnum,isalfanum)
There are a couple of points to be aware of using the link edit
commands.
Firstly, the commands are not executed in the order in which they
are specified. All the commands for one file are performed
together. They are also carried out in the order in which the
files are specified on the command line. As the order in which
library members will be read is not defined, the order in which
link edit commands for these are executed is undefined as well.
There are times when the commands will appear not to work In a 'C'
or DDE Pascal program, if a symbol reference, for example, a
function call, is changed, references to that symbol within the
AOF file will not be altered as the compiler will have resolved
the references at compile time.
A Brief Description of Drlink
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Drlink starts by reading the list of object files and libraries
given on the command line into memory, except for any libraries
given on the option '-lib'. Any 'link edit' commands are acted
upon as the files are read. After this, Drlink attempts to resolve
symbol references in each object file using, first, the symbols
defined as being local to that file and then symbols defined as
available to any file. If there are still any unresolved symbols,
it then goes through each library trying to find them. The
libraries are searched in the order they are specified on the
command line, from left to right. This includes libraries
specified on the '-lib' option. Each library is scanned only once,
unless the option '-rescan' is used. This means that any library
members read can only refer to symbols that are already known or
that can be found in that library or one that has yet to be
searched. The order that libraries are specified on the command
line is therefore very important. If, on the other hand, '-rescan'
is specified, Drlink will keep searching the libraries until all
the symbols have been found or until it determines that a symbol
cannot be found in any library.
Assuming that all symbol references have been found, Drlink moves
on to resolving addresses. Before it does that, however, if the
'-nounused' option was specified, it attempts to determine the
areas in the program that are not referenced from any other areas
and removes any it finds from the program. Next, it determines the
proper addresses of all the symbols and areas in the program and
then goes through the program relocating and resolving addresses.
If the '-debug' option is used, the low level debugging table is
created at this point. The final step is to write the completed
image file to disk.
Drlink has the ability to increase the amount of memory it is
using if it is running in a task window or using the 'F12' CLI. It
will acquire as much extra memory as it needs and return it once
the link has completed. Drlink can be run in a wimpslot of only
96K bytes.
Pre-defined Symbols
~~~~~~~~~~~~~~~~~~~
There are a number of pre-defined symbols that can be referenced
in object files. These are defined by the linker itself. The ones
that Drlink supports are:
Image$$RO$$Base The start address of the 'read-only' part of
executable image when loaded into memory. This
contains program code and constants.
Image$$RO$$Limit This is the address of the byte after the last
byte of the 'read-only' part of a program when
loaded into memory.
Image$$RW$$Base This gives the address of the first byte of the
'read/write' portion of a program when loaded
into memory. This contains program code and
data.
Image$$RW$$Limit This defines the address of the byte after the
last byte of the 'read/write' part of the
program. The includes any zero-initialised data
areas.
Image$$ZI$$Base This symbol defines the start address of the
'zero-initialised' part of the program when
loaded into memory. This is simply an area of
memory that is used by the program when it is
run to hold data. It is not included in the
image file on disk to prevent the image file
becoming bloated with huge tracts of
uninitialised data (except the Acorn C compiler
does not make use of them and so the image
file can become bloated with huge tracts of
uninitialised data). If an AIF file is being
produced (the standard Acorn executable image)
then the zero-initialised data area is cleared
to zeros when the program is run. This is not
case if any other executable file formats are
used, for example, '-bin'.
Image$$ZI$$Limit This marks the address of the byte following
the last byte of the 'zero-initialised' data
part.
It should be noted that, with Drlink, the two
symbols 'Image$$RW$$Limit' and 'Image$$ZILimit'
are set to the same value.
The Acorn documentation says that the end of one part of the
executable image should not be assumed to coincide with the start
of the next, for example, it should not be assumed that the
read/write part of the image starts the byte after the read-only
part.
The six 'Image$$' symbols are defined in the 'link' documentation
but there are a large number of other undocumented symbols, some
of which are used by the libraries supplied with the C compiler
(the C release 3 libraries, at least). Drlink implements a
number of these but not the whole set, nor are the ones that are
present guarenteed to remain there.
'Area' Symbols
Roughly speaking, the part of the AOF file that contains the
actual code, data and debugging tables compiled from the original
source file is broken down into a number of named 'areas', for
example, the C compiler generates an area called 'C$$Code' for
program code and one called 'C$$Data' for any data. These will be
present in each AOF file included in the link and what Drlink
(and 'link') does is to group all the areas with the same name
together. What is not documented, though, is that each uniquely
named area encountered by the linker results in creation of three
symbols that can be can be (and are) referenced by any object
file. These are the area name itself and a 'base' and 'limit' pair
which point at the start address of the first area of that name
when the program is loaded and the address of the byte after the
last occurrence of that area, for example, the area 'C$$Code'
would generate the symbols 'C$$Code', 'C$$Code$$Base' and
'C$$Code$$Limit'. The area 'C$$Debug' adds the symbols 'C$$Debug',
'C$$Debug$$Base' and 'C$$Debug$$Limit' to the linker's symbol
table.
What was said in the preceding paragraph also applies to 'common'
blocks. These are areas just like any other, but they are handled
slightly differently in that all common block areas with the same
name are overlaid on one another with the size of the common block
being that of the largest instance of the common block. Just as
with other areas, three symbols are created for each common block
that can be used in programs: the common block name and a 'base'
and 'limit' pair based on that name, for example, a common block
called 'acorn' would add the symbols 'acorn', 'acorn$$Base' and
'acorn$$Limit' to the linker's tables.
If the '-zo' C compiler option is used, each function in the
object code has its own uniquely-name area and this results in an
explosion in the number of area symbols generated. Normally this
would not be a problem except for the extra memory required to
hold these symbols, but it results in the low-level debugging
table created by the linker becoming flooded with what is, in the
author's opinion, totally useless symbol information. Drlink's
solution to this problem is not to include any symbols generated
for areas apart from those for common blocks in the low-level
debugging table.
There are other symbols that 'link' defines internally but these
have not been seen in any AOF files yet and so they have not be
included in Drlink.
Differences Between Drlink and Link
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Drlink is based on the version of 'link' that comes with
release 3 of the C compiler but there are a number of features of
'link' that are missing or that have been changed slightly. The
idea is that Drlink will be used to link 'ordinary' programs and
not any of the more exotic types that the Acorn linker can handle,
for example, programs that use overlays.
First, the missing features:
1) Drlink does not support overlays (the '-overlay' option).
2) The entry address of the program cannot be specified (the
option '-entry').
3) The old debug option '-dbug' is not supported.
4) The option to print a list of cross references between areas
has not be included (option '-xref').
5) It does not support unnamed common blocks.
6) The 'link' documentation contains vague references to Un*x
'Aout' format files. Drlink does not handle these.
The known differences are:
1) The low level debugging tables do not have as many entries in
them as the ones generated by 'link'. 'link' includes entries
for symbols for every single area in the executable program
but Drlink leaves out all of these apart from the ones for
'common' blocks.
2) There are a number of undocumented built-in linker symbols
available in 'link' such as '_esdata' that Drlink does not
include.
3) The default program name created by the linker is '!Runimage'
and not 'aif'.
4) If the '-bin' option is used to create a binary file and the
entry point is not the first instruction in the program,
Drlink adds a branch to that address at the start of the
program.
5) The link edit commands are different to link's.
6) The partially-linked AOF files produced by Drlink are not the
same as those produced by link. They do not contain the zero-
length area 'Aout$$Common'. The relocations in the AOF file
are a mixture of type-1 and type-2 rather than being all
type-2.
7) '-base' behaves differently. With link, the filetype of a file
where '-base' is used is 'absolute'. Drlink makes such files
untyped and gives them load and execution addresses.
8) Strong symbol definitions are more fully supported.
The extensions to the Acorn release 3 link are:
1) If running under a task window or in the 'F12' CLI, Drlink can
extend its wimpslot.
2) It can removed unreferenced areas from the executable program.
3) Drlink supports extended command lines.
4) It can scan libraries more than once.
5) Debugging tables can be selectively included in the image
file.
6) Warning, error and fatal error messages can be displayed in a
'throwback' window.
7) The starting address of the read/write part of the image file
can be defined by means of a linker option.
8) A map of areas contained in the executable image file can be
written to a file.
9) It can produce a listing of symbols in the image file.
10) It can align the end of the read-only portion of the image fle
on a page boundary.
11) It partially supports AOF version 3 (enough to link C and C++
programs) and generates AIF version 3 headers on image files.
In all other respects, Drlink should behave in exactly the same
way as 'link', hopefully apart from some known bugs in 'link'.
There are probably other subtle differences in the way the linkers
behave but these are not known.
Change Record
~~~~~~~~~~~~~
Drlink 0.20 - First release version.
Drlink 0.21
- Added support for type-2 relocations.
- Fixed problem with paths with multiple directories in
filenames.
- Speeded up linker a bit.
Drlink 0.22
- Fixed bug where symbolic debug tables were left out of the
image file if '-nounused' was used.
- Changed way linker orders areas to more closely match that of
'link'.
- Added option '-keepdebug' to selectively include debugging
information from object files in image file.
- Allowed filenames supplied for options '-lib' and '-keepdebug'
to be enclosed in double quotes. This will, in fact, work on
any option.
Drlink 0.23
- Added 'link edit' commands (the '-edit' option).
- Added code to allow 'back-to-front' filenames.
- Now sets a return code of 12 if a link fails.
- Fixed bug in '-keepdebug' code where a buffer was overflowing
and overwriting anything that followed it, e.g. amu.
Drlink 0.24
- Made 'verbose' mode list the names of the external references
being satisfied and the files containing those references when
loading library members.
- Linker now prints a warning message about and lists files
specified on '-keepdebug' that were not loaded.
- A problem with extended command lines containing rubbish at the
end of the line has been fixed.
Drlink 0.25
- Fixed bug where the offset of the program entry point within
the entry point's area was being set to zero.
- Fixed bug in '-nounused' code where references to areas in
type-2 relocations were not being handled correctly.
- Fixed bug to do with filenames that include a path variable
that only showed up with RISCOS 2.
- Added the option to create partially-linked AOF files (option
'-aof').
- Added 'throwback' support (option '-throwback'). Warning, error
and fatal error messages can be displayed in a 'throwback'
window.
- Added warning to documentation concerning the use of the C
compiler option '-zo'.
Drlink 0.26
- Improved linker's performance in large links.
- Improved memory management.
- Added options '-base' and '-data' to allow the start addresses
of code and data part of the image file to be specified.
- Added option '-areamap' to allow map of areas in image file to
be written to a file.
- Added code to circumvent problem with the DDEUtils command
'*prefix' where the linker cannot find files where a path is
included as part of the filename, for example, 'C:O.Stubs',
after '*prefix' has been used.
Drlink 0.26a - Bug fix version
- Fixed bug introduced in 0.26 where -aof code stopped working.
- Programmed around problen affecting files from Objasm that
contain debug tables where the tables contain an invalid 'AL'
attribute.
- RISCOS 2 filenames with paths finally sorted out I hope!
- Recompiled with the latest and greatest version of the
compiler.
Drlink 0.27
- Fixed bug where unresolved references to weak external symbols
were being included in the list of relocations at the end of
relocatable modules.
- Fixed bug in '-nounused' which could cause addressing
exceptions if an AOF file contained type-2 relocations.
- Fixed bug where type-2 relocations in an object file that is
used as part of a partially-linked AOF file were sometimes
being relocated incorrectly.
- Added option '-acornmap' to allow printing of symbol listing in
more-or-less the same format as that used by 'link'.
- Added option '-pagealign' to allow end of read-only part of
image to be aligned on a page boundary (useful for DDT).
- Changed symbol listing so that the addresses of symbols in
relocatable modules are expressed as an offset from the start
of the module instead of an address.
- Corrected handling of common blocks.
- Added code to allow code and data areas to have the 'common
definition' area attribute.
- Changed handling of zero length areas. Previously Drlink
ignored these completely.
- The linker will now produce a list of unresolved weak external
references if option '-verbose' is used instead of just
mentioning the fact.
- Corrected low level debug table and symbol listing code so that
they no longer include symbols from areas omitted from the image
file.
- Added support for 'strong' symbol definitions.
- Added some AOF V3 support.
Drlink 0.28
- Added option '-leaveweak' to stop linker resolving weak external
references from libraries (so that it behaves as per AOF 3 docs).
- Changed headers on image file to AIF v3 headers.
- Added option -C++ to instruct linker to carry out C++-specific
operations concerned with constructors and destructors. The
linker does not yet expand C++ mangled names into their full
versions.
- Added support for 'old style' libraries so that FORTRAN 77
programs can be linked.
- Fixed bug where relocation info for type-2 relocations was
missed out in relocatable AIF files and relocatable modules.
- Improved memory management when linker is running out of memory.
Future Developments
~~~~~~~~~~~~~~~~~~~
At the moment, the items on my 'wish list' for Drlink are, in no
particular order:
1) Add full support for AOF V3.
2) Improve the C++ support by printing de-mangled C++ function
and variable names.
3) Make it run faster.
4) Improve the memory management.
Any other suggestions people have will be gratefully received.
If anyone has any suggestions or comments on Drlink, I can be
contacted on the Arcade Bulletin Board, user #418 'Davedan'.
Telephone numbers for Arcade are 0181-654-2212 and 0181-655-4412.
Alternative, I can be reached at:
Davedan@arcade.demon.co.uk
Copyright
~~~~~~~~~
The software and the documentation that goes with it is
Copyright ⌐ David Daniels 1993, 1994, 1995. All Rights Reserved.
Permission is hereby given for you to copy this program and freely
distribute it, subject to the following conditions:
* No charge is made for the program (except nominal media costs).
* No alterations are made to any of the files within this archive file.
* All of the files within this archive are supplied, including this one.
* No part of this program is included in a commercial product.
