Mercurial > hg > index.cgi

comparison docs/manual/x795.html @ 231:2cc599f1bebf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added --define to lwasm documentation. Added documentation of the -D/--define command line option for lwasm. It has been present for a long time but has somehow escaped documentation.
author William Astle <lost@l-w.ca>
date Sun, 15 Jul 2012 23:12:09 -0600
parents
children d389adbcc4ab
comparison
equal deleted inserted replaced
230:e09985968e64 231:2cc599f1bebf
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="c681.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Linker Operation"
17 HREF="x781.html"><LINK
18 REL="NEXT"
19 TITLE="Format Specific Linking Notes"
20 HREF="x829.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="x781.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="x829.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="AEN795"
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 >section <CODE
108 CLASS="PARAMETER"
109 >name</CODE
110 > load <CODE
111 CLASS="PARAMETER"
112 >addr</CODE
113 ></DT
114 ><DD
115 ><P
116 >&#13;This causes the section <CODE
117 CLASS="PARAMETER"
118 >name</CODE
119 > to load at
120 <CODE
121 CLASS="PARAMETER"
122 >addr</CODE
123 >. For the raw target, only one "load at" entry is
124 allowed for non-bss sections and it must be the first one. For raw targets,
125 it affects the addresses the linker assigns to symbols but has no other
126 affect on the output. bss sections may all have separate load addresses but
127 since they will not appear in the binary anyway, this is okay.</P
128 ><P
129 >For the decb target, each "load" entry will cause a new "block" to be
130 output to the binary which will contain the load address. It is legal for
131 sections to overlap in this manner - the linker assumes the loader will sort
132 everything out.</P
133 ></DD
134 ><DT
135 >section <CODE
136 CLASS="PARAMETER"
137 >name</CODE
138 ></DT
139 ><DD
140 ><P
141 >&#13;This will cause the section <CODE
142 CLASS="PARAMETER"
143 >name</CODE
144 > to load after the previously listed
145 section.</P
146 ></DD
147 ><DT
148 >entry <CODE
149 CLASS="PARAMETER"
150 >addr or sym</CODE
151 ></DT
152 ><DD
153 ><P
154 >This will cause the execution address (entry point) to be the address
155 specified (in hex) or the specified symbol name. The symbol name must
156 match a symbol that is exported by one of the object files being linked.
157 This has no effect for targets that do not encode the entry point into the
158 resulting file. If not specified, the entry point is assumed to be address 0
159 which is probably not what you want. The default link scripts for targets
160 that support this directive automatically starts at the beginning of the
161 first section (usually "init" or "code") that is emitted in the binary.</P
162 ></DD
163 ><DT
164 >pad <CODE
165 CLASS="PARAMETER"
166 >size</CODE
167 ></DT
168 ><DD
169 ><P
170 >This will cause the output file to be padded with NUL bytes to be exactly
171 <CODE
172 CLASS="PARAMETER"
173 >size</CODE
174 > bytes in length. This only makes sense for a raw target.</P
175 ></DD
176 ></DL
177 ></DIV
178 ></DIV
179 ><DIV
180 CLASS="NAVFOOTER"
181 ><HR
182 ALIGN="LEFT"
183 WIDTH="100%"><TABLE
184 SUMMARY="Footer navigation table"
185 WIDTH="100%"
186 BORDER="0"
187 CELLPADDING="0"
188 CELLSPACING="0"
189 ><TR
190 ><TD
191 WIDTH="33%"
192 ALIGN="left"
193 VALIGN="top"
194 ><A
195 HREF="x781.html"
196 ACCESSKEY="P"
197 >Prev</A
198 ></TD
199 ><TD
200 WIDTH="34%"
201 ALIGN="center"
202 VALIGN="top"
203 ><A
204 HREF="index.html"
205 ACCESSKEY="H"
206 >Home</A
207 ></TD
208 ><TD
209 WIDTH="33%"
210 ALIGN="right"
211 VALIGN="top"
212 ><A
213 HREF="x829.html"
214 ACCESSKEY="N"
215 >Next</A
216 ></TD
217 ></TR
218 ><TR
219 ><TD
220 WIDTH="33%"
221 ALIGN="left"
222 VALIGN="top"
223 >Linker Operation</TD
224 ><TD
225 WIDTH="34%"
226 ALIGN="center"
227 VALIGN="top"
228 ><A
229 HREF="c681.html"
230 ACCESSKEY="U"
231 >Up</A
232 ></TD
233 ><TD
234 WIDTH="33%"
235 ALIGN="right"
236 VALIGN="top"
237 >Format Specific Linking Notes</TD
238 ></TR
239 ></TABLE
240 ></DIV
241 ></BODY
242 ></HTML
243 >