Mercurial > hg > index.cgi
comparison docs/manual/manual.html @ 517:1faf14de9d04
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 > The following options for displaying cycle counts in listings are provided. | 2689 > 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 > LWLINK takes one or more files in supported input formats and links them | 2937 > 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 |