Amiga Elysian Archive/AmigaElysianArchive.iso/prog/c/dice206.lha/doc/dlink.doc

Text File | 1990-12-13 | 9KB | 219 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.

    -f[rag]        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.

    -r[es]        Resident link.

    -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

                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 .