Mercurial > hg > index.cgi
comparison docs/manual/manual.html @ 347:330a66a0f45a
Document the forwardrefmax pragma
Since the forwardrefmax is useful for combatting huge assembly times in many
sources, actually document it so people can find it.
author | William Astle <lost@l-w.ca> |
---|---|
date | Thu, 09 Apr 2015 12:51:02 -0600 |
parents | e95f07cbce4e |
children | 379ef4e08dd2 |
comparison
equal
deleted
inserted
replaced
346:9e35f7a1fca1 | 347:330a66a0f45a |
---|---|
195 ></DT | 195 ></DT |
196 ></DL | 196 ></DL |
197 ></DD | 197 ></DD |
198 ><DT | 198 ><DT |
199 >4. <A | 199 >4. <A |
200 HREF="#AEN727" | 200 HREF="#AEN734" |
201 >LWLINK</A | 201 >LWLINK</A |
202 ></DT | 202 ></DT |
203 ><DD | 203 ><DD |
204 ><DL | 204 ><DL |
205 ><DT | 205 ><DT |
206 >4.1. <A | 206 >4.1. <A |
207 HREF="#AEN730" | 207 HREF="#AEN737" |
208 >Command Line Options</A | 208 >Command Line Options</A |
209 ></DT | 209 ></DT |
210 ><DT | 210 ><DT |
211 >4.2. <A | 211 >4.2. <A |
212 HREF="#AEN827" | 212 HREF="#AEN834" |
213 >Linker Operation</A | 213 >Linker Operation</A |
214 ></DT | 214 ></DT |
215 ><DT | 215 ><DT |
216 >4.3. <A | 216 >4.3. <A |
217 HREF="#AEN841" | 217 HREF="#AEN848" |
218 >Linking Scripts</A | 218 >Linking Scripts</A |
219 ></DT | 219 ></DT |
220 ><DT | 220 ><DT |
221 >4.4. <A | 221 >4.4. <A |
222 HREF="#AEN907" | 222 HREF="#AEN914" |
223 >Format Specific Linking Notes</A | 223 >Format Specific Linking Notes</A |
224 ></DT | 224 ></DT |
225 ><DD | 225 ><DD |
226 ><DL | 226 ><DL |
227 ><DT | 227 ><DT |
228 >4.4.1. <A | 228 >4.4.1. <A |
229 HREF="#AEN910" | 229 HREF="#AEN917" |
230 >OS9 Modules</A | 230 >OS9 Modules</A |
231 ></DT | 231 ></DT |
232 ></DL | 232 ></DL |
233 ></DD | 233 ></DD |
234 ></DL | 234 ></DL |
235 ></DD | 235 ></DD |
236 ><DT | 236 ><DT |
237 >5. <A | 237 >5. <A |
238 HREF="#AEN922" | 238 HREF="#AEN929" |
239 >Libraries and LWAR</A | 239 >Libraries and LWAR</A |
240 ></DT | 240 ></DT |
241 ><DD | 241 ><DD |
242 ><DL | 242 ><DL |
243 ><DT | 243 ><DT |
244 >5.1. <A | 244 >5.1. <A |
245 HREF="#AEN926" | 245 HREF="#AEN933" |
246 >Command Line Options</A | 246 >Command Line Options</A |
247 ></DT | 247 ></DT |
248 ></DL | 248 ></DL |
249 ></DD | 249 ></DD |
250 ><DT | 250 ><DT |
262 ><B | 262 ><B |
263 >List of Tables</B | 263 >List of Tables</B |
264 ></DT | 264 ></DT |
265 ><DT | 265 ><DT |
266 >6-1. <A | 266 >6-1. <A |
267 HREF="#AEN1009" | 267 HREF="#AEN1016" |
268 >Object File Term Types</A | 268 >Object File Term Types</A |
269 ></DT | 269 ></DT |
270 ><DT | 270 ><DT |
271 >6-2. <A | 271 >6-2. <A |
272 HREF="#AEN1039" | 272 HREF="#AEN1046" |
273 >Object File Operator Numbers</A | 273 >Object File Operator Numbers</A |
274 ></DT | 274 ></DT |
275 ></DL | 275 ></DL |
276 ></DIV | 276 ></DIV |
277 ><DIV | 277 ><DIV |
2377 ><P | 2377 ><P |
2378 >It is important to note that if a symbol is defined but it does not | 2378 >It is important to note that if a symbol is defined but it does not |
2379 yet evaluate to a constant value at the point where the conditional appears, | 2379 yet evaluate to a constant value at the point where the conditional appears, |
2380 the assembler will still complain about a non constant condition.</P | 2380 the assembler will still complain about a non constant condition.</P |
2381 ></DD | 2381 ></DD |
2382 ><DT | |
2383 >forwardrefmax</DT | |
2384 ><DD | |
2385 ><P | |
2386 >This pragma will disable forward reference optimization completely. | |
2387 Ordinarily, LWASM will attempt to select the shortest possible addressing | |
2388 mode for forward references. However, in many source files, especially | |
2389 those not using the PCR relative addressing modes, this optimization is | |
2390 pointless since the assembler will almost certainly settle on a 16 bit | |
2391 offset or address. If all variables in the direct page are defined before | |
2392 the main body of the code, the benefit of forward reference optimization | |
2393 almost certainly vanishes completely. However, the cost of doing that | |
2394 optimization remains and can result in a very long assembly time.</P | |
2395 ><P | |
2396 >Enabling this pragma will cause all forward references to use the | |
2397 maximum offset or address size, much the same has EDTASM and other pure | |
2398 two pass assemblers do. The side effect is that all line lengths and | |
2399 symbol values are fully resolved after the initial parsing pass and the | |
2400 amount of work to resolve everything becomes almost nil.</P | |
2401 ><P | |
2402 >While this pragma can be applied selectively to sections of source | |
2403 code (use *PRAGMA if doing so and compatibility with other assemblers | |
2404 is desired), it is likely more useful when provided as a command line | |
2405 pragma.</P | |
2406 ><P | |
2407 >It should be noted that the presence or absence of this pragma | |
2408 will not change the correctness of the generated code unless cycle counts | |
2409 or byte counts are critical (which they usually are not). It also will | |
2410 not override the operand size override prefixes (< and >). It only | |
2411 applies when the assembler is left to guess what the operand size is.</P | |
2412 ></DD | |
2382 ></DL | 2413 ></DL |
2383 ></DIV | 2414 ></DIV |
2384 ><P | 2415 ><P |
2385 >As a convenience, each input file has a pragma state stack. This | 2416 >As a convenience, each input file has a pragma state stack. This |
2386 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a | 2417 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a |
2401 ></DIV | 2432 ></DIV |
2402 ><DIV | 2433 ><DIV |
2403 CLASS="CHAPTER" | 2434 CLASS="CHAPTER" |
2404 ><HR><H1 | 2435 ><HR><H1 |
2405 ><A | 2436 ><A |
2406 NAME="AEN727" | 2437 NAME="AEN734" |
2407 ></A | 2438 ></A |
2408 >Chapter 4. LWLINK</H1 | 2439 >Chapter 4. LWLINK</H1 |
2409 ><P | 2440 ><P |
2410 >The LWTOOLS linker is called LWLINK. This chapter documents the various features | 2441 >The LWTOOLS linker is called LWLINK. This chapter documents the various features |
2411 of the linker.</P | 2442 of the linker.</P |
2412 ><DIV | 2443 ><DIV |
2413 CLASS="SECTION" | 2444 CLASS="SECTION" |
2414 ><HR><H2 | 2445 ><HR><H2 |
2415 CLASS="SECTION" | 2446 CLASS="SECTION" |
2416 ><A | 2447 ><A |
2417 NAME="AEN730" | 2448 NAME="AEN737" |
2418 >4.1. Command Line Options</A | 2449 >4.1. Command Line Options</A |
2419 ></H2 | 2450 ></H2 |
2420 ><P | 2451 ><P |
2421 >The binary for LWLINK is called "lwlink". Note that the binary is in lower | 2452 >The binary for LWLINK is called "lwlink". Note that the binary is in lower |
2422 case. lwlink takes the following command line arguments.</P | 2453 case. lwlink takes the following command line arguments.</P |
2609 ><DIV | 2640 ><DIV |
2610 CLASS="SECTION" | 2641 CLASS="SECTION" |
2611 ><HR><H2 | 2642 ><HR><H2 |
2612 CLASS="SECTION" | 2643 CLASS="SECTION" |
2613 ><A | 2644 ><A |
2614 NAME="AEN827" | 2645 NAME="AEN834" |
2615 >4.2. Linker Operation</A | 2646 >4.2. Linker Operation</A |
2616 ></H2 | 2647 ></H2 |
2617 ><P | 2648 ><P |
2618 > LWLINK takes one or more files in supported input formats and links them | 2649 > LWLINK takes one or more files in supported input formats and links them |
2619 into a single binary. Currently supported formats are the LWTOOLS object | 2650 into a single binary. Currently supported formats are the LWTOOLS object |
2665 ><DIV | 2696 ><DIV |
2666 CLASS="SECTION" | 2697 CLASS="SECTION" |
2667 ><HR><H2 | 2698 ><HR><H2 |
2668 CLASS="SECTION" | 2699 CLASS="SECTION" |
2669 ><A | 2700 ><A |
2670 NAME="AEN841" | 2701 NAME="AEN848" |
2671 >4.3. Linking Scripts</A | 2702 >4.3. Linking Scripts</A |
2672 ></H2 | 2703 ></H2 |
2673 ><P | 2704 ><P |
2674 >A linker script is used to instruct the linker about how to assemble the | 2705 >A linker script is used to instruct the linker about how to assemble the |
2675 various sections into a completed binary. It consists of a series of | 2706 various sections into a completed binary. It consists of a series of |
2869 ><DIV | 2900 ><DIV |
2870 CLASS="SECTION" | 2901 CLASS="SECTION" |
2871 ><HR><H2 | 2902 ><HR><H2 |
2872 CLASS="SECTION" | 2903 CLASS="SECTION" |
2873 ><A | 2904 ><A |
2874 NAME="AEN907" | 2905 NAME="AEN914" |
2875 >4.4. Format Specific Linking Notes</A | 2906 >4.4. Format Specific Linking Notes</A |
2876 ></H2 | 2907 ></H2 |
2877 ><P | 2908 ><P |
2878 >Some formats require special information to be able to generate actual | 2909 >Some formats require special information to be able to generate actual |
2879 binaries. If the specific format you are interested in is not listed in | 2910 binaries. If the specific format you are interested in is not listed in |
2882 ><DIV | 2913 ><DIV |
2883 CLASS="SECTION" | 2914 CLASS="SECTION" |
2884 ><HR><H3 | 2915 ><HR><H3 |
2885 CLASS="SECTION" | 2916 CLASS="SECTION" |
2886 ><A | 2917 ><A |
2887 NAME="AEN910" | 2918 NAME="AEN917" |
2888 >4.4.1. OS9 Modules</A | 2919 >4.4.1. OS9 Modules</A |
2889 ></H3 | 2920 ></H3 |
2890 ><P | 2921 ><P |
2891 >OS9 modules need to embed several items into the module header. These | 2922 >OS9 modules need to embed several items into the module header. These |
2892 items are the type of module, the langauge of the module, the module | 2923 items are the type of module, the langauge of the module, the module |
2958 ></DIV | 2989 ></DIV |
2959 ><DIV | 2990 ><DIV |
2960 CLASS="CHAPTER" | 2991 CLASS="CHAPTER" |
2961 ><HR><H1 | 2992 ><HR><H1 |
2962 ><A | 2993 ><A |
2963 NAME="AEN922" | 2994 NAME="AEN929" |
2964 ></A | 2995 ></A |
2965 >Chapter 5. Libraries and LWAR</H1 | 2996 >Chapter 5. Libraries and LWAR</H1 |
2966 ><P | 2997 ><P |
2967 >LWTOOLS also includes a tool for managing libraries. These are analogous to | 2998 >LWTOOLS also includes a tool for managing libraries. These are analogous to |
2968 the static libraries created with the "ar" tool on POSIX systems. Each library | 2999 the static libraries created with the "ar" tool on POSIX systems. Each library |
2977 ><DIV | 3008 ><DIV |
2978 CLASS="SECTION" | 3009 CLASS="SECTION" |
2979 ><HR><H2 | 3010 ><HR><H2 |
2980 CLASS="SECTION" | 3011 CLASS="SECTION" |
2981 ><A | 3012 ><A |
2982 NAME="AEN926" | 3013 NAME="AEN933" |
2983 >5.1. Command Line Options</A | 3014 >5.1. Command Line Options</A |
2984 ></H2 | 3015 ></H2 |
2985 ><P | 3016 ><P |
2986 >The binary for LWAR is called "lwar". Note that the binary is in lower | 3017 >The binary for LWAR is called "lwar". Note that the binary is in lower |
2987 case. The options lwar understands are listed below. For archive manipulation | 3018 case. The options lwar understands are listed below. For archive manipulation |
3178 followed by any data required by the term. Then end of the list is flagged | 3209 followed by any data required by the term. Then end of the list is flagged |
3179 by a NULL expression (only an end of expression term).</P | 3210 by a NULL expression (only an end of expression term).</P |
3180 ><DIV | 3211 ><DIV |
3181 CLASS="TABLE" | 3212 CLASS="TABLE" |
3182 ><A | 3213 ><A |
3183 NAME="AEN1009" | 3214 NAME="AEN1016" |
3184 ></A | 3215 ></A |
3185 ><P | 3216 ><P |
3186 ><B | 3217 ><B |
3187 >Table 6-1. Object File Term Types</B | 3218 >Table 6-1. Object File Term Types</B |
3188 ></P | 3219 ></P |
3250 allows local symbols that are not exported to have the same names as | 3281 allows local symbols that are not exported to have the same names as |
3251 exported symbols or external references.</P | 3282 exported symbols or external references.</P |
3252 ><DIV | 3283 ><DIV |
3253 CLASS="TABLE" | 3284 CLASS="TABLE" |
3254 ><A | 3285 ><A |
3255 NAME="AEN1039" | 3286 NAME="AEN1046" |
3256 ></A | 3287 ></A |
3257 ><P | 3288 ><P |
3258 ><B | 3289 ><B |
3259 >Table 6-2. Object File Operator Numbers</B | 3290 >Table 6-2. Object File Operator Numbers</B |
3260 ></P | 3291 ></P |