Status

• elf tools 0.17.5, dated 2003/10/17.
• binutils beta12, dated 2002/03/21.

The last updates fix :

• a bug that appeared in very large object files and made the program crash horribly.
• a problem with psk output of specific lenths.

xtc will never work correctly with the linker since it's internal structure makes linking impossible in some cases.
Patches for the above exists but quickly reached "very dirty hack" status and will be omitted from the official xtc distributions.

With rtc >= 0.1.36 , linker operation seems now ok.

Features / Known bugs

• The linker does not detect situations where variables marked as extern are actually never instantiated. This may lead to memory corruption.
  

Download

Tutorial

Introduction

For APEmille there already did exist a completely different linker project. It did link code at the assembly level however, and thus is most suited for generating simulator (SF) code.

The Microcode Linker links shaked object files that are produced by an adapted shaker (such as psk or flint) and a subsequent converter.

Linking Steps

1. A TAO compiler creates an assembly source file.

2. The assembler/shaker creates an intermediate microcode object format

   (This step is most often merged with the next one)

3. A converter program brings the file into a suitable format to be use by the linker and the linker utilities.

4. Object files can, of course, be collected into libraries.

5. The linker combines object files and libraries to an executable.

6. If the executable produced in step (5) is not directly loadable by the OS, another tool can convert it back to the standard JEX format.

Required Software

The software versions of the relevant APEmille tools that are believed to function correctly with the ald linker are listed below. Don't even think of trying it while using older versions than listed!

The Linker Tools

ald

The linker proper. It's a straightforward port of the GNU ld linker (version 1.9.1) with only the few necessary changes to support the requirements of the APEmille microcode.

aar

The GNU ar program (renamed aar for APEmille) creates, modifies, and extracts from archives. An archive is a single file holding a collection of other files in a structure that makes it possible to retrieve the original individual files (called members of the archive).

Please refer to the UNIX man page of ar for usage information.

astrip

The GNU strip program (renamed astrip for APEmille) strips the symbol table from ELF files.
This mainly useful after linking to reduce the size of the executable file.

aobjdump

The GNU objdump program. Use it to examine .ao files.

jex2elf

A converter between REX and ELF files.
Usually called by the shaker.

elf2jex

A converter between ELF and JEX files.
Currently called manually before execution.

Programming Rules

The following rules apply to TAO programmers wishing to use the linker:

• The main program must be enclosed in
  begin main
  end main
• Compile always using the '-c' flag.
• External data must be declared as such using the same declaration as the data's home modules, e.g.:
  extern complex field[100]
• External subroutines need not be declared since rtc does it for all calls.
  Note: rtc requires strict type conformance of declaration and use of a subroutine, i.e. calling a subroutine with differently typed arguments than declared by the routine will result in a linker error.
• The order in which modules are linked is not important. The order does however affect the memory layout. So users who wish to re-use the memory contents of a previous run should carefully place all relevant data into the first module.
• The linker treats globally declared floating point data similar to FORTRAN common blocks, i.e. they may be declared multiple times but should have the same size everywhere.
  This "feature" was introduced to faciliate the transition to using the linker, otherwise the multiple inclusion of files that contain declarations would result in long error lists.

Sample Session

% rtc-try -c main.zzt 
This try version of rtc was generated on Fri May 25 19:31:42 MEST 2001
Using files from //zroot/bin/../rtc-try ...
... TAO compilation using: //zroot/bin/../rtc-try/rtclib
(//zroot/bin/../rtc-try/rtaocomp)
... including double.hzt 
... including localint.hzt 
OK
... cross-assembling: main.rasm -> main.jasm
% psk -e  main.jasm

[ psk]: Version 2.1 using AKAS directory: /kroot/lib/psklib
[kaso]: /tmp/10374_main-exp.jasm --> /tmp/10374_main.easm
[kaso]: WARNING: HALT with DISP not yet supported
[kaso]: Removed 2 / 2 Moves
[kaso]: Cancelled 2 Instructions, [kaso]: took 1.00 secs.
[shaker]: Shake-up limit is 256 cycles
[shaker]: Default max physical register is 0x1f (31)
[shaker]: took 1.26 u + 0.01 s = 1.27 CPU seconds
[shaker]: 4 memory pages used (0%), last PMA 0x331 (817) 
% rtc-try -c module.zzt 
This try version of rtc was generated on Fri May 25 19:31:42 MEST 2001
Using files from //zroot/bin/../rtc-try ...
... TAO compilation using: //zroot/bin/../rtc-try/rtclib
    (//zroot/bin/../rtc-try/rtaocomp)
... including double.hzt 
... including localint.hzt 
OK
... cross-assembling: module.rasm -> module.jasm
% psk -e module.jasm

[ psk]: Version 2.1 using AKAS directory: /kroot/lib/psklib
[kaso]: /tmp/10390_module-exp.jasm --> /tmp/10390_module.easm
[kaso]: took 1.00 secs.
[shaker]: Shake-up limit is 256 cycles
[shaker]: Default max physical register is 0x1f (31)
[shaker]: took 0.27 u + 0.01 s = 0.28 CPU seconds
[shaker]: 1 memory pages used (0%), last PMA 0xa7 (167) 
% ald -o myprog.x main.ao module.ao
% elf2jex myprog.x myprog.jex







% aar crv libxxx.a module.ao
a - module.ao
% ranlib libxxx.a
% ald -o myprog.x main.ao -L. -lxxx
% elf2jex myprog.x myprog.jex

Memory Layout

Object files contain several types of sections :

• Program memory (sections .tzpm and .jndm).
• Global (i.e. externally visible) Jmille data (section *COM*).
• Local (i.e. private) Jmille data (section .jndata).
• Global and local Tmille data (section .tzdata).
• Constant blocks that include also the slice information (sections .tconxx and .jconxx ).
• Memory allocation sections for the above constants (sections .tzbss and .jnbss).

The linker rearranges and merges the sections as shown below.
The program sections of each module are genrally padded up to the next page boundary (1 page = 0x100 cycles) due to the embedded page fault jumps that cannot be moved by the linker. A linked executable is therefore always larger than an equivalent single-source-file program.