Mercurial > hg > index.cgi

comparison docs/manual/x1019.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 >Format Specific Linking Notes</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="LWLINK"
14 HREF="c838.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Linking Scripts"
17 HREF="x952.html"><LINK
18 REL="NEXT"
19 TITLE="Libraries and LWAR"
20 HREF="c1034.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="x952.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 4. LWLINK</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="c1034.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="AEN1019"
77 >4.4. Format Specific Linking Notes</A
78 ></H1
79 ><P
80 >Some formats require special information to be able to generate actual
81 binaries. If the specific format you are interested in is not listed in
82 this section, then there is nothing special you need to know about to create
83 a final binary.</P
84 ><DIV
85 CLASS="SECTION"
86 ><H2
87 CLASS="SECTION"
88 ><A
89 NAME="AEN1022"
90 >4.4.1. OS9 Modules</A
91 ></H2
92 ><P
93 >OS9 modules need to embed several items into the module header. These
94 items are the type of module, the langauge of the module, the module
95 attributes, the module revision number, the data size (bss), and the
96 execution offset. These are all either calculated or default to reasonable
97 values.</P
98 ><P
99 >The data size is calcuated as the sum of all sections named "bss" or
100 ".bss" in all object files that are linked together.</P
101 ><P
102 >The execution offset is calculated from the address of the special
103 symbol "__start" which must be an exported (external) symbol in one of the
104 objects to be linked.</P
105 ><P
106 >The type defaults to "Prgrm" or "Program module". The language
107 defaults to "Objct" or "6809 object code". Attributes default to enabling
108 the re-entrant flag. And finally, the revision defaults to zero.</P
109 ><P
110 >The embedded module name is the output filename. If the output
111 filename includes more than just the filename, this will probably not be
112 what you want.</P
113 ><P
114 >The type, language, attributes, revision, and module name can all be
115 overridden by providing a special section in exactly one of the object files
116 to be linked. This section is called "__os9" (note the two underscores).
117 To override the type, language, attributes, or revision values, define a
118 non-exported symbol in this section called "type", "lang", "attr", or "rev"
119 respectively. Any other symbols defined are ignored. To override the
120 module name, include as the only actual code in the section a NUL terminated
121 string (the FCN directive is useful for this). If there is no code in the
122 section or it beings with a NUL, the default name will be used. Any of the
123 preceeding that are not defined in the special section will retain their
124 default values.</P
125 ><P
126 >The built-in link script for OS9 modules will place the following
127 sections, in order, in the module: "code", ".text", "data", ".data". It
128 will merge all sections with the name "bss" or ".bss" into the "data"
129 section. All other section names are ignored. What this means is that you
130 must define your data variables in the a section called "bss" or ".bss" even
131 though you will be refencing them all as offsets from U. This does have the
132 unpleasant side effect that all BSS references will end up being 16 bit
133 offsets because the assembler cannot know what the offset will be once the
134 linker is finished its work. Thus, if the tightest possible code is
135 required, having LWASM directly output the module is a better choice.</P
136 ><P
137 >While the built-in link script is probably sufficient for most
138 purposes, you can provide your own script. If you provide a custom link
139 script, you must start your code and data sections at location 000D to
140 accommodate the module header. Otherwise, you will have an incorrect
141 location for the execution offset. You must use the ENTRY directive in the
142 script to define the entry point for the module.</P
143 ><P
144 >It should also be obvious from the above that you cannot mix the bss
145 (rmb) definitions with the module code when linking separately. Those
146 familiar with typical module creation will probably find this an unpleasant
147 difference but it is unavoidable.</P
148 ><P
149 >It should also be noted that direct page references should also be
150 avoided because you cannot know ahead of time whether the linker is going to
151 end up putting a particular variable in the first 256 bytes of the module's
152 data space. If, however, you know for certain you will have less than 256
153 bytes of defined data space across all of the object files that will be
154 linked, you can instead use forced DP addressing for your data addresses
155 instead of the ,u notation. When linking with 3rd party libraries, this
156 practice should be avoided. Also, when creating libraries, always use the
157 offset from U technique.</P
158 ></DIV
159 ></DIV
160 ><DIV
161 CLASS="NAVFOOTER"
162 ><HR
163 ALIGN="LEFT"
164 WIDTH="100%"><TABLE
165 SUMMARY="Footer navigation table"
166 WIDTH="100%"
167 BORDER="0"
168 CELLPADDING="0"
169 CELLSPACING="0"
170 ><TR
171 ><TD
172 WIDTH="33%"
173 ALIGN="left"
174 VALIGN="top"
175 ><A
176 HREF="x952.html"
177 ACCESSKEY="P"
178 >Prev</A
179 ></TD
180 ><TD
181 WIDTH="34%"
182 ALIGN="center"
183 VALIGN="top"
184 ><A
185 HREF="index.html"
186 ACCESSKEY="H"
187 >Home</A
188 ></TD
189 ><TD
190 WIDTH="33%"
191 ALIGN="right"
192 VALIGN="top"
193 ><A
194 HREF="c1034.html"
195 ACCESSKEY="N"
196 >Next</A
197 ></TD
198 ></TR
199 ><TR
200 ><TD
201 WIDTH="33%"
202 ALIGN="left"
203 VALIGN="top"
204 >Linking Scripts</TD
205 ><TD
206 WIDTH="34%"
207 ALIGN="center"
208 VALIGN="top"
209 ><A
210 HREF="c838.html"
211 ACCESSKEY="U"
212 >Up</A
213 ></TD
214 ><TD
215 WIDTH="33%"
216 ALIGN="right"
217 VALIGN="top"
218 >Libraries and LWAR</TD
219 ></TR
220 ></TABLE
221 ></DIV
222 ></BODY
223 ></HTML
224 >