Mercurial > hg > index.cgi

comparison docs/manual/manual.html @ 347:330a66a0f45a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 (&lt; and &gt;). 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 >&#13;LWLINK takes one or more files in supported input formats and links them 2649 >&#13;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