Mercurial > hg-old > index.cgi

comparison doc/manual/x507.html @ 398:7987ee447833 3.0-beta1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added generated files for release
author lost@l-w.ca
date Fri, 23 Jul 2010 17:18:52 -0600
parents
children
comparison
equal deleted inserted replaced
397:09fe7c40a082 398:7987ee447833
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 >Object Files and Sections</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="LWASM"
14 HREF="c43.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Structures"
17 HREF="x487.html"><LINK
18 REL="NEXT"
19 TITLE="Assembler Modes and Pragmas"
20 HREF="x571.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="x487.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 3. LWASM</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="x571.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="AEN507"
77 >3.9. Object Files and Sections</A
78 ></H1
79 ><P
80 >The object file target is very useful for large project because it allows
81 multiple files to be assembled independently and then linked into the final
82 binary at a later time. It allows only the small portion of the project
83 that was modified to be re-assembled rather than requiring the entire set
84 of source code to be available to the assembler in a single assembly process.
85 This can be particularly important if there are a large number of macros,
86 symbol definitions, or other metadata that uses resources at assembly time.
87 By far the largest benefit, however, is keeping the source files small enough
88 for a mere mortal to find things in them.</P
89 ><P
90 >With multi-file projects, there needs to be a means of resolving references to
91 symbols in other source files. These are known as external references. The
92 addresses of these symbols cannot be known until the linker joins all the
93 object files into a single binary. This means that the assembler must be
94 able to output the object code without knowing the value of the symbol. This
95 places some restrictions on the code generated by the assembler. For
96 example, the assembler cannot generate direct page addressing for instructions
97 that reference external symbols because the address of the symbol may not
98 be in the direct page. Similarly, relative branches and PC relative addressing
99 cannot be used in their eight bit forms. Everything that must be resolved
100 by the linker must be assembled to use the largest address size possible to
101 allow the linker to fill in the correct value at link time. Note that the
102 same problem applies to absolute address references as well, even those in
103 the same source file, because the address is not known until link time.</P
104 ><P
105 >It is often desired in multi-file projects to have code of various types grouped
106 together in the final binary generated by the linker as well. The same applies
107 to data. In order for the linker to do that, the bits that are to be grouped
108 must be tagged in some manner. This is where the concept of sections comes in.
109 Each chunk of code or data is part of a section in the object file. Then,
110 when the linker reads all the object files, it coalesces all sections of the
111 same name into a single section and then considers it as a unit.</P
112 ><P
113 >The existence of sections, however, raises a problem for symbols even
114 within the same source file. Thus, the assembler must treat symbols from
115 different sections within the same source file in the same manner as external
116 symbols. That is, it must leave them for the linker to resolve at link time,
117 with all the limitations that entails.</P
118 ><P
119 >In the object file target mode, LWASM requires all source lines that
120 cause bytes to be output to be inside a section. Any directives that do
121 not cause any bytes to be output can appear outside of a section. This includes
122 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however,
123 makes no sense within a section because it is the linker that determines
124 the starting address of the section's code, not the assembler.</P
125 ><P
126 >All symbols defined globally in the assembly process are local to the
127 source file and cannot be exported. All symbols defined within a section are
128 considered local to the source file unless otherwise explicitly exported.
129 Symbols referenced from external source files must be declared external,
130 either explicitly or by asking the assembler to assume that all undefined
131 symbols are external.</P
132 ><P
133 >It is often handy to define a number of memory addresses that will be
134 used for data at run-time but which need not be included in the binary file.
135 These memory addresses are not initialized until run-time, either by the
136 program itself or by the program loader, depending on the operating environment.
137 Such sections are often known as BSS sections. LWASM supports generating
138 sections with a BSS attribute set which causes the section definition including
139 symbols exported from that section and those symbols required to resolve
140 references from the local file, but with no actual code in the object file.
141 It is illegal for any source lines within a BSS flagged section to cause any
142 bytes to be output.</P
143 ><P
144 >The following directives apply to section handling.</P
145 ><P
146 ></P
147 ><DIV
148 CLASS="VARIABLELIST"
149 ><DL
150 ><DT
151 >SECTION <CODE
152 CLASS="PARAMETER"
153 >name[,flags]</CODE
154 >, SECT <CODE
155 CLASS="PARAMETER"
156 >name[,flags]</CODE
157 >, .AREA <CODE
158 CLASS="PARAMETER"
159 >name[,flags]</CODE
160 ></DT
161 ><DD
162 ><P
163 >Instructs the assembler that the code following this directive is to be
164 considered part of the section <CODE
165 CLASS="PARAMETER"
166 >name</CODE
167 >. A section name
168 may appear multiple times in which case it is as though all the code from
169 all the instances of that section appeared adjacent within the source file.
170 However, <CODE
171 CLASS="PARAMETER"
172 >flags</CODE
173 > may only be specified on the first
174 instance of the section.</P
175 ><P
176 >There is a single flag supported in <CODE
177 CLASS="PARAMETER"
178 >flags</CODE
179 >. The
180 flag <CODE
181 CLASS="PARAMETER"
182 >bss</CODE
183 > will cause the section to be treated as a BSS
184 section and, thus, no code will be included in the object file nor will any
185 bytes be permitted to be output.</P
186 ><P
187 >If the section name is "bss" or ".bss" in any combination of upper and
188 lower case, the section is assumed to be a BSS section. In that case,
189 the flag <CODE
190 CLASS="PARAMETER"
191 >!bss</CODE
192 > can be used to override this assumption.</P
193 ><P
194 >If assembly is already happening within a section, the section is implicitly
195 ended and the new section started. This is not considered an error although
196 it is recommended that all sections be explicitly closed.</P
197 ></DD
198 ><DT
199 >ENDSECTION, ENDSECT, ENDS</DT
200 ><DD
201 ><P
202 >This directive ends the current section. This puts assembly outside of any
203 sections until the next SECTION directive.</P
204 ></DD
205 ><DT
206 ><CODE
207 CLASS="PARAMETER"
208 >sym</CODE
209 > EXTERN, <CODE
210 CLASS="PARAMETER"
211 >sym</CODE
212 > EXTERNAL, <CODE
213 CLASS="PARAMETER"
214 >sym</CODE
215 > IMPORT</DT
216 ><DD
217 ><P
218 >This directive defines <CODE
219 CLASS="PARAMETER"
220 >sym</CODE
221 > as an external symbol.
222 This directive may occur at any point in the source code. EXTERN definitions
223 are resolved on the first pass so an EXTERN definition anywhere in the
224 source file is valid for the entire file. The use of this directive is
225 optional when the assembler is instructed to assume that all undefined
226 symbols are external. In fact, in that mode, if the symbol is referenced
227 before the EXTERN directive, an error will occur.</P
228 ></DD
229 ><DT
230 ><CODE
231 CLASS="PARAMETER"
232 >sym</CODE
233 > EXPORT, <CODE
234 CLASS="PARAMETER"
235 >sym</CODE
236 > .GLOBL, EXPORT <CODE
237 CLASS="PARAMETER"
238 >sym</CODE
239 >, .GLOBL <CODE
240 CLASS="PARAMETER"
241 >sym</CODE
242 ></DT
243 ><DD
244 ><P
245 >This directive defines <CODE
246 CLASS="PARAMETER"
247 >sym</CODE
248 > as an exported symbol.
249 This directive may occur at any point in the source code, even before the
250 definition of the exported symbol.</P
251 ><P
252 >Note that <CODE
253 CLASS="PARAMETER"
254 >sym</CODE
255 > may appear as the operand or as the
256 statement's symbol. If there is a symbol on the statement, that will
257 take precedence over any operand that is present.</P
258 ></DD
259 ><DT
260 ><CODE
261 CLASS="PARAMETER"
262 >sym</CODE
263 > EXTDEP</DT
264 ><DD
265 ><P
266 >This directive forces an external dependency on
267 <CODE
268 CLASS="PARAMETER"
269 >sym</CODE
270 >, even if it is never referenced anywhere else in
271 this file.</P
272 ></DD
273 ></DL
274 ></DIV
275 ></DIV
276 ><DIV
277 CLASS="NAVFOOTER"
278 ><HR
279 ALIGN="LEFT"
280 WIDTH="100%"><TABLE
281 SUMMARY="Footer navigation table"
282 WIDTH="100%"
283 BORDER="0"
284 CELLPADDING="0"
285 CELLSPACING="0"
286 ><TR
287 ><TD
288 WIDTH="33%"
289 ALIGN="left"
290 VALIGN="top"
291 ><A
292 HREF="x487.html"
293 ACCESSKEY="P"
294 >Prev</A
295 ></TD
296 ><TD
297 WIDTH="34%"
298 ALIGN="center"
299 VALIGN="top"
300 ><A
301 HREF="index.html"
302 ACCESSKEY="H"
303 >Home</A
304 ></TD
305 ><TD
306 WIDTH="33%"
307 ALIGN="right"
308 VALIGN="top"
309 ><A
310 HREF="x571.html"
311 ACCESSKEY="N"
312 >Next</A
313 ></TD
314 ></TR
315 ><TR
316 ><TD
317 WIDTH="33%"
318 ALIGN="left"
319 VALIGN="top"
320 >Structures</TD
321 ><TD
322 WIDTH="34%"
323 ALIGN="center"
324 VALIGN="top"
325 ><A
326 HREF="c43.html"
327 ACCESSKEY="U"
328 >Up</A
329 ></TD
330 ><TD
331 WIDTH="33%"
332 ALIGN="right"
333 VALIGN="top"
334 >Assembler Modes and Pragmas</TD
335 ></TR
336 ></TABLE
337 ></DIV
338 ></BODY
339 ></HTML
340 >