Mercurial > hg > index.cgi

comparison docs/manual/x827.html @ 333:507f442dc71e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add support for 6800 compatibility instructions. The occasional program uses the 6800 compatibility instructions since they are actually specified by Motorola in at least some documentation. They advertised the 6809 as source compatible with the 6800. This mode is not enabled by default, however. It is my belief that receiving an error when using a non-6809 instruction is more useful since it is unlikely that much 6800 source code is being assembled for the 6809 these days. Nevertheless, the --6809compat option is present for just those purposes so one does not have to resort to using macros (which would work equally well in most cases).
author William Astle <lost@l-w.ca>
date Tue, 15 Apr 2014 10:57:34 -0600
parents b30091890d62
children
comparison
equal deleted inserted replaced
332:26bfe8d557e2 333:507f442dc71e
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2 <HTML 2 <HTML
3 ><HEAD 3 ><HEAD
4 ><TITLE 4 ><TITLE
5 >Linking Scripts</TITLE 5 >Linker Operation</TITLE
6 ><META 6 ><META
7 NAME="GENERATOR" 7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME" 9 REL="HOME"
10 TITLE="LW Tool Chain" 10 TITLE="LW Tool Chain"
11 HREF="index.html"><LINK 11 HREF="index.html"><LINK
12 REL="UP" 12 REL="UP"
13 TITLE="LWLINK" 13 TITLE="LWLINK"
14 HREF="c713.html"><LINK 14 HREF="c727.html"><LINK
15 REL="PREVIOUS" 15 REL="PREVIOUS"
16 TITLE="Linker Operation" 16 TITLE="LWLINK"
17 HREF="x813.html"><LINK 17 HREF="c727.html"><LINK
18 REL="NEXT" 18 REL="NEXT"
19 TITLE="Format Specific Linking Notes" 19 TITLE="Linking Scripts"
20 HREF="x893.html"></HEAD 20 HREF="x841.html"></HEAD
21 ><BODY 21 ><BODY
22 CLASS="SECTION" 22 CLASS="SECTION"
23 BGCOLOR="#FFFFFF" 23 BGCOLOR="#FFFFFF"
24 TEXT="#000000" 24 TEXT="#000000"
25 LINK="#0000FF" 25 LINK="#0000FF"
43 ><TD 43 ><TD
44 WIDTH="10%" 44 WIDTH="10%"
45 ALIGN="left" 45 ALIGN="left"
46 VALIGN="bottom" 46 VALIGN="bottom"
47 ><A 47 ><A
48 HREF="x813.html" 48 HREF="c727.html"
49 ACCESSKEY="P" 49 ACCESSKEY="P"
50 >Prev</A 50 >Prev</A
51 ></TD 51 ></TD
52 ><TD 52 ><TD
53 WIDTH="80%" 53 WIDTH="80%"
57 ><TD 57 ><TD
58 WIDTH="10%" 58 WIDTH="10%"
59 ALIGN="right" 59 ALIGN="right"
60 VALIGN="bottom" 60 VALIGN="bottom"
61 ><A 61 ><A
62 HREF="x893.html" 62 HREF="x841.html"
63 ACCESSKEY="N" 63 ACCESSKEY="N"
64 >Next</A 64 >Next</A
65 ></TD 65 ></TD
66 ></TR 66 ></TR
67 ></TABLE 67 ></TABLE
72 CLASS="SECTION" 72 CLASS="SECTION"
73 ><H1 73 ><H1
74 CLASS="SECTION" 74 CLASS="SECTION"
75 ><A 75 ><A
76 NAME="AEN827" 76 NAME="AEN827"
77 >4.3. Linking Scripts</A 77 >4.2. Linker Operation</A
78 ></H1 78 ></H1
79 ><P 79 ><P
80 >A linker script is used to instruct the linker about how to assemble the 80 >&#13;LWLINK takes one or more files in supported input formats and links them
81 various sections into a completed binary. It consists of a series of 81 into a single binary. Currently supported formats are the LWTOOLS object
82 directives which are considered in the order they are encountered.</P 82 file format and the archive format used by LWAR. While the precise method is
83 ><P 83 slightly different, linking can be conceptualized as the following steps.&#13;</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 84 ><P
102 ></P 85 ></P
103 ><DIV 86 ><OL
104 CLASS="VARIABLELIST" 87 TYPE="1"
105 ><DL 88 ><LI
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 89 ><P
116 >&#13;This will cause the linker to append the specified list of byte values 90 >First, the linker loads a linking script. If no script is specified, it
117 (specified in hexadecimal separated by commas) to the end of the named 91 loads a built-in default script based on the output format selected. This
118 section. This is done once all instances of the specified section are 92 script tells the linker how to lay out the various sections in the final
119 collected together. This has no effect if the specified section does not 93 binary.</P
120 appear anywhere in any of the objects specified for linking. &#13;</P 94 ></LI
95 ><LI
121 ><P 96 ><P
122 >&#13;If code depends on the presence of this padding somewhere, it is sufficient 97 >Next, the linker reads all the input files into memory. At this time, it
123 to include an empty section of the specified name in the object that depends 98 flags any format errors in those files. It constructs a table of symbols
124 on it.&#13;</P 99 for each object at this time.</P
125 ></DD 100 ></LI
126 ><DT 101 ><LI
127 >define basesympat <CODE
128 CLASS="PARAMETER"
129 >string</CODE
130 ></DT
131 ><DD
132 ><P 102 ><P
133 >&#13;This causes the linker to define a symbol for the ultimate base address of 103 >The linker then proceeds with organizing the sections loaded from each file
134 each section using the pattern specified by <CODE 104 according to the linking script. As it does so, it is able to assign addresses
135 CLASS="PARAMETER" 105 to each symbol defined in each object file. At this time, the linker may
136 >string</CODE 106 also collapse different instances of the same section name into a single
137 >. 107 section by appending the data from each subsequent instance of the section
138 In the string, %s can appear exactly once and will be replaced with the 108 to the first instance of the section.</P
139 section name. The base address is calculated after all instances of each 109 ></LI
140 section have been collapsed together.&#13;</P 110 ><LI
141 ><P 111 ><P
142 >&#13;It should be noted that if none of the objects to be linked contains a 112 >Next, the linker looks through every object file for every incomplete reference.
143 particular section name, there will be no base symbol defined for it, even 113 It then attempts to fully resolve that reference. If it cannot do so, it
144 if it is listed explicitly in the link script. If code depends on the 114 throws an error. Once a reference is resolved, the value is placed into
145 presence of these symbols, it is sufficient to include an empty section of 115 the binary code at the specified section. It should be noted that an
146 the specified name in the object that depends on it.&#13;</P 116 incomplete reference can reference either a symbol internal to the object
117 file or an external symbol which is in the export list of another object
118 file.</P
119 ></LI
120 ><LI
147 ><P 121 ><P
148 > If the pattern resolves to the same string for multiple 122 >If all of the above steps are successful, the linker opens the output file
149 sections, the results are undefined.&#13;</P 123 and actually constructs the binary.</P
150 ></DD 124 ></LI
151 ><DT 125 ></OL
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 > high <CODE
209 CLASS="PARAMETER"
210 >addr</CODE
211 ></DT
212 ><DD
213 ><P
214 >&#13;This causes the section <CODE
215 CLASS="PARAMETER"
216 >name</CODE
217 > to load with its end
218 address just below <CODE
219 CLASS="PARAMETER"
220 >addr</CODE
221 >. Subsequent sections are
222 loaded at progressively lower addresses. This may lead to inefficient file
223 encoding for some targets. As of this writing, it will also almost
224 certainly do the wrong thing for a raw target.&#13;</P
225 ><P
226 >&#13;This is useful for aligning a block of code with high memory. As an
227 example, if the total size of a section is $100 bytes and a high address of
228 $FE00 is specified, the section will actually load at $FD00.&#13;</P
229 ></DD
230 ><DT
231 >section <CODE
232 CLASS="PARAMETER"
233 >name</CODE
234 ></DT
235 ><DD
236 ><P
237 >&#13;This will cause the section <CODE
238 CLASS="PARAMETER"
239 >name</CODE
240 > to load after the previously listed
241 section.</P
242 ></DD
243 ><DT
244 >entry <CODE
245 CLASS="PARAMETER"
246 >addr or sym</CODE
247 ></DT
248 ><DD
249 ><P
250 >This will cause the execution address (entry point) to be the address
251 specified (in hex) or the specified symbol name. The symbol name must
252 match a symbol that is exported by one of the object files being linked.
253 This has no effect for targets that do not encode the entry point into the
254 resulting file. If not specified, the entry point is assumed to be address 0
255 which is probably not what you want. The default link scripts for targets
256 that support this directive automatically starts at the beginning of the
257 first section (usually "init" or "code") that is emitted in the binary.</P
258 ></DD
259 ><DT
260 >pad <CODE
261 CLASS="PARAMETER"
262 >size</CODE
263 ></DT
264 ><DD
265 ><P
266 >This will cause the output file to be padded with NUL bytes to be exactly
267 <CODE
268 CLASS="PARAMETER"
269 >size</CODE
270 > bytes in length. This only makes sense for a raw target.</P
271 ></DD
272 ></DL
273 ></DIV
274 ></DIV 126 ></DIV
275 ><DIV 127 ><DIV
276 CLASS="NAVFOOTER" 128 CLASS="NAVFOOTER"
277 ><HR 129 ><HR
278 ALIGN="LEFT" 130 ALIGN="LEFT"
286 ><TD 138 ><TD
287 WIDTH="33%" 139 WIDTH="33%"
288 ALIGN="left" 140 ALIGN="left"
289 VALIGN="top" 141 VALIGN="top"
290 ><A 142 ><A
291 HREF="x813.html" 143 HREF="c727.html"
292 ACCESSKEY="P" 144 ACCESSKEY="P"
293 >Prev</A 145 >Prev</A
294 ></TD 146 ></TD
295 ><TD 147 ><TD
296 WIDTH="34%" 148 WIDTH="34%"
304 ><TD 156 ><TD
305 WIDTH="33%" 157 WIDTH="33%"
306 ALIGN="right" 158 ALIGN="right"
307 VALIGN="top" 159 VALIGN="top"
308 ><A 160 ><A
309 HREF="x893.html" 161 HREF="x841.html"
310 ACCESSKEY="N" 162 ACCESSKEY="N"
311 >Next</A 163 >Next</A
312 ></TD 164 ></TD
313 ></TR 165 ></TR
314 ><TR 166 ><TR
315 ><TD 167 ><TD
316 WIDTH="33%" 168 WIDTH="33%"
317 ALIGN="left" 169 ALIGN="left"
318 VALIGN="top" 170 VALIGN="top"
319 >Linker Operation</TD 171 >LWLINK</TD
320 ><TD 172 ><TD
321 WIDTH="34%" 173 WIDTH="34%"
322 ALIGN="center" 174 ALIGN="center"
323 VALIGN="top" 175 VALIGN="top"
324 ><A 176 ><A
325 HREF="c713.html" 177 HREF="c727.html"
326 ACCESSKEY="U" 178 ACCESSKEY="U"
327 >Up</A 179 >Up</A
328 ></TD 180 ></TD
329 ><TD 181 ><TD
330 WIDTH="33%" 182 WIDTH="33%"
331 ALIGN="right" 183 ALIGN="right"
332 VALIGN="top" 184 VALIGN="top"
333 >Format Specific Linking Notes</TD 185 >Linking Scripts</TD
334 ></TR 186 ></TR
335 ></TABLE 187 ></TABLE
336 ></DIV 188 ></DIV
337 ></BODY 189 ></BODY
338 ></HTML 190 ></HTML