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 $
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.
11 Also, there may be slight differences in the model used for Position
12 Independent Code generation by the compiler.
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.
18 Machine dependent macros and data structures.
20 typedef struct jmpslot { ... } jmpslot_t;
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.
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.
34 RELOC_STATICS_THROUGH_GOT_P(r)
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.
42 Some other random macros:
46 Tells whether the machine ID in an input file header is acceptable.
50 Set flags F in a.out header. Must account for possible non-NetBSD
51 headers; QMAGIC is still a documented ld output format.
55 Return true if this appears to be a dynamically linked object.
57 #define relocation_info reloc_info_<machine>
59 Define (possibly machine dependent) relocation record format.
60 Should convert to a typedef someday for greater opacity.
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.
69 md_get_rt_segment_addend(r,a)
71 Another SunOS bug workaround.
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):
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
102 Things which are currently defined as routines in <machine>/md.c:
105 md_init_header(struct exec *hp, int magic, int flags)
107 Initializes the output file header. Straightforward, unless
108 multiple OS'es are supported.
111 md_swap*_exec_hdr(struct exec *)
113 Input/output a.out header in target byte-order.
116 md_swap*_reloc(struct relocation_info *, n)
118 Input/output N relocation records in target byte-order.
121 md_get_addend(struct relocation_info *rp, char *addr)
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()).
127 md_relocate(struct relocation_info *rp, long reloc, char *addr,
128 int relocatable_output)
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().
136 md_make_reloc(struct relocation_info *rp, int type)
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:
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
150 md_make_jmpreloc(struct relocation_info *rp, *r, int type)
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.
159 md_make_gotreloc(struct relocation_info *rp, *r, int type)
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
168 md_make_cpyreloc(struct relocation_info *rp, *r)
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.
174 md_make_jmpslot(jmpslot_t *sp, long offset, long index)
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.
182 md_fix_jmpslot(jmpslot_t *sp, long offset, long addr)
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.
189 md_set_breakpoint(long where, long *savep)
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.