gnu/usr.bin/ld/PORTING

   1 $FreeBSD: src/gnu/usr.bin/ld/PORTING,v 1.5 1999/08/27 23:35:59 peter Exp $
   2 $DragonFly: src/gnu/usr.bin/ld/Attic/PORTING,v 1.2 2003/06/17 04:25:46 dillon Exp $
   3
   4 This document describes some of the machine dependent parts in ld(1) and rtld(?)
   5 Most of the machine dependencies are a result of different ways in which
   6 relocation information is conveyed in an architecture's object files.
   7 Especially RISC architectures are likely candidates to have deviated from the
   8 traditional relocation record structure due a tendency to use odd sized
   9 "bitfields" to denote immediate operands within their fixed size instructions.
  10
  11 Also, there may be slight differences in the model used for Position
  12 Independent Code generation by the compiler.
  13
  14 Lastly, both ld and rtld must fiddle with actual machine instructions to setup
  15 a transfer vector to accommodate PIC code and dynamic linking.
  16
  17
  18 Machine dependent macros and data structures.
  19
  20 typedef struct jmpslot { ... } jmpslot_t;
  21
  22         The Procedure Linkage Table (PLT) is an array of these structures.
  23         The structure contains room for a control transfer instruction
  24         and a relocation index. md_make_jmpslot() and md_fix_jmpslot()
  25         are responsible for filling these in.
  26
  27 JMPSLOT_NEEDS_RELOC()
  28
  29         Macro indicating whether or not a jmpslot entry needs a run-time
  30         relocation when ld has already resolved the symbolic reference
  31         (eg. when `-Bsymbolic' was given). Usually the case if the control
  32         transfer instruction is PC relative or something.
  33
  34 RELOC_STATICS_THROUGH_GOT_P(r)
  35
  36         Predicate taking a `struct relocation_info *' as an argument. It
  37         decides whether variables with file scope are addressed relative to
  38         the start Global Offset Table (1) or an entry in GOT must be
  39         allocated (0). The compiler has a say in this.
  40
  41
  42 Some other random macros:
  43
  44 BAD_MID(ex)
  45
  46         Tells whether the machine ID in an input file header is acceptable.
  47
  48 N_SET_FLAG(ex,f)
  49
  50         Set flags F in a.out header. Must account for possible non-NetBSD
  51         headers; QMAGIC is still a documented ld output format.
  52
  53 N_IS_DYNAMIC(ex)
  54
  55         Return true if this appears to be a dynamically linked object.
  56
  57 #define relocation_info         reloc_info_<machine>
  58
  59         Define (possibly machine dependent) relocation record format.
  60         Should convert to a typedef someday for greater opacity.
  61
  62 md_got_reloc(r)
  63
  64         Adjustment to be applied to the relocation value of references
  65         to "_GLOBAL_OFFSET_TABLE". It's here because of Sun's sparc as(1),
  66         (it's is a *bug*), and could have been `#ifdef SUN_COMPAT' if I
  67         had not let it slip into NetBSD's gas for compatibility.
  68
  69 md_get_rt_segment_addend(r,a)
  70
  71         Another SunOS bug workaround.
  72
  73
  74 The macros below have defaults defined in ld.h for the traditional relocation
  75 structure format; each takes a `struct relocation_info *' argument (see
  76 ld.h for more detailed comments):
  77
  78 RELOC_ADDRESS(r)                - the address at which to relocate
  79 RELOC_EXTERN_P(r)               - relocation for external symbol
  80 RELOC_TYPE(r)                   - segment (text/data/bss), non-external relocs
  81 RELOC_SYMBOL(r)                 - symbol index, external relocs
  82 RELOC_MEMORY_SUB_P(r)           - relocation involves something to subtract
  83 RELOC_MEMORY_ADD_P(r)           - relocation involves something to add
  84 RELOC_ADD_EXTRA(r)              - <disused> (moved into MD files)
  85 RELOC_PCREL_P(r)                - relocation is PC relative
  86 RELOC_VALUE_RIGHTSHIFT(r)       - <disused>
  87 RELOC_TARGET_SIZE(r)            - size (in bytes) of relocated value
  88 RELOC_TARGET_BITPOS(r)          - <disused> (moved into MD files)
  89 RELOC_TARGET_BITSIZE(r)         - <disused> (moved into MD files)
  90 RELOC_JMPTAB_P(r)               - relocation is for a PLT entry
  91 RELOC_BASEREL_P(r)              - relocation is for a GOT entry
  92 RELOC_RELATIVE_P(r)             - relocation is load address relative
  93 RELOC_COPY_P(r)                 - relocation involves an initialization
  94 RELOC_INIT_SEGMENT_RELOC(r)     - initialize a relocation record pertaining to
  95                                   a segment; traditional archs can use bzero().
  96 RELOC_LAZY_P(r)                 - (run-time) resolution can be lazy.
  97 CHECK_GOT_RELOC(r)              - consistency check on relocations involving
  98                                   the "_GLOBAL_OFFSET_TABLE" symbol
  99
 100
 101
 102 Things which are currently defined as routines in <machine>/md.c:
 103
 104
 105 md_init_header(struct exec *hp, int magic, int flags)
 106
 107         Initializes the output file header. Straightforward, unless
 108         multiple OS'es are supported.
 109
 110
 111 md_swap*_exec_hdr(struct exec *)
 112
 113         Input/output a.out header in target byte-order.
 114
 115
 116 md_swap*_reloc(struct relocation_info *, n)
 117
 118         Input/output N relocation records in target byte-order.
 119
 120
 121 md_get_addend(struct relocation_info *rp, char *addr)
 122
 123         Return a relocation addend. Traditionally found in the object file
 124         at address ADDR. The relocation record determines the data width
 125         in bytes (using RELOC_TARGET_SIZE()).
 126
 127 md_relocate(struct relocation_info *rp, long reloc, char *addr,
 128             int relocatable_output)
 129
 130         Perform a relocation at the given address, usually by entering
 131         the specified value RELOC into the object file. Some architectures
 132         may store the relocation in RP when RELOCATABLE_OUTPUT is set.
 133         Again, the byte size of the relocation value is determined from
 134         RP through RELOC_TARGET_SIZE().
 135
 136 md_make_reloc(struct relocation_info *rp, int type)
 137
 138         Construct the machine dependent part of a relocation record used
 139         for run-time relocation. Sets RP's type field or one or more
 140         bitfields according to TYPE which is ld's internal relocation
 141         representation of the type of (run-time) relocation. TYPE is a
 142         combination of the following bits:
 143
 144         RELTYPE_EXTERN          - relocation is for unresolved symbol
 145         RELTYPE_JMPSLOT         - relocation is for a PLT entry
 146         RELTYPE_BASEREL         - <not used>
 147         RELTYPE_RELATIVE        - relocation is load address relative
 148         RELTYPE_COPY            - relocation is an initalization
 149
 150 md_make_jmpreloc(struct relocation_info *rp, *r, int type)
 151
 152         Set up a run-time relocation record pertaining to a jmpslot.
 153         This usually sets a bit or a relocation type dedicated to jmpslot
 154         relocations. R is the relocation record to be updated (ie. the
 155         run-time relocation record), while RP points at the relocation
 156         record from the object file on behalf of which we allocated a
 157         PLT entry. RP may not be needed.
 158
 159 md_make_gotreloc(struct relocation_info *rp, *r, int type)
 160
 161         Set up a run-time relocation record pertaining to a GOT entry.
 162         This usually sets a bit or a relocation type dedicated to GOT
 163         relocations. R is the relocation record to be updated (ie. the
 164         run-time relocation record), while RP points at the relocation
 165         record from the object file on behalf of which we allocated a
 166         GOT entry.
 167
 168 md_make_cpyreloc(struct relocation_info *rp, *r)
 169
 170         Mark the relocation record as pertaining to a location that needs
 171         run-time initializing from some shared object source.
 172         R and RP same as above.
 173
 174 md_make_jmpslot(jmpslot_t *sp, long offset, long index)
 175
 176         Construct a jmpslot, ie. fill in the machine opcodes that comprise
 177         a transfer to slot 0 of the PLT. OFFSET is the location of SP
 178         relative to the start of the PLT (ie. (int)sp - (int)&PLT[0] ).
 179         INDEX is the entry in the run-time relocation record table which
 180         determines what symbol this jmpslot is supposed to resolve.
 181
 182 md_fix_jmpslot(jmpslot_t *sp, long offset, long addr)
 183
 184         Fix up a jmpslot so that it will transfer directly to ADDR
 185         in stead of to PLT[0]. OFFSET has the same meaning as in
 186         md_make_jmpslot(). This function is called by binder() after
 187         it has resolved a symbol into a (run-time) address.
 188
 189 md_set_breakpoint(long where, long *savep)
 190
 191         Set a breakpoint. Used when run under a debugger. The breakpoint
 192         instruction is to be set at location WHERE. The original contents
 193         of *WHERE is to be saved in *SAVEP.
 194
 195