ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / drlink_1 / Drlink_doc < prev

Wrap

Text File | 1998-03-08 | 52KB | 1,177 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.34, 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. Note that '-quiet' takes precedence over '-verbose'. If both options are specified, '-verbose' is ignored. -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'. -gcc This option is used in conjunction with '-nounused' to tell the linker to ignore special areas created by GCC when weeding out areas that are not referenced in the image file. It has no other effect. The default is to omit all unreferenced areas. -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. -quiet This instructs the linker not to print the 'Drlink AOF Linker ...' message when it starts up. Nothing will be printed except for error messages. This option overrides '-verbose' if both are specified. -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. -revmap This option is used in conjunction with '-symbols' and instructs the linker to list the symbols with one symbol per line in the order <address> <name>. -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, that is, one symbol per line in the order <name> <address>. If option '-revmap' is used then the symbol listing is produced with one symbol per line in <address> <name> order. -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 -gcc -gcc -help -h -keepdebug -keep -leaveweak -leave -lib -lib -map -map -module -m -nounused -no -output -o -pagealign -pag -quiet -qui -relocatable -r -rescan -res -revmap -rev -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. Drlink 0.29 - Added symbols 'Image$$CodeBase', 'Image$$CodeLimit', 'Image$$DataBase' and 'Image$$DataLimit' required by FORTRAN 77 programs. These will only be included if 'old style' libraries are read. Drlink 0.30 - Made code StrongARM compatible. - Added support for 'based' areas. - Added support for areas not aligned on a word boundary. - Added option '-quiet' which stops linker from printing the 'Drlink AOF Linker' message. - Added support for the relocation of instruction sequences. - Fixed bug affecting symbols which had the 'common reference' attribute set. - Fixed two bugs in partially-linked AOF file support which stopped partially-linked files working with C release 5. - Fixed bug causing addressing exception when option '-symbol' was used when creating a partially-linked AOF file. - Fixed bug in C++ code where areas containing constructors and destructors could be deleted if option '-nounused' was used. - Added code to handle 'strong symbol' case that was missed out when strong symbol support was added. Drlink 0.31 - Fixed bug in library search code. - Added option '-revmap'. Drlink 0.32 - Fixed problem where very long symbol names (300 characters!) caused the linker to fail in various places. Drlink 0.33 - Fixed problem in code that produces area maps where area names longer than about 200 characters were causing the linker to die. - Added option '-gcc' to stop linker removing GCC-specific areas from the image file when '-nounused' is used. - Increased the maximum length filename that the linker will handle to 500 characters. Drlink 0.34 - Linker can now be compiled to run under RiscBSD and Linux (but it still links only AOF files). 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, 1996, 1997, 1998. 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.