Mercurial > hg > index.cgi

comparison docs/manual/x612.html @ 565:fc072f6cde09

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update documentation to reflect includebin offset/length feature
author William Astle <lost@l-w.ca>
date Thu, 21 Dec 2023 22:16:12 -0700
parents
children
comparison
equal deleted inserted replaced
564:87f904e2b304 565:fc072f6cde09
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="c62.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Structures"
17 HREF="x591.html"><LINK
18 REL="NEXT"
19 TITLE="Assembler Modes and Pragmas"
20 HREF="x676.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="x591.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="x676.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="AEN612"
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 ><CODE
177 CLASS="PARAMETER"
178 >flags</CODE
179 > is a comma separated list of flags. If a
180 flag is "bss", the section will be treated as a BSS section and no
181 statements that generate output are permitted.</P
182 ><P
183 >If the flag is "constant",
184 the same restrictions apply as for BSS sections. Additionally, all symbols
185 defined in a constant section define absolute values and will not be
186 adjusted by the linker at link time. Constant sections cannot define
187 complex expressions for symbols; the value must be fully defined at assembly
188 time. Additionally, multiple instances of a constant section do not
189 coalesce into a single addressing unit; each instance starts again at offset
190 0.</P
191 ><P
192 >If the section name is "bss" or ".bss" in any combination of upper and
193 lower case, the section is assumed to be a BSS section. In that case,
194 the flag <CODE
195 CLASS="PARAMETER"
196 >!bss</CODE
197 > can be used to override this assumption.</P
198 ><P
199 > If the section name is "_constants" or "_constant", in any
200 combination of upper and lower case, the section is assumed to be a constant
201 section. This assumption can be overridden with the "!constant"
202 flag.</P
203 ><P
204 >If assembly is already happening within a section, the section is implicitly
205 ended and the new section started. This is not considered an error although
206 it is recommended that all sections be explicitly closed.</P
207 ></DD
208 ><DT
209 >ENDSECTION, ENDSECT</DT
210 ><DD
211 ><P
212 >This directive ends the current section. This puts assembly outside of any
213 sections until the next SECTION directive. ENDSECTION is the preferred form.
214 Prior to version 3.0 of LWASM, ENDS could also be used to end a section but
215 as of version 3.0, it is now an alias for ENDSTRUCT instead.</P
216 ></DD
217 ><DT
218 ><CODE
219 CLASS="PARAMETER"
220 >sym</CODE
221 > EXTERN, <CODE
222 CLASS="PARAMETER"
223 >sym</CODE
224 > EXTERNAL, <CODE
225 CLASS="PARAMETER"
226 >sym</CODE
227 > IMPORT</DT
228 ><DD
229 ><P
230 >This directive defines <CODE
231 CLASS="PARAMETER"
232 >sym</CODE
233 > as an external symbol.
234 This directive may occur at any point in the source code. EXTERN definitions
235 are resolved on the first pass so an EXTERN definition anywhere in the
236 source file is valid for the entire file. The use of this directive is
237 optional when the assembler is instructed to assume that all undefined
238 symbols are external. In fact, in that mode, if the symbol is referenced
239 before the EXTERN directive, an error will occur.</P
240 ></DD
241 ><DT
242 ><CODE
243 CLASS="PARAMETER"
244 >sym</CODE
245 > EXPORT, <CODE
246 CLASS="PARAMETER"
247 >sym</CODE
248 > .GLOBL, EXPORT <CODE
249 CLASS="PARAMETER"
250 >sym</CODE
251 >, .GLOBL <CODE
252 CLASS="PARAMETER"
253 >sym</CODE
254 ></DT
255 ><DD
256 ><P
257 >This directive defines <CODE
258 CLASS="PARAMETER"
259 >sym</CODE
260 > as an exported symbol.
261 This directive may occur at any point in the source code, even before the
262 definition of the exported symbol.</P
263 ><P
264 >Note that <CODE
265 CLASS="PARAMETER"
266 >sym</CODE
267 > may appear as the operand or as the
268 statement's symbol. If there is a symbol on the statement, that will
269 take precedence over any operand that is present.</P
270 ></DD
271 ><DT
272 ><CODE
273 CLASS="PARAMETER"
274 >sym</CODE
275 > EXTDEP</DT
276 ><DD
277 ><P
278 >This directive forces an external dependency on
279 <CODE
280 CLASS="PARAMETER"
281 >sym</CODE
282 >, even if it is never referenced anywhere else in
283 this file.</P
284 ></DD
285 ></DL
286 ></DIV
287 ></DIV
288 ><DIV
289 CLASS="NAVFOOTER"
290 ><HR
291 ALIGN="LEFT"
292 WIDTH="100%"><TABLE
293 SUMMARY="Footer navigation table"
294 WIDTH="100%"
295 BORDER="0"
296 CELLPADDING="0"
297 CELLSPACING="0"
298 ><TR
299 ><TD
300 WIDTH="33%"
301 ALIGN="left"
302 VALIGN="top"
303 ><A
304 HREF="x591.html"
305 ACCESSKEY="P"
306 >Prev</A
307 ></TD
308 ><TD
309 WIDTH="34%"
310 ALIGN="center"
311 VALIGN="top"
312 ><A
313 HREF="index.html"
314 ACCESSKEY="H"
315 >Home</A
316 ></TD
317 ><TD
318 WIDTH="33%"
319 ALIGN="right"
320 VALIGN="top"
321 ><A
322 HREF="x676.html"
323 ACCESSKEY="N"
324 >Next</A
325 ></TD
326 ></TR
327 ><TR
328 ><TD
329 WIDTH="33%"
330 ALIGN="left"
331 VALIGN="top"
332 >Structures</TD
333 ><TD
334 WIDTH="34%"
335 ALIGN="center"
336 VALIGN="top"
337 ><A
338 HREF="c62.html"
339 ACCESSKEY="U"
340 >Up</A
341 ></TD
342 ><TD
343 WIDTH="33%"
344 ALIGN="right"
345 VALIGN="top"
346 >Assembler Modes and Pragmas</TD
347 ></TR
348 ></TABLE
349 ></DIV
350 ></BODY
351 ></HTML
352 >