home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
AMIGA PD 1
/
AMIGA-PD-1.iso
/
Programme_zum_Heft
/
Programmieren
/
Kurztests
/
DiceC
/
doc
/
dlink.doc
< prev
next >
Wrap
Text File
|
1994-02-01
|
11KB
|
273 lines
dlink/dlink dlink/dlink
DLINK.DOC
DLINK <options> <files> <libraries>
Options may occur anywhere on the command lines. Any file ending in
.o[bj] is assumed to be an object file. Any file ending in .l[ib] is
assumed to be a library. Any file name beginning with @ specifies a
text file containing a further list of files.
File ordering is maintained. Section ordering is maintained. All
sections of the same name are coagulated together with ordering
maintained. EXCEPTION: inter-section ordering is not maintained
within a library since library modules are random included. However,
ordering is maintained *between* libraries.
All object files specified are included in the final executable. All
libraries specified are searched at the point they are specified (that is,
specifying an object file that references a symbol defined in a library
specified BEFORE the object file will cause an undefined symbol error).
Normally an object file is specified after a library to terminate an
autoinit or autoexit section.
You do not have to order object files within a library, DLink will
automatically make as many passes as required to handle all internal
library references. However, ordering object files will make DLink go
faster.
Symbols defined in object files overide symbols defined in libraries.
Symbols defined in libraries specified before later libraries overide
symbols defined in later libraries. Symbols defined in a library and
also defined in a later specified object module causes an error.
CREATING A LIBRARY
DLink libraries are standard Amiga libraries... simply join one or more
object modules together and rename the result with a .lib extension.
LINKER SYMBOLS AND A4 RELATIVE ADDRESSING
DLink generates the following special symbols to aid in program
startup:
__ABSOLUTE_BAS base of data in volatile space. This symbol is NOT
defined for normal residentable programs since the
base address is not known (must be allocated run-time)
__DATA_BAS base of data in non-volatile space. This symbol points
to a read-only copy of the initialized data for a
program. For Non-residentable programs this is the
same as __ABSOLUTE_BAS.
For residentable programs this points to a read-only
copy of the initialized data that the program can
duplicate on startup.
For programs linked with an absolute base address for
data this points to the end of the CODE section. The
ROMABLE program always generates a ROM copy of the
initialized data just after the CODE section (which
startup code must copy into RAM)
__DATA_LEN Length of data space is LONGWORDS. I.E. __DATA_LEN * 4
yields the number of bytes of initialized data. This
is used by startup code to copy read-only initialized
data to volatile space (residentable and data-absolute
programs)
__BSS_LEN Length of bss space in LONGWORDS. I.E. __BSS_LEN * 4
yields the number of bytes of uninitialized (BSS) data.
This is used in combination with __DATA_LEN to allocate
the DATA+BSS space for residentable programs, and clear
the BSS space for non-residentable and absolute-
data-base programs.
The BSS space occurs after the DATA space unless the
-frag option is used.
__RESIDENT This symbol is set to 0 if the -r option was used and
1 if the -r option was not used. If set to 1 (-r
option), then NO BSS SPACE IS PREALLOCATED WHEN THE
PROGRAM IS RUN. The startup code must allocate DATA+BSS
space, copy read-only initialized data over to this
space, and clear out the BSS portion before it the
program can run.
Programs linked with the -mw or -ma options obviously
do not 'allocate' their data space since it is
predefined. Most Amiga programmers will never use
the -mw or -ma options, by the way.
SMALL DATA MODEL
The small data model uses A4 relative addressing. The linker sets up
all relative offsets such that A4 must be initialized by startup code
the BaseOfInitializedData + 32766 for A4-relative references to access
the appropriate address.
RESIDENT
If the -r options is given then NO BSS SPACE is allocated after the
data space... the startup code MUST allocate a data+bss space as shown
above. DLink will give error messages for any absolute data references
that occur (except the __DATA_BAS symbol which must be used to copy the
static data to the newly allocated data+bss memory on program startup).
DLink will give an error message if any data-data reloco32s exist when
you specify the -r option as such relocations would be incorrect when
copied to the newly allocated data+bss space. DC1 understands this and
will produce autoinit code to handle any such static data relocations
that occur in your C code when the -r option is given to compile a C
program.
However, DLink does allow data-data relocations to occur if an absolute
data base is specified along with the -r option. This is used only
when making ROMABLE code.
PC-RELATIVE
Because the linker will insert a jump table for PC-RELATIVE references
to different hunks (after coagulation) or where the range is larger
than +/-32K, data should not be placed into a code segment and be
referenced via an external label(pc) unless you are positive the
reference is within +/-32K. This can only happen when referencing
between like-named code hunks. NOTE that the jump table is tagged
onto the end of the section the jump(s) occur in and thus you do
not want to have any autoinit/autoexit code that might possibly
generate a jump table (since the whole idea with autoinit is that
the code falls through to other autoinit code until the terminating
section in x.o's RTS).
Currently dlink cannot handle inter-module PC-RELATIVE references
beyond +/-32K (i.e. when one object file has more than 32K of code).
An error will occur.
Note that if -frag is used you cannot make PC-RELATIVE calls
between sections of differing names ever, or make a program resident.
The -frag option is almost never used on untested.
OVERLAYS (NOT SUPPORTED)
Overlays are not supported as yet.
OPTIONS
Options:
-o execname name of executable
-s Include symbolic information. NOTE, if -r is used
symbolic info for the data sections will point to
the statically init'd stuff, NOT The actual data
space (in BSS) referenced by the code. This is a bug.
-frag Fragment output file (default is to coagulate all
hunks of the same type regardless of name). If
frag is specified then only hunks of the same type
AND name are coagulated.
see fragmentation note at bottom
-r[es] Resident link.
-pi Position independant non-residentable (i.e. only
one copy of the data but also no relocation hunks)
-pr residentable position independant
-P<postfix> specify library name postfix. If DLink cannot find
the library as specified it will append the postfix
and try again. Used by DCC to specify the memory
model.
-mw addr specify absolute data base
-ma addr specify absolute data base
Both options do exactly the same thing and are in
duplicate to conform to DCC's options.
-mw/-ma specify the base of data as a decimal,
0octal, or 0xHEX address. You must use the -r
option in conjunction with these options.
DLink will resolve all Absolute-Word addresses
but not all Absolute-Long addresses. This is left
up to the ROMABLE program which generates a raw
binary image of the program that can then be
transfered to an EPROM.
DO NOT USE WHEN GENERATING AMIGA EXECUTABLES
-d[#] debug mode (spews lots of debugging junk out)
-E file specify stderr file, any errors are appended to the file
instead of to stdout. Useful for batch compiles
-chip chip-only - forces all hunks into CHIP memory
-L0 remove default library search path, including all
explicitly specified (-L dir) directories up to
this point.
-L dir add the specified directory to the library search
path. If the object module or library can not be
found in the current directory, directories
specified with -L are searched. -L directories are
searched before the default library directory
(DLIB:), assuming it was not removed with -L0 .
Note that the directory path specified by -L is used to
search for libraries AND object modules.
A trailing '/' is optional
-P<postfix> This allows you to specify -lc -Ps and DLink will
automatically look for cs.lib ... you can specify a
postfix that occurs before the '.lib' in the
library name here. If DLink cannot find the
library as it is named by default it will try
it with the postfix.
DCC uses this to supply the memory model to DLINK
also allowing the user to say '-lm' in DCC and have
it find MS.LIB if you are using the small-data
model.
SPECIAL NOTE ON FRAGMENTATION
When -frag is specified, the linker will not create a special
combined data+bss hunk (so data and bss can both be referenced with
one base variable).
However, when -frag is NOT specified, the linker will stil not
necessarily combine ALL data hunks into one big hunk and ALL bss
hunks into one big hunk. Any data or bss hunk with special upper
bits set (e.g. to force it into chip) is not combined into these
special hunks, and any data or bss hunk whos NAME begins with
'far' (upper or lower case) will also not be considered.
EXAMPLE
This is what DCC gives the linker to link the program 'foo.c' :
dlink dlib:c.o @tmp dlib:x.o -o ram:foo
--- tmp ---
foo.o
dlib:c.lib dlib:amiga.lib dlib:auto.lib
-----------
Basically it tells dlink to link the startup code, c.o, then the
program object module(s) (foo.o), then c.lib, amiga.lib, and auto.lib,
then finally x.o.
DCC handles all this for you
auto.lib contains autoinit code for certain selected libraries,
including the dos.library. Autoinit code is brought in whenever a
given library base symbol has been referenced BUT NOT DEFINED. auto.lib
defines the symbol and generates autoinit code to open the library and
autoexit code to close the library. To maintain portability you
probably do not want to use this automatic library-openning feature
yourself, it is really meant to support certain actions of the DICE
library (such as floating point support).
x.o terminates the autoinit and autoexit sections with an RTS. The
autoinit and autoexit sections are called from the startup code c.o .