Mercurial > hg > index.cgi

comparison docs/manual/x807.html @ 254:155799f6cfa5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the FILL pseudo operation
author William Astle <lost@l-w.ca>
date Wed, 30 Jan 2013 21:32:14 -0700
parents
children c4853a54b4a1
comparison
equal deleted inserted replaced
253:ed1009bce533 254:155799f6cfa5
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >Linking Scripts</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME"
10 TITLE="LW Tool Chain"
11 HREF="index.html"><LINK
12 REL="UP"
13 TITLE="LWLINK"
14 HREF="c693.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Linker Operation"
17 HREF="x793.html"><LINK
18 REL="NEXT"
19 TITLE="Format Specific Linking Notes"
20 HREF="x864.html"></HEAD
21 ><BODY
22 CLASS="SECTION"
23 BGCOLOR="#FFFFFF"
24 TEXT="#000000"
25 LINK="#0000FF"
26 VLINK="#840084"
27 ALINK="#0000FF"
28 ><DIV
29 CLASS="NAVHEADER"
30 ><TABLE
31 SUMMARY="Header navigation table"
32 WIDTH="100%"
33 BORDER="0"
34 CELLPADDING="0"
35 CELLSPACING="0"
36 ><TR
37 ><TH
38 COLSPAN="3"
39 ALIGN="center"
40 >LW Tool Chain</TH
41 ></TR
42 ><TR
43 ><TD
44 WIDTH="10%"
45 ALIGN="left"
46 VALIGN="bottom"
47 ><A
48 HREF="x793.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 4. LWLINK</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="x864.html"
63 ACCESSKEY="N"
64 >Next</A
65 ></TD
66 ></TR
67 ></TABLE
68 ><HR
69 ALIGN="LEFT"
70 WIDTH="100%"></DIV
71 ><DIV
72 CLASS="SECTION"
73 ><H1
74 CLASS="SECTION"
75 ><A
76 NAME="AEN807"
77 >4.3. Linking Scripts</A
78 ></H1
79 ><P
80 >A linker script is used to instruct the linker about how to assemble the
81 various sections into a completed binary. It consists of a series of
82 directives which are considered in the order they are encountered.</P
83 ><P
84 >The sections will appear in the resulting binary in the order they are
85 specified in the script file. If a referenced section is not found, the linker will behave as though the
86 section did exist but had a zero size, no relocations, and no exports.
87 A section should only be referenced once. Any subsequent references will have
88 an undefined effect.</P
89 ><P
90 >All numbers are in linking scripts are specified in hexadecimal. All directives
91 are case sensitive although the hexadecimal numbers are not.</P
92 ><P
93 >A section name can be specified as a "*", then any section not
94 already matched by the script will be matched. The "*" can be followed
95 by a comma and a flag to narrow the section down slightly, also.
96 If the flag is "!bss", then any section that is not flagged as a bss section
97 will be matched. If the flag is "bss", then any section that is flagged as
98 bss will be matched.</P
99 ><P
100 >The following directives are understood in a linker script.</P
101 ><P
102 ></P
103 ><DIV
104 CLASS="VARIABLELIST"
105 ><DL
106 ><DT
107 >sectopt <CODE
108 CLASS="PARAMETER"
109 >section</CODE
110 > padafter <CODE
111 CLASS="PARAMETER"
112 >byte,...</CODE
113 ></DT
114 ><DD
115 ><P
116 >&#13;This will cause the linker to append the specified list of byte values
117 (specified in hexadecimal separated by commas) to the end of the named
118 section. This is done once all instances of the specified section are
119 collected together. This has no effect if the specified section does not
120 appear anywhere in any of the objects specified for linking. &#13;</P
121 ><P
122 >&#13;If code depends on the presence of this padding somewhere, it is sufficient
123 to include an empty section of the specified name in the object that depends
124 on it.&#13;</P
125 ></DD
126 ><DT
127 >define basesympat <CODE
128 CLASS="PARAMETER"
129 >string</CODE
130 ></DT
131 ><DD
132 ><P
133 >&#13;This causes the linker to define a symbol for the ultimate base address of
134 each section using the pattern specified by <CODE
135 CLASS="PARAMETER"
136 >string</CODE
137 >.
138 In the string, %s can appear exactly once and will be replaced with the
139 section name. The base address is calculated after all instances of each
140 section have been collapsed together.&#13;</P
141 ><P
142 >&#13;It should be noted that if none of the objects to be linked contains a
143 particular section name, there will be no base symbol defined for it, even
144 if it is listed explicitly in the link script. If code depends on the
145 presence of these symbols, it is sufficient to include an empty section of
146 the specified name in the object that depends on it.&#13;</P
147 ><P
148 > If the pattern resolves to the same string for multiple
149 sections, the results are undefined.&#13;</P
150 ></DD
151 ><DT
152 >define lensympat <CODE
153 CLASS="PARAMETER"
154 >string</CODE
155 ></DT
156 ><DD
157 ><P
158 >&#13;This causes the linker to define a symbol for the ultimate length of each
159 section using the pattern specified by <CODE
160 CLASS="PARAMETER"
161 >string</CODE
162 >. In
163 the string, %s can appear exactly once and will be replaced with the section
164 name. The length is calculated after all instances of a section have been
165 collapsed together.&#13;</P
166 ><P
167 >&#13;It should be noted that if none of the objects to be linked contains a
168 particular section name, there will be no length symbol defined for it, even
169 if it is listed explicitly in the link script. If code depends on the
170 presence of these symbols, it is sufficient to include an empty section of
171 the specified name in the object that depends on it.&#13;</P
172 ><P
173 >If the pattern resolves to the same string for multiple
174 sections, the results are undefined.&#13;</P
175 ></DD
176 ><DT
177 >section <CODE
178 CLASS="PARAMETER"
179 >name</CODE
180 > load <CODE
181 CLASS="PARAMETER"
182 >addr</CODE
183 ></DT
184 ><DD
185 ><P
186 >&#13;This causes the section <CODE
187 CLASS="PARAMETER"
188 >name</CODE
189 > to load at
190 <CODE
191 CLASS="PARAMETER"
192 >addr</CODE
193 >. For the raw target, only one "load at" entry is
194 allowed for non-bss sections and it must be the first one. For raw targets,
195 it affects the addresses the linker assigns to symbols but has no other
196 affect on the output. bss sections may all have separate load addresses but
197 since they will not appear in the binary anyway, this is okay.</P
198 ><P
199 >For the decb target, each "load" entry will cause a new "block" to be
200 output to the binary which will contain the load address. It is legal for
201 sections to overlap in this manner - the linker assumes the loader will sort
202 everything out.</P
203 ></DD
204 ><DT
205 >section <CODE
206 CLASS="PARAMETER"
207 >name</CODE
208 ></DT
209 ><DD
210 ><P
211 >&#13;This will cause the section <CODE
212 CLASS="PARAMETER"
213 >name</CODE
214 > to load after the previously listed
215 section.</P
216 ></DD
217 ><DT
218 >entry <CODE
219 CLASS="PARAMETER"
220 >addr or sym</CODE
221 ></DT
222 ><DD
223 ><P
224 >This will cause the execution address (entry point) to be the address
225 specified (in hex) or the specified symbol name. The symbol name must
226 match a symbol that is exported by one of the object files being linked.
227 This has no effect for targets that do not encode the entry point into the
228 resulting file. If not specified, the entry point is assumed to be address 0
229 which is probably not what you want. The default link scripts for targets
230 that support this directive automatically starts at the beginning of the
231 first section (usually "init" or "code") that is emitted in the binary.</P
232 ></DD
233 ><DT
234 >pad <CODE
235 CLASS="PARAMETER"
236 >size</CODE
237 ></DT
238 ><DD
239 ><P
240 >This will cause the output file to be padded with NUL bytes to be exactly
241 <CODE
242 CLASS="PARAMETER"
243 >size</CODE
244 > bytes in length. This only makes sense for a raw target.</P
245 ></DD
246 ></DL
247 ></DIV
248 ></DIV
249 ><DIV
250 CLASS="NAVFOOTER"
251 ><HR
252 ALIGN="LEFT"
253 WIDTH="100%"><TABLE
254 SUMMARY="Footer navigation table"
255 WIDTH="100%"
256 BORDER="0"
257 CELLPADDING="0"
258 CELLSPACING="0"
259 ><TR
260 ><TD
261 WIDTH="33%"
262 ALIGN="left"
263 VALIGN="top"
264 ><A
265 HREF="x793.html"
266 ACCESSKEY="P"
267 >Prev</A
268 ></TD
269 ><TD
270 WIDTH="34%"
271 ALIGN="center"
272 VALIGN="top"
273 ><A
274 HREF="index.html"
275 ACCESSKEY="H"
276 >Home</A
277 ></TD
278 ><TD
279 WIDTH="33%"
280 ALIGN="right"
281 VALIGN="top"
282 ><A
283 HREF="x864.html"
284 ACCESSKEY="N"
285 >Next</A
286 ></TD
287 ></TR
288 ><TR
289 ><TD
290 WIDTH="33%"
291 ALIGN="left"
292 VALIGN="top"
293 >Linker Operation</TD
294 ><TD
295 WIDTH="34%"
296 ALIGN="center"
297 VALIGN="top"
298 ><A
299 HREF="c693.html"
300 ACCESSKEY="U"
301 >Up</A
302 ></TD
303 ><TD
304 WIDTH="33%"
305 ALIGN="right"
306 VALIGN="top"
307 >Format Specific Linking Notes</TD
308 ></TR
309 ></TABLE
310 ></DIV
311 ></BODY
312 ></HTML
313 >