Mercurial > hg-old > index.cgi

comparison doc/manual/x517.html @ 434:b8bf63962a99 3.0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added various generated files for release
author lost@l-w.ca
date Fri, 29 Oct 2010 19:20:39 -0600
parents
children
comparison
equal deleted inserted replaced
433:b142b473f0ee 434:b8bf63962a99
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="x496.html"><LINK
18 REL="NEXT"
19 TITLE="Assembler Modes and Pragmas"
20 HREF="x580.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="x496.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="x580.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="AEN517"
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</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. ENDSECTION is the preferred form.
204 Prior to version 3.0 of LWASM, ENDS could also be used to end a section but
205 as of version 3.0, it is now an alias for ENDSTRUCT instead.</P
206 ></DD
207 ><DT
208 ><CODE
209 CLASS="PARAMETER"
210 >sym</CODE
211 > EXTERN, <CODE
212 CLASS="PARAMETER"
213 >sym</CODE
214 > EXTERNAL, <CODE
215 CLASS="PARAMETER"
216 >sym</CODE
217 > IMPORT</DT
218 ><DD
219 ><P
220 >This directive defines <CODE
221 CLASS="PARAMETER"
222 >sym</CODE
223 > as an external symbol.
224 This directive may occur at any point in the source code. EXTERN definitions
225 are resolved on the first pass so an EXTERN definition anywhere in the
226 source file is valid for the entire file. The use of this directive is
227 optional when the assembler is instructed to assume that all undefined
228 symbols are external. In fact, in that mode, if the symbol is referenced
229 before the EXTERN directive, an error will occur.</P
230 ></DD
231 ><DT
232 ><CODE
233 CLASS="PARAMETER"
234 >sym</CODE
235 > EXPORT, <CODE
236 CLASS="PARAMETER"
237 >sym</CODE
238 > .GLOBL, EXPORT <CODE
239 CLASS="PARAMETER"
240 >sym</CODE
241 >, .GLOBL <CODE
242 CLASS="PARAMETER"
243 >sym</CODE
244 ></DT
245 ><DD
246 ><P
247 >This directive defines <CODE
248 CLASS="PARAMETER"
249 >sym</CODE
250 > as an exported symbol.
251 This directive may occur at any point in the source code, even before the
252 definition of the exported symbol.</P
253 ><P
254 >Note that <CODE
255 CLASS="PARAMETER"
256 >sym</CODE
257 > may appear as the operand or as the
258 statement's symbol. If there is a symbol on the statement, that will
259 take precedence over any operand that is present.</P
260 ></DD
261 ><DT
262 ><CODE
263 CLASS="PARAMETER"
264 >sym</CODE
265 > EXTDEP</DT
266 ><DD
267 ><P
268 >This directive forces an external dependency on
269 <CODE
270 CLASS="PARAMETER"
271 >sym</CODE
272 >, even if it is never referenced anywhere else in
273 this file.</P
274 ></DD
275 ></DL
276 ></DIV
277 ></DIV
278 ><DIV
279 CLASS="NAVFOOTER"
280 ><HR
281 ALIGN="LEFT"
282 WIDTH="100%"><TABLE
283 SUMMARY="Footer navigation table"
284 WIDTH="100%"
285 BORDER="0"
286 CELLPADDING="0"
287 CELLSPACING="0"
288 ><TR
289 ><TD
290 WIDTH="33%"
291 ALIGN="left"
292 VALIGN="top"
293 ><A
294 HREF="x496.html"
295 ACCESSKEY="P"
296 >Prev</A
297 ></TD
298 ><TD
299 WIDTH="34%"
300 ALIGN="center"
301 VALIGN="top"
302 ><A
303 HREF="index.html"
304 ACCESSKEY="H"
305 >Home</A
306 ></TD
307 ><TD
308 WIDTH="33%"
309 ALIGN="right"
310 VALIGN="top"
311 ><A
312 HREF="x580.html"
313 ACCESSKEY="N"
314 >Next</A
315 ></TD
316 ></TR
317 ><TR
318 ><TD
319 WIDTH="33%"
320 ALIGN="left"
321 VALIGN="top"
322 >Structures</TD
323 ><TD
324 WIDTH="34%"
325 ALIGN="center"
326 VALIGN="top"
327 ><A
328 HREF="c43.html"
329 ACCESSKEY="U"
330 >Up</A
331 ></TD
332 ><TD
333 WIDTH="33%"
334 ALIGN="right"
335 VALIGN="top"
336 >Assembler Modes and Pragmas</TD
337 ></TR
338 ></TABLE
339 ></DIV
340 ></BODY
341 ></HTML
342 >