Mercurial > hg > index.cgi

comparison docs/manual/manual.html @ 394:fc166b3bbae3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update manual for recent additions. Document recent feature additions in the manual. Thanks to Erik G <erik@6809.org> for the text for most of these manual additions.
author William Astle <lost@l-w.ca>
date Wed, 15 Jul 2015 19:54:57 -0600
parents 682524a1f32f
children 566660ef3b4d
comparison
equal deleted inserted replaced
393:f2decd9b276d 394:fc166b3bbae3
119 HREF="#AEN65" 119 HREF="#AEN65"
120 >Command Line Options</A 120 >Command Line Options</A
121 ></DT 121 ></DT
122 ><DT 122 ><DT
123 >3.2. <A 123 >3.2. <A
124 HREF="#AEN208" 124 HREF="#AEN218"
125 >Dialects</A 125 >Dialects</A
126 ></DT 126 ></DT
127 ><DT 127 ><DT
128 >3.3. <A 128 >3.3. <A
129 HREF="#AEN217" 129 HREF="#AEN227"
130 >Source Format</A 130 >Source Format</A
131 ></DT 131 ></DT
132 ><DT 132 ><DT
133 >3.4. <A 133 >3.4. <A
134 HREF="#AEN227" 134 HREF="#AEN237"
135 >Symbols</A 135 >Symbols</A
136 ></DT 136 ></DT
137 ><DT 137 ><DT
138 >3.5. <A 138 >3.5. <A
139 HREF="#AEN232" 139 HREF="#AEN242"
140 >Numbers and Expressions</A 140 >Numbers and Expressions</A
141 ></DT 141 ></DT
142 ><DT 142 ><DT
143 >3.6. <A 143 >3.6. <A
144 HREF="#AEN240" 144 HREF="#AEN250"
145 >Assembler Directives</A 145 >Assembler Directives</A
146 ></DT 146 ></DT
147 ><DD 147 ><DD
148 ><DL 148 ><DL
149 ><DT 149 ><DT
150 >3.6.1. <A 150 >3.6.1. <A
151 HREF="#AEN243" 151 HREF="#AEN253"
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="#AEN354" 156 HREF="#AEN364"
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="#AEN401" 161 HREF="#AEN415"
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="#AEN466" 166 HREF="#AEN486"
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="#AEN491" 171 HREF="#AEN511"
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="#AEN531" 178 HREF="#AEN551"
179 >Macros</A 179 >Macros</A
180 ></DT 180 ></DT
181 ><DT 181 ><DT
182 >3.8. <A 182 >3.8. <A
183 HREF="#AEN554" 183 HREF="#AEN574"
184 >Structures</A 184 >Structures</A
185 ></DT 185 ></DT
186 ><DT 186 ><DT
187 >3.9. <A 187 >3.9. <A
188 HREF="#AEN575" 188 HREF="#AEN595"
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="#AEN639" 193 HREF="#AEN659"
194 >Assembler Modes and Pragmas</A 194 >Assembler Modes and Pragmas</A
195 ></DT 195 ></DT
196 ><DT
197 >3.11. <A
198 HREF="#CONVINST"
199 >Convenience Instructions</A
200 ></DT
201 ><DT
202 >3.12. <A
203 HREF="#AEN800"
204 >Cycle Counts</A
205 ></DT
196 ></DL 206 ></DL
197 ></DD 207 ></DD
198 ><DT 208 ><DT
199 >4. <A 209 >4. <A
200 HREF="#AEN745" 210 HREF="#AEN806"
201 >LWLINK</A 211 >LWLINK</A
202 ></DT 212 ></DT
203 ><DD 213 ><DD
204 ><DL 214 ><DL
205 ><DT 215 ><DT
206 >4.1. <A 216 >4.1. <A
207 HREF="#AEN748" 217 HREF="#AEN809"
208 >Command Line Options</A 218 >Command Line Options</A
209 ></DT 219 ></DT
210 ><DT 220 ><DT
211 >4.2. <A 221 >4.2. <A
212 HREF="#AEN845" 222 HREF="#AEN906"
213 >Linker Operation</A 223 >Linker Operation</A
214 ></DT 224 ></DT
215 ><DT 225 ><DT
216 >4.3. <A 226 >4.3. <A
217 HREF="#AEN859" 227 HREF="#AEN920"
218 >Linking Scripts</A 228 >Linking Scripts</A
219 ></DT 229 ></DT
220 ><DT 230 ><DT
221 >4.4. <A 231 >4.4. <A
222 HREF="#AEN925" 232 HREF="#AEN986"
223 >Format Specific Linking Notes</A 233 >Format Specific Linking Notes</A
224 ></DT 234 ></DT
225 ><DD 235 ><DD
226 ><DL 236 ><DL
227 ><DT 237 ><DT
228 >4.4.1. <A 238 >4.4.1. <A
229 HREF="#AEN928" 239 HREF="#AEN989"
230 >OS9 Modules</A 240 >OS9 Modules</A
231 ></DT 241 ></DT
232 ></DL 242 ></DL
233 ></DD 243 ></DD
234 ></DL 244 ></DL
235 ></DD 245 ></DD
236 ><DT 246 ><DT
237 >5. <A 247 >5. <A
238 HREF="#AEN940" 248 HREF="#AEN1001"
239 >Libraries and LWAR</A 249 >Libraries and LWAR</A
240 ></DT 250 ></DT
241 ><DD 251 ><DD
242 ><DL 252 ><DL
243 ><DT 253 ><DT
244 >5.1. <A 254 >5.1. <A
245 HREF="#AEN944" 255 HREF="#AEN1005"
246 >Command Line Options</A 256 >Command Line Options</A
247 ></DT 257 ></DT
248 ></DL 258 ></DL
249 ></DD 259 ></DD
250 ><DT 260 ><DT
262 ><B 272 ><B
263 >List of Tables</B 273 >List of Tables</B
264 ></DT 274 ></DT
265 ><DT 275 ><DT
266 >6-1. <A 276 >6-1. <A
267 HREF="#AEN1027" 277 HREF="#AEN1088"
268 >Object File Term Types</A 278 >Object File Term Types</A
269 ></DT 279 ></DT
270 ><DT 280 ><DT
271 >6-2. <A 281 >6-2. <A
272 HREF="#AEN1057" 282 HREF="#AEN1118"
273 >Object File Operator Numbers</A 283 >Object File Operator Numbers</A
274 ></DT 284 ></DT
275 ></DL 285 ></DL
276 ></DIV 286 ></DIV
277 ><DIV 287 ><DIV
554 ><DD 564 ><DD
555 ><P 565 ><P
556 >This will cause the assembler to accept the additional instructions available 566 >This will cause the assembler to accept the additional instructions available
557 on the 6309 processor. This is the default mode; this option is provided for 567 on the 6309 processor. This is the default mode; this option is provided for
558 completeness and to override preset command arguments.</P 568 completeness and to override preset command arguments.</P
569 ><P
570 >This option is the same as if the first line of the source code is "PRAGMA 6309".</P
559 ></DD 571 ></DD
560 ><DT 572 ><DT
561 ><CODE 573 ><CODE
562 CLASS="OPTION" 574 CLASS="OPTION"
563 >--6800compat</CODE 575 >--6800compat</CODE
580 >-9</CODE 592 >-9</CODE
581 ></DT 593 ></DT
582 ><DD 594 ><DD
583 ><P 595 ><P
584 >This will cause the assembler to reject instructions that are only available 596 >This will cause the assembler to reject instructions that are only available
585 on the 6309 processor.</P 597 on the 6309 processor. This actually has the effect of starting the assembler
598 as though the first line of the source is "PRAGMA 6809".</P
586 ></DD 599 ></DD
587 ><DT 600 ><DT
588 ><CODE 601 ><CODE
589 CLASS="OPTION" 602 CLASS="OPTION"
590 >--decb</CODE 603 >--decb</CODE
780 redefine SYM using EQU will result in a multiply defined symbol error.</P 793 redefine SYM using EQU will result in a multiply defined symbol error.</P
781 ></DD 794 ></DD
782 ><DT 795 ><DT
783 ><CODE 796 ><CODE
784 CLASS="OPTION" 797 CLASS="OPTION"
798 >-t WIDTH</CODE
799 >, <CODE
800 CLASS="OPTION"
801 >--tabs=WIDTH</CODE
802 ></DT
803 ><DD
804 ><P
805 >Specifies the handling of tabs in listing files. <CODE
806 CLASS="OPTION"
807 >--tabs=0</CODE
808 >
809 disables tab expansion. <CODE
810 CLASS="OPTION"
811 >--tabs=8</CODE
812 > is the default setting.</P
813 ></DD
814 ><DT
815 ><CODE
816 CLASS="OPTION"
785 >--help</CODE 817 >--help</CODE
786 >, <CODE 818 >, <CODE
787 CLASS="OPTION" 819 CLASS="OPTION"
788 >-?</CODE 820 >-?</CODE
789 ></DT 821 ></DT
831 ><DIV 863 ><DIV
832 CLASS="SECTION" 864 CLASS="SECTION"
833 ><HR><H2 865 ><HR><H2
834 CLASS="SECTION" 866 CLASS="SECTION"
835 ><A 867 ><A
836 NAME="AEN208" 868 NAME="AEN218"
837 >3.2. Dialects</A 869 >3.2. Dialects</A
838 ></H2 870 ></H2
839 ><P 871 ><P
840 > LWASM supports all documented MC6809 instructions as defined by 872 > LWASM supports all documented MC6809 instructions as defined by
841 Motorola. By default, this does not include any MC6800 compatibility 873 Motorola. By default, this does not include any MC6800 compatibility
875 ><DIV 907 ><DIV
876 CLASS="SECTION" 908 CLASS="SECTION"
877 ><HR><H2 909 ><HR><H2
878 CLASS="SECTION" 910 CLASS="SECTION"
879 ><A 911 ><A
880 NAME="AEN217" 912 NAME="AEN227"
881 >3.3. Source Format</A 913 >3.3. Source Format</A
882 ></H2 914 ></H2
883 ><P 915 ><P
884 >LWASM accepts plain text files in a relatively free form. It can handle 916 >LWASM accepts plain text files in a relatively free form. It can handle
885 lines terminated with CR, LF, CRLF, or LFCR which means it should be able 917 lines terminated with CR, LF, CRLF, or LFCR which means it should be able
921 ><DIV 953 ><DIV
922 CLASS="SECTION" 954 CLASS="SECTION"
923 ><HR><H2 955 ><HR><H2
924 CLASS="SECTION" 956 CLASS="SECTION"
925 ><A 957 ><A
926 NAME="AEN227" 958 NAME="AEN237"
927 >3.4. Symbols</A 959 >3.4. Symbols</A
928 ></H2 960 ></H2
929 ><P 961 ><P
930 >Symbols have no length restriction. They may contain letters, numbers, dots, 962 >Symbols have no length restriction. They may contain letters, numbers, dots,
931 dollar signs, and underscores. They must start with a letter, dot, or 963 dollar signs, and underscores. They must start with a letter, dot, or
949 ><DIV 981 ><DIV
950 CLASS="SECTION" 982 CLASS="SECTION"
951 ><HR><H2 983 ><HR><H2
952 CLASS="SECTION" 984 CLASS="SECTION"
953 ><A 985 ><A
954 NAME="AEN232" 986 NAME="AEN242"
955 >3.5. Numbers and Expressions</A 987 >3.5. Numbers and Expressions</A
956 ></H2 988 ></H2
957 ><P 989 ><P
958 >&#13;Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary 990 >&#13;Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
959 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B". 991 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B".
994 ><DIV 1026 ><DIV
995 CLASS="SECTION" 1027 CLASS="SECTION"
996 ><HR><H2 1028 ><HR><H2
997 CLASS="SECTION" 1029 CLASS="SECTION"
998 ><A 1030 ><A
999 NAME="AEN240" 1031 NAME="AEN250"
1000 >3.6. Assembler Directives</A 1032 >3.6. Assembler Directives</A
1001 ></H2 1033 ></H2
1002 ><P 1034 ><P
1003 >Various directives can be used to control the behaviour of the 1035 >Various directives can be used to control the behaviour of the
1004 assembler or to include non-code/data in the resulting output. Those directives 1036 assembler or to include non-code/data in the resulting output. Those directives
1007 ><DIV 1039 ><DIV
1008 CLASS="SECTION" 1040 CLASS="SECTION"
1009 ><HR><H3 1041 ><HR><H3
1010 CLASS="SECTION" 1042 CLASS="SECTION"
1011 ><A 1043 ><A
1012 NAME="AEN243" 1044 NAME="AEN253"
1013 >3.6.1. Data Directives</A 1045 >3.6.1. Data Directives</A
1014 ></H3 1046 ></H3
1015 ><P 1047 ><P
1016 ></P 1048 ></P
1017 ><DIV 1049 ><DIV
1241 ><DIV 1273 ><DIV
1242 CLASS="SECTION" 1274 CLASS="SECTION"
1243 ><HR><H3 1275 ><HR><H3
1244 CLASS="SECTION" 1276 CLASS="SECTION"
1245 ><A 1277 ><A
1246 NAME="AEN354" 1278 NAME="AEN364"
1247 >3.6.2. Address Definition</A 1279 >3.6.2. Address Definition</A
1248 ></H3 1280 ></H3
1249 ><P 1281 ><P
1250 >The directives in this section all control the addresses of symbols 1282 >The directives in this section all control the addresses of symbols
1251 or the assembly process itself.</P 1283 or the assembly process itself.</P
1267 that include address information (decb, hex, srec, and ihex), an ORG 1299 that include address information (decb, hex, srec, and ihex), an ORG
1268 directive will re-start the address sequence within the output. When using 1300 directive will re-start the address sequence within the output. When using
1269 the raw target format, ORG is used only to determine the addresses of symbols.</P 1301 the raw target format, ORG is used only to determine the addresses of symbols.</P
1270 ></DD 1302 ></DD
1271 ><DT 1303 ><DT
1304 >REORG</DT
1305 ><DD
1306 ><P
1307 >Sets the assembly address to the value it had immediately prior to the
1308 previous ORG statement. It is used to continue assembly after some
1309 specification that required an additional ORG. This directive is primarily
1310 intended for MACRO-80c compatibility. Consider using alternatives in
1311 modern code.</P
1312 ></DD
1313 ><DT
1272 ><CODE 1314 ><CODE
1273 CLASS="PARAMETER" 1315 CLASS="PARAMETER"
1274 >sym</CODE 1316 >sym</CODE
1275 > EQU <CODE 1317 > EQU <CODE
1276 CLASS="PARAMETER" 1318 CLASS="PARAMETER"
1377 ><DIV 1419 ><DIV
1378 CLASS="SECTION" 1420 CLASS="SECTION"
1379 ><HR><H3 1421 ><HR><H3
1380 CLASS="SECTION" 1422 CLASS="SECTION"
1381 ><A 1423 ><A
1382 NAME="AEN401" 1424 NAME="AEN415"
1383 >3.6.3. Conditional Assembly</A 1425 >3.6.3. Conditional Assembly</A
1384 ></H3 1426 ></H3
1385 ><P 1427 ><P
1386 >Portions of the source code can be excluded or included based on conditions 1428 >Portions of the source code can be excluded or included based on conditions
1387 known at assembly time. Conditionals can be nested arbitrarily deeply. The 1429 known at assembly time. Conditionals can be nested arbitrarily deeply. The
1501 > is defined at this point in the assembly 1543 > is defined at this point in the assembly
1502 process, the conditional 1544 process, the conditional
1503 will be considered true.</P 1545 will be considered true.</P
1504 ></DD 1546 ></DD
1505 ><DT 1547 ><DT
1548 >IFPRAGMA <CODE
1549 CLASS="PARAMETER"
1550 >pragma</CODE
1551 ></DT
1552 ><DD
1553 ><P
1554 >If <CODE
1555 CLASS="PARAMETER"
1556 >pragma</CODE
1557 > is in effect, the condition will be considered true.</P
1558 ></DD
1559 ><DT
1506 >IFNDEF <CODE 1560 >IFNDEF <CODE
1507 CLASS="PARAMETER" 1561 CLASS="PARAMETER"
1508 >sym</CODE 1562 >sym</CODE
1509 ></DT 1563 ></DT
1510 ><DD 1564 ><DD
1540 ><DIV 1594 ><DIV
1541 CLASS="SECTION" 1595 CLASS="SECTION"
1542 ><HR><H3 1596 ><HR><H3
1543 CLASS="SECTION" 1597 CLASS="SECTION"
1544 ><A 1598 ><A
1545 NAME="AEN466" 1599 NAME="AEN486"
1546 >3.6.4. OS9 Target Directives</A 1600 >3.6.4. OS9 Target Directives</A
1547 ></H3 1601 ></H3
1548 ><P 1602 ><P
1549 >This section includes directives that apply solely to the OS9 1603 >This section includes directives that apply solely to the OS9
1550 target.</P 1604 target.</P
1607 ><DIV 1661 ><DIV
1608 CLASS="SECTION" 1662 CLASS="SECTION"
1609 ><HR><H3 1663 ><HR><H3
1610 CLASS="SECTION" 1664 CLASS="SECTION"
1611 ><A 1665 ><A
1612 NAME="AEN491" 1666 NAME="AEN511"
1613 >3.6.5. Miscelaneous Directives</A 1667 >3.6.5. Miscelaneous Directives</A
1614 ></H3 1668 ></H3
1615 ><P 1669 ><P
1616 >This section includes directives that do not fit into the other 1670 >This section includes directives that do not fit into the other
1617 categories.</P 1671 categories.</P
1721 ><DIV 1775 ><DIV
1722 CLASS="SECTION" 1776 CLASS="SECTION"
1723 ><HR><H2 1777 ><HR><H2
1724 CLASS="SECTION" 1778 CLASS="SECTION"
1725 ><A 1779 ><A
1726 NAME="AEN531" 1780 NAME="AEN551"
1727 >3.7. Macros</A 1781 >3.7. Macros</A
1728 ></H2 1782 ></H2
1729 ><P 1783 ><P
1730 >LWASM is a macro assembler. A macro is simply a name that stands in for a 1784 >LWASM is a macro assembler. A macro is simply a name that stands in for a
1731 series of instructions. Once a macro is defined, it is used like any other 1785 series of instructions. Once a macro is defined, it is used like any other
1820 ><DIV 1874 ><DIV
1821 CLASS="SECTION" 1875 CLASS="SECTION"
1822 ><HR><H2 1876 ><HR><H2
1823 CLASS="SECTION" 1877 CLASS="SECTION"
1824 ><A 1878 ><A
1825 NAME="AEN554" 1879 NAME="AEN574"
1826 >3.8. Structures</A 1880 >3.8. Structures</A
1827 ></H2 1881 ></H2
1828 ><P 1882 ><P
1829 >&#13;Structures are used to group related data in a fixed structure. A structure 1883 >&#13;Structures are used to group related data in a fixed structure. A structure
1830 consists a number of fields, defined in sequential order and which take up 1884 consists a number of fields, defined in sequential order and which take up
1913 ><DIV 1967 ><DIV
1914 CLASS="SECTION" 1968 CLASS="SECTION"
1915 ><HR><H2 1969 ><HR><H2
1916 CLASS="SECTION" 1970 CLASS="SECTION"
1917 ><A 1971 ><A
1918 NAME="AEN575" 1972 NAME="AEN595"
1919 >3.9. Object Files and Sections</A 1973 >3.9. Object Files and Sections</A
1920 ></H2 1974 ></H2
1921 ><P 1975 ><P
1922 >The object file target is very useful for large project because it allows 1976 >The object file target is very useful for large project because it allows
1923 multiple files to be assembled independently and then linked into the final 1977 multiple files to be assembled independently and then linked into the final
2130 ><DIV 2184 ><DIV
2131 CLASS="SECTION" 2185 CLASS="SECTION"
2132 ><HR><H2 2186 ><HR><H2
2133 CLASS="SECTION" 2187 CLASS="SECTION"
2134 ><A 2188 ><A
2135 NAME="AEN639" 2189 NAME="AEN659"
2136 >3.10. Assembler Modes and Pragmas</A 2190 >3.10. Assembler Modes and Pragmas</A
2137 ></H2 2191 ></H2
2138 ><P 2192 ><P
2139 >There are a number of options that affect the way assembly is performed. 2193 >There are a number of options that affect the way assembly is performed.
2140 Some of these options can only be specified on the command line because 2194 Some of these options can only be specified on the command line because
2232 >Technically, a compliant 6809 assembler must recognize these 2286 >Technically, a compliant 6809 assembler must recognize these
2233 instructions by default since Motorola advertised the 6809 as being source 2287 instructions by default since Motorola advertised the 6809 as being source
2234 compatible with the 6800. However, most source code does not require this 2288 compatible with the 6800. However, most source code does not require this
2235 compatibility and LWASM itself did not support these instructions prior to 2289 compatibility and LWASM itself did not support these instructions prior to
2236 version 4.11 so this mode is disabled by default.</P 2290 version 4.11 so this mode is disabled by default.</P
2291 ></DD
2292 ><DT
2293 >6809</DT
2294 ><DD
2295 ><P
2296 >This pragma allows you to mark a section of code as 6809-only. In ths mode,
2297 the assembler will throw an error if any 6309 instructions are used.</P
2298 ></DD
2299 ><DT
2300 >6309</DT
2301 ><DD
2302 ><P
2303 >This pragma enables the use of 6309 instructions and disables any 6809 specific
2304 instructions. It also changes the cycle count listing output (if selected)
2305 to display 6309 timings.</P
2306 ></DD
2307 ><DT
2308 >6809conv, 6309conv</DT
2309 ><DD
2310 ><P
2311 >These pragmas enable convenience instructions extending the 6809 and 6309
2312 instruction sets respectively. For more information, see
2313 <A
2314 HREF="#CONVINST"
2315 >Section 3.11</A
2316 >.</P
2237 ></DD 2317 ></DD
2238 ><DT 2318 ><DT
2239 >index0tonone</DT 2319 >index0tonone</DT
2240 ><DD 2320 ><DD
2241 ><P 2321 ><P
2429 will not change the correctness of the generated code unless cycle counts 2509 will not change the correctness of the generated code unless cycle counts
2430 or byte counts are critical (which they usually are not). It also will 2510 or byte counts are critical (which they usually are not). It also will
2431 not override the operand size override prefixes (&lt; and &gt;). It only 2511 not override the operand size override prefixes (&lt; and &gt;). It only
2432 applies when the assembler is left to guess what the operand size is.</P 2512 applies when the assembler is left to guess what the operand size is.</P
2433 ></DD 2513 ></DD
2514 ><DT
2515 >qrts</DT
2516 ><DD
2517 ><P
2518 >&#13;Enables the use of the ?RTS branch target. ?RTS is implemented to maintain
2519 compatibility with the MACRO-80c assembler. It works by searching backward
2520 in the code for an RTS instruction. If none is found, it inverts the branch
2521 logic and inserts an RTS following the branch instruction. Below you can
2522 see how a BMI (2B xx) has been assembled as a BPL *+1 (2A 01) to skip over an
2523 inserted RTS (39).</P
2524 ><PRE
2525 CLASS="PROGRAMLISTING"
2526 >1D1E 7D1D1D TST WHICH1
2527 1D21 2A0139 BMI ?RTS
2528 1D24 BD1D65 JSR INV</PRE
2529 ></DD
2530 ><DT
2531 >m80ext</DT
2532 ><DD
2533 ><P
2534 >&#13;This pragma (along with pragma qrts) enables some uncommon behaviors to
2535 accomodate The Micro Works MACRO-80c assembler from 1982. This assembler
2536 was used by a number of notable TRS-80 Color Computer applications and the
2537 goal of this pragma is to allow them to build identical binaries from
2538 unmodified, vintage source code.</P
2539 ><P
2540 >&#13;In m80ext mode, the handling of the "END" pseudo-op changes when used inside
2541 an include file. Instead of terminating all assembly, it merely stops
2542 processing of the current include file (this behavior matches the original
2543 Motorola 6809 assembler). In addition, loading an ASCII value with a single
2544 quote (e.g., LDA #'N) is extended to 16-bit registers (e.g., LDD #'NO).
2545 LWASM normally supports this via double quote and that is the proper use in
2546 modern code. Finally, the FCC pseudo-op is extended to handle FCB-like
2547 behavior after the closing delimiter:</P
2548 ><PRE
2549 CLASS="PROGRAMLISTING"
2550 > FCC "Greetings from 1982",13,0</PRE
2551 ></DD
2552 ><DT
2553 >testmode</DT
2554 ><DD
2555 ><P
2556 >&#13;This pragma is intended for internal testing purposes. In testmode, the
2557 assembler searches for a specially-formatted comment starting with a
2558 semicolon followed by a period. Immediately afterward are a list of hex
2559 bytes that the assembler is expected to generate. Likewise, if the
2560 assembler is expected to throw an error or warning on a given line, you can
2561 check by specifying "E:" followed by the error number. In this case the
2562 error is ignored and the assembler continues ignoring the line in question.&#13;</P
2563 ><PRE
2564 CLASS="PROGRAMLISTING"
2565 >1D1E 7D1D1D TST WHICH1 ;.7d1d1d
2566 1D21 2A0139 BMI ?RTS ;.2a0139
2567 1D24 1D24 FDB * ;.1d24
2568 1D26 xyz INV ;.E:32 (Error 32 is "Bad opcode")</PRE
2569 ></DD
2434 ></DL 2570 ></DL
2435 ></DIV 2571 ></DIV
2436 ><P 2572 ><P
2437 >As a convenience, each input file has a pragma state stack. This 2573 >As a convenience, each input file has a pragma state stack. This
2438 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a 2574 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
2448 pragma, engage the nolist pragma, and then pop the state of the nolist 2584 pragma, engage the nolist pragma, and then pop the state of the nolist
2449 pragma at the end of the include file. This will cause the entire include 2585 pragma at the end of the include file. This will cause the entire include
2450 file to operate under the nolist pragma. However, if the file is included 2586 file to operate under the nolist pragma. However, if the file is included
2451 while nolist is already engaged, it will not undo that state.</P 2587 while nolist is already engaged, it will not undo that state.</P
2452 ></DIV 2588 ></DIV
2589 ><DIV
2590 CLASS="SECTION"
2591 ><HR><H2
2592 CLASS="SECTION"
2593 ><A
2594 NAME="CONVINST"
2595 >3.11. Convenience Instructions</A
2596 ></H2
2597 ><P
2598 >&#13;Similar to the 6800 compatibility instructions (pragma 6800compat) these
2599 pragma 6809conv and pragma 6309conv enable convenience extensions to the
2600 6809 and 6309 instruction set. Originally intended for compatibility with
2601 the MACRO-80c assembler, these have proven useful in large codebases that
2602 target both the 6809 and the 6309.</P
2603 ><P
2604 >&#13;The 6809 extensions are straightforward with the exception of "TSTD" which
2605 assembles as "STD -2,S". A benefit of using these is they will "just work"
2606 and take on their 6309 equivalent when you enable 6309 assembly mode.
2607 Supported instructions: ASRD, CLRD, COMD, LSLD, LSRD, NEGD, TSTD.</P
2608 ><P
2609 >&#13;6309 extensions are based on common patterns described by Chris Burke and
2610 Darren Atkinson in their 6309 documentation and include the following
2611 instructions: ASRQ, CLRQ, COMQ, LSLE, LSLF, LSLQ, LSRQ, NEGE,
2612 NEGF, NEGW, NEGQ, TSTQ.</P
2613 ></DIV
2614 ><DIV
2615 CLASS="SECTION"
2616 ><HR><H2
2617 CLASS="SECTION"
2618 ><A
2619 NAME="AEN800"
2620 >3.12. Cycle Counts</A
2621 ></H2
2622 ><P
2623 >&#13;The following options for displaying cycle counts in listings are provided.
2624 These options are enabled from pragmas on the command line or in the
2625 assembly files themselves. For compatibility with other assemblers you can
2626 use the "OPT" keyword in addition to "PRAGMA."</P
2627 ><PRE
2628 CLASS="PROGRAMLISTING"
2629 >opt c - enable cycle counts: [8]
2630 opt cd - enable detailed cycle counts breaking down addressing modes: [5+3]
2631 opt ct - show a running subtotal of cycles
2632 opt cc - clear the running subtotal</PRE
2633 ><P
2634 >&#13;The assembler supports both 6809 as well as native-mode 6309 cycle counts.
2635 In 6309 mode the counts are displayed in parenthesis instead of brackets.
2636 In addition, some operations have a variable cycle count. In this case a
2637 "+?" is displayed to alert the reader. Sample output is shown below.</P
2638 ><PRE
2639 CLASS="PROGRAMLISTING"
2640 >266f 7d25e2 (window.asm):00313 [7] 7 move tst putflg
2641 2672 2602 (window.asm):00314 [5] 12 bne a@
2642 2674 1e13 (window.asm):00315 [8] 20 exg x,u
2643 2676 0dd6 (window.asm):00316 [6] 26 a@ tst is6309
2644 2678 2618 (window.asm):00317 [5] 31 bne exit@
2645 (window.asm):00318 opt 6309
2646 267a 10860085 (window.asm):00319 (4) 35 b@ ldw #133
2647 267e 113813 (window.asm):00320 (6+?) 41 tfm x+,u+
2648 2681 30881b (window.asm):00321 (4+1) 46 leax 27,x
2649 2684 33c81b (window.asm):00322 (4+1) 51 leau 27,u
2650 2687 4a (window.asm):00323 (1) 52 deca
2651 2688 26f0 (window.asm):00324 (5) 57 bne b@</PRE
2652 ></DIV
2453 ></DIV 2653 ></DIV
2454 ><DIV 2654 ><DIV
2455 CLASS="CHAPTER" 2655 CLASS="CHAPTER"
2456 ><HR><H1 2656 ><HR><H1
2457 ><A 2657 ><A
2458 NAME="AEN745" 2658 NAME="AEN806"
2459 ></A 2659 ></A
2460 >Chapter 4. LWLINK</H1 2660 >Chapter 4. LWLINK</H1
2461 ><P 2661 ><P
2462 >The LWTOOLS linker is called LWLINK. This chapter documents the various features 2662 >The LWTOOLS linker is called LWLINK. This chapter documents the various features
2463 of the linker.</P 2663 of the linker.</P
2464 ><DIV 2664 ><DIV
2465 CLASS="SECTION" 2665 CLASS="SECTION"
2466 ><HR><H2 2666 ><HR><H2
2467 CLASS="SECTION" 2667 CLASS="SECTION"
2468 ><A 2668 ><A
2469 NAME="AEN748" 2669 NAME="AEN809"
2470 >4.1. Command Line Options</A 2670 >4.1. Command Line Options</A
2471 ></H2 2671 ></H2
2472 ><P 2672 ><P
2473 >The binary for LWLINK is called "lwlink". Note that the binary is in lower 2673 >The binary for LWLINK is called "lwlink". Note that the binary is in lower
2474 case. lwlink takes the following command line arguments.</P 2674 case. lwlink takes the following command line arguments.</P
2661 ><DIV 2861 ><DIV
2662 CLASS="SECTION" 2862 CLASS="SECTION"
2663 ><HR><H2 2863 ><HR><H2
2664 CLASS="SECTION" 2864 CLASS="SECTION"
2665 ><A 2865 ><A
2666 NAME="AEN845" 2866 NAME="AEN906"
2667 >4.2. Linker Operation</A 2867 >4.2. Linker Operation</A
2668 ></H2 2868 ></H2
2669 ><P 2869 ><P
2670 >&#13;LWLINK takes one or more files in supported input formats and links them 2870 >&#13;LWLINK takes one or more files in supported input formats and links them
2671 into a single binary. Currently supported formats are the LWTOOLS object 2871 into a single binary. Currently supported formats are the LWTOOLS object
2717 ><DIV 2917 ><DIV
2718 CLASS="SECTION" 2918 CLASS="SECTION"
2719 ><HR><H2 2919 ><HR><H2
2720 CLASS="SECTION" 2920 CLASS="SECTION"
2721 ><A 2921 ><A
2722 NAME="AEN859" 2922 NAME="AEN920"
2723 >4.3. Linking Scripts</A 2923 >4.3. Linking Scripts</A
2724 ></H2 2924 ></H2
2725 ><P 2925 ><P
2726 >A linker script is used to instruct the linker about how to assemble the 2926 >A linker script is used to instruct the linker about how to assemble the
2727 various sections into a completed binary. It consists of a series of 2927 various sections into a completed binary. It consists of a series of
2921 ><DIV 3121 ><DIV
2922 CLASS="SECTION" 3122 CLASS="SECTION"
2923 ><HR><H2 3123 ><HR><H2
2924 CLASS="SECTION" 3124 CLASS="SECTION"
2925 ><A 3125 ><A
2926 NAME="AEN925" 3126 NAME="AEN986"
2927 >4.4. Format Specific Linking Notes</A 3127 >4.4. Format Specific Linking Notes</A
2928 ></H2 3128 ></H2
2929 ><P 3129 ><P
2930 >Some formats require special information to be able to generate actual 3130 >Some formats require special information to be able to generate actual
2931 binaries. If the specific format you are interested in is not listed in 3131 binaries. If the specific format you are interested in is not listed in
2934 ><DIV 3134 ><DIV
2935 CLASS="SECTION" 3135 CLASS="SECTION"
2936 ><HR><H3 3136 ><HR><H3
2937 CLASS="SECTION" 3137 CLASS="SECTION"
2938 ><A 3138 ><A
2939 NAME="AEN928" 3139 NAME="AEN989"
2940 >4.4.1. OS9 Modules</A 3140 >4.4.1. OS9 Modules</A
2941 ></H3 3141 ></H3
2942 ><P 3142 ><P
2943 >OS9 modules need to embed several items into the module header. These 3143 >OS9 modules need to embed several items into the module header. These
2944 items are the type of module, the langauge of the module, the module 3144 items are the type of module, the langauge of the module, the module
3010 ></DIV 3210 ></DIV
3011 ><DIV 3211 ><DIV
3012 CLASS="CHAPTER" 3212 CLASS="CHAPTER"
3013 ><HR><H1 3213 ><HR><H1
3014 ><A 3214 ><A
3015 NAME="AEN940" 3215 NAME="AEN1001"
3016 ></A 3216 ></A
3017 >Chapter 5. Libraries and LWAR</H1 3217 >Chapter 5. Libraries and LWAR</H1
3018 ><P 3218 ><P
3019 >LWTOOLS also includes a tool for managing libraries. These are analogous to 3219 >LWTOOLS also includes a tool for managing libraries. These are analogous to
3020 the static libraries created with the "ar" tool on POSIX systems. Each library 3220 the static libraries created with the "ar" tool on POSIX systems. Each library
3029 ><DIV 3229 ><DIV
3030 CLASS="SECTION" 3230 CLASS="SECTION"
3031 ><HR><H2 3231 ><HR><H2
3032 CLASS="SECTION" 3232 CLASS="SECTION"
3033 ><A 3233 ><A
3034 NAME="AEN944" 3234 NAME="AEN1005"
3035 >5.1. Command Line Options</A 3235 >5.1. Command Line Options</A
3036 ></H2 3236 ></H2
3037 ><P 3237 ><P
3038 >The binary for LWAR is called "lwar". Note that the binary is in lower 3238 >The binary for LWAR is called "lwar". Note that the binary is in lower
3039 case. The options lwar understands are listed below. For archive manipulation 3239 case. The options lwar understands are listed below. For archive manipulation
3230 followed by any data required by the term. Then end of the list is flagged 3430 followed by any data required by the term. Then end of the list is flagged
3231 by a NULL expression (only an end of expression term).</P 3431 by a NULL expression (only an end of expression term).</P
3232 ><DIV 3432 ><DIV
3233 CLASS="TABLE" 3433 CLASS="TABLE"
3234 ><A 3434 ><A
3235 NAME="AEN1027" 3435 NAME="AEN1088"
3236 ></A 3436 ></A
3237 ><P 3437 ><P
3238 ><B 3438 ><B
3239 >Table 6-1. Object File Term Types</B 3439 >Table 6-1. Object File Term Types</B
3240 ></P 3440 ></P
3302 allows local symbols that are not exported to have the same names as 3502 allows local symbols that are not exported to have the same names as
3303 exported symbols or external references.</P 3503 exported symbols or external references.</P
3304 ><DIV 3504 ><DIV
3305 CLASS="TABLE" 3505 CLASS="TABLE"
3306 ><A 3506 ><A
3307 NAME="AEN1057" 3507 NAME="AEN1118"
3308 ></A 3508 ></A
3309 ><P 3509 ><P
3310 ><B 3510 ><B
3311 >Table 6-2. Object File Operator Numbers</B 3511 >Table 6-2. Object File Operator Numbers</B
3312 ></P 3512 ></P