Mercurial > hg > index.cgi

comparison docs/manual/manual.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 8c6c3363e18e
children
comparison
equal deleted inserted replaced
564:87f904e2b304 565:fc072f6cde09
151 HREF="#AEN264" 151 HREF="#AEN264"
152 >Data Directives</A 152 >Data Directives</A
153 ></DT 153 ></DT
154 ><DT 154 ><DT
155 >3.6.2. <A 155 >3.6.2. <A
156 HREF="#AEN375" 156 HREF="#AEN381"
157 >Address Definition</A 157 >Address Definition</A
158 ></DT 158 ></DT
159 ><DT 159 ><DT
160 >3.6.3. <A 160 >3.6.3. <A
161 HREF="#AEN426" 161 HREF="#AEN432"
162 >Conditional Assembly</A 162 >Conditional Assembly</A
163 ></DT 163 ></DT
164 ><DT 164 ><DT
165 >3.6.4. <A 165 >3.6.4. <A
166 HREF="#AEN497" 166 HREF="#AEN503"
167 >OS9 Target Directives</A 167 >OS9 Target Directives</A
168 ></DT 168 ></DT
169 ><DT 169 ><DT
170 >3.6.5. <A 170 >3.6.5. <A
171 HREF="#AEN522" 171 HREF="#AEN528"
172 >Miscelaneous Directives</A 172 >Miscelaneous Directives</A
173 ></DT 173 ></DT
174 ></DL 174 ></DL
175 ></DD 175 ></DD
176 ><DT 176 ><DT
177 >3.7. <A 177 >3.7. <A
178 HREF="#AEN562" 178 HREF="#AEN568"
179 >Macros</A 179 >Macros</A
180 ></DT 180 ></DT
181 ><DT 181 ><DT
182 >3.8. <A 182 >3.8. <A
183 HREF="#AEN585" 183 HREF="#AEN591"
184 >Structures</A 184 >Structures</A
185 ></DT 185 ></DT
186 ><DT 186 ><DT
187 >3.9. <A 187 >3.9. <A
188 HREF="#AEN606" 188 HREF="#AEN612"
189 >Object Files and Sections</A 189 >Object Files and Sections</A
190 ></DT 190 ></DT
191 ><DT 191 ><DT
192 >3.10. <A 192 >3.10. <A
193 HREF="#AEN670" 193 HREF="#AEN676"
194 >Assembler Modes and Pragmas</A 194 >Assembler Modes and Pragmas</A
195 ></DT 195 ></DT
196 ><DT 196 ><DT
197 >3.11. <A 197 >3.11. <A
198 HREF="#CONVINST" 198 HREF="#CONVINST"
199 >Convenience Instructions</A 199 >Convenience Instructions</A
200 ></DT 200 ></DT
201 ><DT 201 ><DT
202 >3.12. <A 202 >3.12. <A
203 HREF="#AEN826" 203 HREF="#AEN832"
204 >Cycle Counts</A 204 >Cycle Counts</A
205 ></DT 205 ></DT
206 ></DL 206 ></DL
207 ></DD 207 ></DD
208 ><DT 208 ><DT
209 >4. <A 209 >4. <A
210 HREF="#AEN832" 210 HREF="#AEN838"
211 >LWLINK</A 211 >LWLINK</A
212 ></DT 212 ></DT
213 ><DD 213 ><DD
214 ><DL 214 ><DL
215 ><DT 215 ><DT
216 >4.1. <A 216 >4.1. <A
217 HREF="#AEN835" 217 HREF="#AEN841"
218 >Command Line Options</A 218 >Command Line Options</A
219 ></DT 219 ></DT
220 ><DT 220 ><DT
221 >4.2. <A 221 >4.2. <A
222 HREF="#AEN932" 222 HREF="#AEN938"
223 >Linker Operation</A 223 >Linker Operation</A
224 ></DT 224 ></DT
225 ><DT 225 ><DT
226 >4.3. <A 226 >4.3. <A
227 HREF="#AEN946" 227 HREF="#AEN952"
228 >Linking Scripts</A 228 >Linking Scripts</A
229 ></DT 229 ></DT
230 ><DT 230 ><DT
231 >4.4. <A 231 >4.4. <A
232 HREF="#AEN1013" 232 HREF="#AEN1019"
233 >Format Specific Linking Notes</A 233 >Format Specific Linking Notes</A
234 ></DT 234 ></DT
235 ><DD 235 ><DD
236 ><DL 236 ><DL
237 ><DT 237 ><DT
238 >4.4.1. <A 238 >4.4.1. <A
239 HREF="#AEN1016" 239 HREF="#AEN1022"
240 >OS9 Modules</A 240 >OS9 Modules</A
241 ></DT 241 ></DT
242 ></DL 242 ></DL
243 ></DD 243 ></DD
244 ></DL 244 ></DL
245 ></DD 245 ></DD
246 ><DT 246 ><DT
247 >5. <A 247 >5. <A
248 HREF="#AEN1028" 248 HREF="#AEN1034"
249 >Libraries and LWAR</A 249 >Libraries and LWAR</A
250 ></DT 250 ></DT
251 ><DD 251 ><DD
252 ><DL 252 ><DL
253 ><DT 253 ><DT
254 >5.1. <A 254 >5.1. <A
255 HREF="#AEN1032" 255 HREF="#AEN1038"
256 >Command Line Options</A 256 >Command Line Options</A
257 ></DT 257 ></DT
258 ></DL 258 ></DL
259 ></DD 259 ></DD
260 ><DT 260 ><DT
272 ><B 272 ><B
273 >List of Tables</B 273 >List of Tables</B
274 ></DT 274 ></DT
275 ><DT 275 ><DT
276 >6-1. <A 276 >6-1. <A
277 HREF="#AEN1115" 277 HREF="#AEN1121"
278 >Object File Term Types</A 278 >Object File Term Types</A
279 ></DT 279 ></DT
280 ><DT 280 ><DT
281 >6-2. <A 281 >6-2. <A
282 HREF="#AEN1145" 282 HREF="#AEN1151"
283 >Object File Operator Numbers</A 283 >Object File Operator Numbers</A
284 ></DT 284 ></DT
285 ></DL 285 ></DL
286 ></DIV 286 ></DIV
287 ><DIV 287 ><DIV
1252 ></DD 1252 ></DD
1253 ><DT 1253 ><DT
1254 >INCLUDEBIN <CODE 1254 >INCLUDEBIN <CODE
1255 CLASS="PARAMETER" 1255 CLASS="PARAMETER"
1256 >filename</CODE 1256 >filename</CODE
1257 ></DT 1257 >[,<CODE
1258 CLASS="PARAMETER"
1259 >start</CODE
1260 >[,<CODE
1261 CLASS="PARAMETER"
1262 >length</CODE
1263 >]]</DT
1258 ><DD 1264 ><DD
1259 ><P 1265 ><P
1260 >Treat the contents of <CODE 1266 >Treat the contents of <CODE
1261 CLASS="PARAMETER" 1267 CLASS="PARAMETER"
1262 >filename</CODE 1268 >filename</CODE
1273 searched followed by the search path in the order specified.</P 1279 searched followed by the search path in the order specified.</P
1274 ><P 1280 ><P
1275 > Please note that absolute path detection including drive letters will 1281 > Please note that absolute path detection including drive letters will
1276 not function correctly on Windows platforms. Non-absolute inclusion will 1282 not function correctly on Windows platforms. Non-absolute inclusion will
1277 work, however.</P 1283 work, however.</P
1284 ><P
1285 > The optional <CODE
1286 CLASS="PARAMETER"
1287 >start</CODE
1288 > parameter allows you to set
1289 the byte offset to start reading from the binary file. Positive values are
1290 from the beginning of the file, negative values are from the end of the file.</P
1291 ><P
1292 > The optional <CODE
1293 CLASS="PARAMETER"
1294 >length</CODE
1295 > parameter allows you to set
1296 the number of bytes read from the binary file. If missing, then the file is
1297 read to the end.</P
1278 ></DD 1298 ></DD
1279 ><DT 1299 ><DT
1280 >FILL <CODE 1300 >FILL <CODE
1281 CLASS="PARAMETER" 1301 CLASS="PARAMETER"
1282 >byte</CODE 1302 >byte</CODE
1300 ><DIV 1320 ><DIV
1301 CLASS="SECTION" 1321 CLASS="SECTION"
1302 ><HR><H3 1322 ><HR><H3
1303 CLASS="SECTION" 1323 CLASS="SECTION"
1304 ><A 1324 ><A
1305 NAME="AEN375" 1325 NAME="AEN381"
1306 >3.6.2. Address Definition</A 1326 >3.6.2. Address Definition</A
1307 ></H3 1327 ></H3
1308 ><P 1328 ><P
1309 >The directives in this section all control the addresses of symbols 1329 >The directives in this section all control the addresses of symbols
1310 or the assembly process itself.</P 1330 or the assembly process itself.</P
1446 ><DIV 1466 ><DIV
1447 CLASS="SECTION" 1467 CLASS="SECTION"
1448 ><HR><H3 1468 ><HR><H3
1449 CLASS="SECTION" 1469 CLASS="SECTION"
1450 ><A 1470 ><A
1451 NAME="AEN426" 1471 NAME="AEN432"
1452 >3.6.3. Conditional Assembly</A 1472 >3.6.3. Conditional Assembly</A
1453 ></H3 1473 ></H3
1454 ><P 1474 ><P
1455 >Portions of the source code can be excluded or included based on conditions 1475 >Portions of the source code can be excluded or included based on conditions
1456 known at assembly time. Conditionals can be nested arbitrarily deeply. The 1476 known at assembly time. Conditionals can be nested arbitrarily deeply. The
1621 ><DIV 1641 ><DIV
1622 CLASS="SECTION" 1642 CLASS="SECTION"
1623 ><HR><H3 1643 ><HR><H3
1624 CLASS="SECTION" 1644 CLASS="SECTION"
1625 ><A 1645 ><A
1626 NAME="AEN497" 1646 NAME="AEN503"
1627 >3.6.4. OS9 Target Directives</A 1647 >3.6.4. OS9 Target Directives</A
1628 ></H3 1648 ></H3
1629 ><P 1649 ><P
1630 >This section includes directives that apply solely to the OS9 1650 >This section includes directives that apply solely to the OS9
1631 target.</P 1651 target.</P
1688 ><DIV 1708 ><DIV
1689 CLASS="SECTION" 1709 CLASS="SECTION"
1690 ><HR><H3 1710 ><HR><H3
1691 CLASS="SECTION" 1711 CLASS="SECTION"
1692 ><A 1712 ><A
1693 NAME="AEN522" 1713 NAME="AEN528"
1694 >3.6.5. Miscelaneous Directives</A 1714 >3.6.5. Miscelaneous Directives</A
1695 ></H3 1715 ></H3
1696 ><P 1716 ><P
1697 >This section includes directives that do not fit into the other 1717 >This section includes directives that do not fit into the other
1698 categories.</P 1718 categories.</P
1802 ><DIV 1822 ><DIV
1803 CLASS="SECTION" 1823 CLASS="SECTION"
1804 ><HR><H2 1824 ><HR><H2
1805 CLASS="SECTION" 1825 CLASS="SECTION"
1806 ><A 1826 ><A
1807 NAME="AEN562" 1827 NAME="AEN568"
1808 >3.7. Macros</A 1828 >3.7. Macros</A
1809 ></H2 1829 ></H2
1810 ><P 1830 ><P
1811 >LWASM is a macro assembler. A macro is simply a name that stands in for a 1831 >LWASM is a macro assembler. A macro is simply a name that stands in for a
1812 series of instructions. Once a macro is defined, it is used like any other 1832 series of instructions. Once a macro is defined, it is used like any other
1901 ><DIV 1921 ><DIV
1902 CLASS="SECTION" 1922 CLASS="SECTION"
1903 ><HR><H2 1923 ><HR><H2
1904 CLASS="SECTION" 1924 CLASS="SECTION"
1905 ><A 1925 ><A
1906 NAME="AEN585" 1926 NAME="AEN591"
1907 >3.8. Structures</A 1927 >3.8. Structures</A
1908 ></H2 1928 ></H2
1909 ><P 1929 ><P
1910 >&#13;Structures are used to group related data in a fixed structure. A structure 1930 >&#13;Structures are used to group related data in a fixed structure. A structure
1911 consists a number of fields, defined in sequential order and which take up 1931 consists a number of fields, defined in sequential order and which take up
1994 ><DIV 2014 ><DIV
1995 CLASS="SECTION" 2015 CLASS="SECTION"
1996 ><HR><H2 2016 ><HR><H2
1997 CLASS="SECTION" 2017 CLASS="SECTION"
1998 ><A 2018 ><A
1999 NAME="AEN606" 2019 NAME="AEN612"
2000 >3.9. Object Files and Sections</A 2020 >3.9. Object Files and Sections</A
2001 ></H2 2021 ></H2
2002 ><P 2022 ><P
2003 >The object file target is very useful for large project because it allows 2023 >The object file target is very useful for large project because it allows
2004 multiple files to be assembled independently and then linked into the final 2024 multiple files to be assembled independently and then linked into the final
2211 ><DIV 2231 ><DIV
2212 CLASS="SECTION" 2232 CLASS="SECTION"
2213 ><HR><H2 2233 ><HR><H2
2214 CLASS="SECTION" 2234 CLASS="SECTION"
2215 ><A 2235 ><A
2216 NAME="AEN670" 2236 NAME="AEN676"
2217 >3.10. Assembler Modes and Pragmas</A 2237 >3.10. Assembler Modes and Pragmas</A
2218 ></H2 2238 ></H2
2219 ><P 2239 ><P
2220 >There are a number of options that affect the way assembly is performed. 2240 >There are a number of options that affect the way assembly is performed.
2221 Some of these options can only be specified on the command line because 2241 Some of these options can only be specified on the command line because
2692 ><DIV 2712 ><DIV
2693 CLASS="SECTION" 2713 CLASS="SECTION"
2694 ><HR><H2 2714 ><HR><H2
2695 CLASS="SECTION" 2715 CLASS="SECTION"
2696 ><A 2716 ><A
2697 NAME="AEN826" 2717 NAME="AEN832"
2698 >3.12. Cycle Counts</A 2718 >3.12. Cycle Counts</A
2699 ></H2 2719 ></H2
2700 ><P 2720 ><P
2701 >&#13;The following options for displaying cycle counts in listings are provided. 2721 >&#13;The following options for displaying cycle counts in listings are provided.
2702 These options are enabled from pragmas on the command line or in the 2722 These options are enabled from pragmas on the command line or in the
2731 ></DIV 2751 ></DIV
2732 ><DIV 2752 ><DIV
2733 CLASS="CHAPTER" 2753 CLASS="CHAPTER"
2734 ><HR><H1 2754 ><HR><H1
2735 ><A 2755 ><A
2736 NAME="AEN832" 2756 NAME="AEN838"
2737 ></A 2757 ></A
2738 >Chapter 4. LWLINK</H1 2758 >Chapter 4. LWLINK</H1
2739 ><P 2759 ><P
2740 >The LWTOOLS linker is called LWLINK. This chapter documents the various features 2760 >The LWTOOLS linker is called LWLINK. This chapter documents the various features
2741 of the linker.</P 2761 of the linker.</P
2742 ><DIV 2762 ><DIV
2743 CLASS="SECTION" 2763 CLASS="SECTION"
2744 ><HR><H2 2764 ><HR><H2
2745 CLASS="SECTION" 2765 CLASS="SECTION"
2746 ><A 2766 ><A
2747 NAME="AEN835" 2767 NAME="AEN841"
2748 >4.1. Command Line Options</A 2768 >4.1. Command Line Options</A
2749 ></H2 2769 ></H2
2750 ><P 2770 ><P
2751 >The binary for LWLINK is called "lwlink". Note that the binary is in lower 2771 >The binary for LWLINK is called "lwlink". Note that the binary is in lower
2752 case. lwlink takes the following command line arguments.</P 2772 case. lwlink takes the following command line arguments.</P
2940 ><DIV 2960 ><DIV
2941 CLASS="SECTION" 2961 CLASS="SECTION"
2942 ><HR><H2 2962 ><HR><H2
2943 CLASS="SECTION" 2963 CLASS="SECTION"
2944 ><A 2964 ><A
2945 NAME="AEN932" 2965 NAME="AEN938"
2946 >4.2. Linker Operation</A 2966 >4.2. Linker Operation</A
2947 ></H2 2967 ></H2
2948 ><P 2968 ><P
2949 >&#13;LWLINK takes one or more files in supported input formats and links them 2969 >&#13;LWLINK takes one or more files in supported input formats and links them
2950 into a single binary. Currently supported formats are the LWTOOLS object 2970 into a single binary. Currently supported formats are the LWTOOLS object
2996 ><DIV 3016 ><DIV
2997 CLASS="SECTION" 3017 CLASS="SECTION"
2998 ><HR><H2 3018 ><HR><H2
2999 CLASS="SECTION" 3019 CLASS="SECTION"
3000 ><A 3020 ><A
3001 NAME="AEN946" 3021 NAME="AEN952"
3002 >4.3. Linking Scripts</A 3022 >4.3. Linking Scripts</A
3003 ></H2 3023 ></H2
3004 ><P 3024 ><P
3005 >A linker script is used to instruct the linker about how to assemble the 3025 >A linker script is used to instruct the linker about how to assemble the
3006 various sections into a completed binary. It consists of a series of 3026 various sections into a completed binary. It consists of a series of
3203 ><DIV 3223 ><DIV
3204 CLASS="SECTION" 3224 CLASS="SECTION"
3205 ><HR><H2 3225 ><HR><H2
3206 CLASS="SECTION" 3226 CLASS="SECTION"
3207 ><A 3227 ><A
3208 NAME="AEN1013" 3228 NAME="AEN1019"
3209 >4.4. Format Specific Linking Notes</A 3229 >4.4. Format Specific Linking Notes</A
3210 ></H2 3230 ></H2
3211 ><P 3231 ><P
3212 >Some formats require special information to be able to generate actual 3232 >Some formats require special information to be able to generate actual
3213 binaries. If the specific format you are interested in is not listed in 3233 binaries. If the specific format you are interested in is not listed in
3216 ><DIV 3236 ><DIV
3217 CLASS="SECTION" 3237 CLASS="SECTION"
3218 ><HR><H3 3238 ><HR><H3
3219 CLASS="SECTION" 3239 CLASS="SECTION"
3220 ><A 3240 ><A
3221 NAME="AEN1016" 3241 NAME="AEN1022"
3222 >4.4.1. OS9 Modules</A 3242 >4.4.1. OS9 Modules</A
3223 ></H3 3243 ></H3
3224 ><P 3244 ><P
3225 >OS9 modules need to embed several items into the module header. These 3245 >OS9 modules need to embed several items into the module header. These
3226 items are the type of module, the langauge of the module, the module 3246 items are the type of module, the langauge of the module, the module
3292 ></DIV 3312 ></DIV
3293 ><DIV 3313 ><DIV
3294 CLASS="CHAPTER" 3314 CLASS="CHAPTER"
3295 ><HR><H1 3315 ><HR><H1
3296 ><A 3316 ><A
3297 NAME="AEN1028" 3317 NAME="AEN1034"
3298 ></A 3318 ></A
3299 >Chapter 5. Libraries and LWAR</H1 3319 >Chapter 5. Libraries and LWAR</H1
3300 ><P 3320 ><P
3301 >LWTOOLS also includes a tool for managing libraries. These are analogous to 3321 >LWTOOLS also includes a tool for managing libraries. These are analogous to
3302 the static libraries created with the "ar" tool on POSIX systems. Each library 3322 the static libraries created with the "ar" tool on POSIX systems. Each library
3311 ><DIV 3331 ><DIV
3312 CLASS="SECTION" 3332 CLASS="SECTION"
3313 ><HR><H2 3333 ><HR><H2
3314 CLASS="SECTION" 3334 CLASS="SECTION"
3315 ><A 3335 ><A
3316 NAME="AEN1032" 3336 NAME="AEN1038"
3317 >5.1. Command Line Options</A 3337 >5.1. Command Line Options</A
3318 ></H2 3338 ></H2
3319 ><P 3339 ><P
3320 >The binary for LWAR is called "lwar". Note that the binary is in lower 3340 >The binary for LWAR is called "lwar". Note that the binary is in lower
3321 case. The options lwar understands are listed below. For archive manipulation 3341 case. The options lwar understands are listed below. For archive manipulation
3512 followed by any data required by the term. Then end of the list is flagged 3532 followed by any data required by the term. Then end of the list is flagged
3513 by a NULL expression (only an end of expression term).</P 3533 by a NULL expression (only an end of expression term).</P
3514 ><DIV 3534 ><DIV
3515 CLASS="TABLE" 3535 CLASS="TABLE"
3516 ><A 3536 ><A
3517 NAME="AEN1115" 3537 NAME="AEN1121"
3518 ></A 3538 ></A
3519 ><P 3539 ><P
3520 ><B 3540 ><B
3521 >Table 6-1. Object File Term Types</B 3541 >Table 6-1. Object File Term Types</B
3522 ></P 3542 ></P
3584 allows local symbols that are not exported to have the same names as 3604 allows local symbols that are not exported to have the same names as
3585 exported symbols or external references.</P 3605 exported symbols or external references.</P
3586 ><DIV 3606 ><DIV
3587 CLASS="TABLE" 3607 CLASS="TABLE"
3588 ><A 3608 ><A
3589 NAME="AEN1145" 3609 NAME="AEN1151"
3590 ></A 3610 ></A
3591 ><P 3611 ><P
3592 ><B 3612 ><B
3593 >Table 6-2. Object File Operator Numbers</B 3613 >Table 6-2. Object File Operator Numbers</B
3594 ></P 3614 ></P