Mercurial > hg-old > index.cgi

comparison doc/manual/x361.html @ 153:ffef3ea07399 2.1 2.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Preparing for release
author lost
date Fri, 30 Jan 2009 04:32:55 +0000
parents
children
comparison
equal deleted inserted replaced
152:6bd4755d224f 153:ffef3ea07399
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="c35.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Macros"
17 HREF="x339.html"><LINK
18 REL="NEXT"
19 TITLE="Assembler Modes and Pragmas"
20 HREF="x407.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="x339.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="x407.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="AEN361"
77 >3.8. 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 ></DT
158 ><DD
159 ><P
160 >Instructs the assembler that the code following this directive is to be
161 considered part of the section <CODE
162 CLASS="PARAMETER"
163 >name</CODE
164 >. A section name
165 may appear multiple times in which case it is as though all the code from
166 all the instances of that section appeared adjacent within the source file.
167 However, <CODE
168 CLASS="PARAMETER"
169 >flags</CODE
170 > may only be specified on the first
171 instance of the section.</P
172 ><P
173 >There is a single flag supported in <CODE
174 CLASS="PARAMETER"
175 >flags</CODE
176 >. The
177 flag <CODE
178 CLASS="PARAMETER"
179 >bss</CODE
180 > will cause the section to be treated as a BSS
181 section and, thus, no code will be included in the object file nor will any
182 bytes be permitted to be output.</P
183 ><P
184 >If assembly is already happening within a section, the section is implicitly
185 ended and the new section started. This is not considered an error although
186 it is recommended that all sections be explicitly closed.</P
187 ></DD
188 ><DT
189 >ENDSECTION, ENDSECT, ENDS</DT
190 ><DD
191 ><P
192 >This directive ends the current section. This puts assembly outside of any
193 sections until the next SECTION directive.</P
194 ></DD
195 ><DT
196 ><CODE
197 CLASS="PARAMETER"
198 >sym</CODE
199 > EXTERN, <CODE
200 CLASS="PARAMETER"
201 >sym</CODE
202 > EXTERNAL, <CODE
203 CLASS="PARAMETER"
204 >sym</CODE
205 > IMPORT</DT
206 ><DD
207 ><P
208 >This directive defines <CODE
209 CLASS="PARAMETER"
210 >sym</CODE
211 > as an external symbol.
212 This directive may occur at any point in the source code. EXTERN definitions
213 are resolved on the first pass so an EXTERN definition anywhere in the
214 source file is valid for the entire file. The use of this directive is
215 optional when the assembler is instructed to assume that all undefined
216 symbols are external. In fact, in that mode, if the symbol is referenced
217 before the EXTERN directive, an error will occur.</P
218 ></DD
219 ><DT
220 ><CODE
221 CLASS="PARAMETER"
222 >sym</CODE
223 > EXPORT</DT
224 ><DD
225 ><P
226 >This directive defines <CODE
227 CLASS="PARAMETER"
228 >sym</CODE
229 > as an exported symbol.
230 This directive may occur at any point in the source code, even before the
231 definition of the exported symbol.</P
232 ></DD
233 ></DL
234 ></DIV
235 ></DIV
236 ><DIV
237 CLASS="NAVFOOTER"
238 ><HR
239 ALIGN="LEFT"
240 WIDTH="100%"><TABLE
241 SUMMARY="Footer navigation table"
242 WIDTH="100%"
243 BORDER="0"
244 CELLPADDING="0"
245 CELLSPACING="0"
246 ><TR
247 ><TD
248 WIDTH="33%"
249 ALIGN="left"
250 VALIGN="top"
251 ><A
252 HREF="x339.html"
253 ACCESSKEY="P"
254 >Prev</A
255 ></TD
256 ><TD
257 WIDTH="34%"
258 ALIGN="center"
259 VALIGN="top"
260 ><A
261 HREF="index.html"
262 ACCESSKEY="H"
263 >Home</A
264 ></TD
265 ><TD
266 WIDTH="33%"
267 ALIGN="right"
268 VALIGN="top"
269 ><A
270 HREF="x407.html"
271 ACCESSKEY="N"
272 >Next</A
273 ></TD
274 ></TR
275 ><TR
276 ><TD
277 WIDTH="33%"
278 ALIGN="left"
279 VALIGN="top"
280 >Macros</TD
281 ><TD
282 WIDTH="34%"
283 ALIGN="center"
284 VALIGN="top"
285 ><A
286 HREF="c35.html"
287 ACCESSKEY="U"
288 >Up</A
289 ></TD
290 ><TD
291 WIDTH="33%"
292 ALIGN="right"
293 VALIGN="top"
294 >Assembler Modes and Pragmas</TD
295 ></TR
296 ></TABLE
297 ></DIV
298 ></BODY
299 ></HTML
300 >