Mercurial > hg > index.cgi

comparison docs/manual/manual.html @ 517:1faf14de9d04

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update manual to correctly reflect forwardrefmax behaviour Add a note to autobranchlength referencing forwardrefmax and also not that forwardrefmax is enabled by default.
author William Astle <lost@l-w.ca>
date Tue, 13 Apr 2021 15:38:12 -0600
parents 52af0aa54fe5
children b530ff19f7c0
comparison
equal deleted inserted replaced
516:c33b4abff860 517:1faf14de9d04
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="#AEN821" 203 HREF="#AEN822"
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="#AEN827" 210 HREF="#AEN828"
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="#AEN830" 217 HREF="#AEN831"
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="#AEN927" 222 HREF="#AEN928"
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="#AEN941" 227 HREF="#AEN942"
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="#AEN1007" 232 HREF="#AEN1008"
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="#AEN1010" 239 HREF="#AEN1011"
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="#AEN1022" 248 HREF="#AEN1023"
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="#AEN1026" 255 HREF="#AEN1027"
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="#AEN1109" 277 HREF="#AEN1110"
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="#AEN1139" 282 HREF="#AEN1140"
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
2474 >Because this pragma leads to source that is incompatible with other 2474 >Because this pragma leads to source that is incompatible with other
2475 assemblers, it is strongly recommended that it be invoked using the PRAGMA 2475 assemblers, it is strongly recommended that it be invoked using the PRAGMA
2476 directive within the source code rather than on the command line or via the 2476 directive within the source code rather than on the command line or via the
2477 *PRAGMA directive. This way, an error will be raised if someone tries to 2477 *PRAGMA directive. This way, an error will be raised if someone tries to
2478 assemble the code under a different assembler.</P 2478 assemble the code under a different assembler.</P
2479 ><P
2480 >Note that if the "forwardrefmax" pragma is ineffect, as is the current
2481 default, this pragma will not behave as expected.</P
2479 ></DD 2482 ></DD
2480 ><DT 2483 ><DT
2481 >nosymbolcase, symbolnocase</DT 2484 >nosymbolcase, symbolnocase</DT
2482 ><DD 2485 ><DD
2483 ><P 2486 ><P
2510 ><DT 2513 ><DT
2511 >forwardrefmax</DT 2514 >forwardrefmax</DT
2512 ><DD 2515 ><DD
2513 ><P 2516 ><P
2514 >This pragma will disable forward reference optimization completely. 2517 >This pragma will disable forward reference optimization completely.
2515 Ordinarily, LWASM will attempt to select the shortest possible addressing 2518 However, many source files, especially
2516 mode for forward references. However, in many source files, especially
2517 those not using the PCR relative addressing modes, this optimization is 2519 those not using the PCR relative addressing modes, this optimization is
2518 pointless since the assembler will almost certainly settle on a 16 bit 2520 pointless since the assembler will almost certainly settle on a 16 bit
2519 offset or address. If all variables in the direct page are defined before 2521 offset or address. If all variables in the direct page are defined before
2520 the main body of the code, the benefit of forward reference optimization 2522 the main body of the code, the benefit of forward reference optimization
2521 almost certainly vanishes completely. However, the cost of doing that 2523 almost certainly vanishes completely. However, the cost of doing that
2522 optimization remains and can result in a very long assembly time.</P 2524 optimization remains and can result in a very long assembly time. Because
2525 of this, "forwardrefmax" has been the default setting since version 4.14 of
2526 LWTOOLS. To turn it off, use "noforwardrefmax".</P
2523 ><P 2527 ><P
2524 >Enabling this pragma will cause all forward references to use the 2528 >Enabling this pragma will cause all forward references to use the
2525 maximum offset or address size, much the same has EDTASM and other pure 2529 maximum offset or address size, much the same has EDTASM and other pure
2526 two pass assemblers do. The side effect is that all line lengths and 2530 two pass assemblers do. The side effect is that all line lengths and
2527 symbol values are fully resolved after the initial parsing pass and the 2531 symbol values are fully resolved after the initial parsing pass and the
2676 ><DIV 2680 ><DIV
2677 CLASS="SECTION" 2681 CLASS="SECTION"
2678 ><HR><H2 2682 ><HR><H2
2679 CLASS="SECTION" 2683 CLASS="SECTION"
2680 ><A 2684 ><A
2681 NAME="AEN821" 2685 NAME="AEN822"
2682 >3.12. Cycle Counts</A 2686 >3.12. Cycle Counts</A
2683 ></H2 2687 ></H2
2684 ><P 2688 ><P
2685 >&#13;The following options for displaying cycle counts in listings are provided. 2689 >&#13;The following options for displaying cycle counts in listings are provided.
2686 These options are enabled from pragmas on the command line or in the 2690 These options are enabled from pragmas on the command line or in the
2715 ></DIV 2719 ></DIV
2716 ><DIV 2720 ><DIV
2717 CLASS="CHAPTER" 2721 CLASS="CHAPTER"
2718 ><HR><H1 2722 ><HR><H1
2719 ><A 2723 ><A
2720 NAME="AEN827" 2724 NAME="AEN828"
2721 ></A 2725 ></A
2722 >Chapter 4. LWLINK</H1 2726 >Chapter 4. LWLINK</H1
2723 ><P 2727 ><P
2724 >The LWTOOLS linker is called LWLINK. This chapter documents the various features 2728 >The LWTOOLS linker is called LWLINK. This chapter documents the various features
2725 of the linker.</P 2729 of the linker.</P
2726 ><DIV 2730 ><DIV
2727 CLASS="SECTION" 2731 CLASS="SECTION"
2728 ><HR><H2 2732 ><HR><H2
2729 CLASS="SECTION" 2733 CLASS="SECTION"
2730 ><A 2734 ><A
2731 NAME="AEN830" 2735 NAME="AEN831"
2732 >4.1. Command Line Options</A 2736 >4.1. Command Line Options</A
2733 ></H2 2737 ></H2
2734 ><P 2738 ><P
2735 >The binary for LWLINK is called "lwlink". Note that the binary is in lower 2739 >The binary for LWLINK is called "lwlink". Note that the binary is in lower
2736 case. lwlink takes the following command line arguments.</P 2740 case. lwlink takes the following command line arguments.</P
2924 ><DIV 2928 ><DIV
2925 CLASS="SECTION" 2929 CLASS="SECTION"
2926 ><HR><H2 2930 ><HR><H2
2927 CLASS="SECTION" 2931 CLASS="SECTION"
2928 ><A 2932 ><A
2929 NAME="AEN927" 2933 NAME="AEN928"
2930 >4.2. Linker Operation</A 2934 >4.2. Linker Operation</A
2931 ></H2 2935 ></H2
2932 ><P 2936 ><P
2933 >&#13;LWLINK takes one or more files in supported input formats and links them 2937 >&#13;LWLINK takes one or more files in supported input formats and links them
2934 into a single binary. Currently supported formats are the LWTOOLS object 2938 into a single binary. Currently supported formats are the LWTOOLS object
2980 ><DIV 2984 ><DIV
2981 CLASS="SECTION" 2985 CLASS="SECTION"
2982 ><HR><H2 2986 ><HR><H2
2983 CLASS="SECTION" 2987 CLASS="SECTION"
2984 ><A 2988 ><A
2985 NAME="AEN941" 2989 NAME="AEN942"
2986 >4.3. Linking Scripts</A 2990 >4.3. Linking Scripts</A
2987 ></H2 2991 ></H2
2988 ><P 2992 ><P
2989 >A linker script is used to instruct the linker about how to assemble the 2993 >A linker script is used to instruct the linker about how to assemble the
2990 various sections into a completed binary. It consists of a series of 2994 various sections into a completed binary. It consists of a series of
3184 ><DIV 3188 ><DIV
3185 CLASS="SECTION" 3189 CLASS="SECTION"
3186 ><HR><H2 3190 ><HR><H2
3187 CLASS="SECTION" 3191 CLASS="SECTION"
3188 ><A 3192 ><A
3189 NAME="AEN1007" 3193 NAME="AEN1008"
3190 >4.4. Format Specific Linking Notes</A 3194 >4.4. Format Specific Linking Notes</A
3191 ></H2 3195 ></H2
3192 ><P 3196 ><P
3193 >Some formats require special information to be able to generate actual 3197 >Some formats require special information to be able to generate actual
3194 binaries. If the specific format you are interested in is not listed in 3198 binaries. If the specific format you are interested in is not listed in
3197 ><DIV 3201 ><DIV
3198 CLASS="SECTION" 3202 CLASS="SECTION"
3199 ><HR><H3 3203 ><HR><H3
3200 CLASS="SECTION" 3204 CLASS="SECTION"
3201 ><A 3205 ><A
3202 NAME="AEN1010" 3206 NAME="AEN1011"
3203 >4.4.1. OS9 Modules</A 3207 >4.4.1. OS9 Modules</A
3204 ></H3 3208 ></H3
3205 ><P 3209 ><P
3206 >OS9 modules need to embed several items into the module header. These 3210 >OS9 modules need to embed several items into the module header. These
3207 items are the type of module, the langauge of the module, the module 3211 items are the type of module, the langauge of the module, the module
3273 ></DIV 3277 ></DIV
3274 ><DIV 3278 ><DIV
3275 CLASS="CHAPTER" 3279 CLASS="CHAPTER"
3276 ><HR><H1 3280 ><HR><H1
3277 ><A 3281 ><A
3278 NAME="AEN1022" 3282 NAME="AEN1023"
3279 ></A 3283 ></A
3280 >Chapter 5. Libraries and LWAR</H1 3284 >Chapter 5. Libraries and LWAR</H1
3281 ><P 3285 ><P
3282 >LWTOOLS also includes a tool for managing libraries. These are analogous to 3286 >LWTOOLS also includes a tool for managing libraries. These are analogous to
3283 the static libraries created with the "ar" tool on POSIX systems. Each library 3287 the static libraries created with the "ar" tool on POSIX systems. Each library
3292 ><DIV 3296 ><DIV
3293 CLASS="SECTION" 3297 CLASS="SECTION"
3294 ><HR><H2 3298 ><HR><H2
3295 CLASS="SECTION" 3299 CLASS="SECTION"
3296 ><A 3300 ><A
3297 NAME="AEN1026" 3301 NAME="AEN1027"
3298 >5.1. Command Line Options</A 3302 >5.1. Command Line Options</A
3299 ></H2 3303 ></H2
3300 ><P 3304 ><P
3301 >The binary for LWAR is called "lwar". Note that the binary is in lower 3305 >The binary for LWAR is called "lwar". Note that the binary is in lower
3302 case. The options lwar understands are listed below. For archive manipulation 3306 case. The options lwar understands are listed below. For archive manipulation
3493 followed by any data required by the term. Then end of the list is flagged 3497 followed by any data required by the term. Then end of the list is flagged
3494 by a NULL expression (only an end of expression term).</P 3498 by a NULL expression (only an end of expression term).</P
3495 ><DIV 3499 ><DIV
3496 CLASS="TABLE" 3500 CLASS="TABLE"
3497 ><A 3501 ><A
3498 NAME="AEN1109" 3502 NAME="AEN1110"
3499 ></A 3503 ></A
3500 ><P 3504 ><P
3501 ><B 3505 ><B
3502 >Table 6-1. Object File Term Types</B 3506 >Table 6-1. Object File Term Types</B
3503 ></P 3507 ></P
3565 allows local symbols that are not exported to have the same names as 3569 allows local symbols that are not exported to have the same names as
3566 exported symbols or external references.</P 3570 exported symbols or external references.</P
3567 ><DIV 3571 ><DIV
3568 CLASS="TABLE" 3572 CLASS="TABLE"
3569 ><A 3573 ><A
3570 NAME="AEN1139" 3574 NAME="AEN1140"
3571 ></A 3575 ></A
3572 ><P 3576 ><P
3573 ><B 3577 ><B
3574 >Table 6-2. Object File Operator Numbers</B 3578 >Table 6-2. Object File Operator Numbers</B
3575 ></P 3579 ></P