Mercurial > hg > index.cgi
comparison docs/manual/manual.html @ 394:fc166b3bbae3
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 > Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary | 990 > 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 > Structures are used to group related data in a fixed structure. A structure | 1883 > 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 (< and >). It only | 2511 not override the operand size override prefixes (< and >). 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 > 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 > 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 > 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 > 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. </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 > 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 > 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 > 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 > 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 > 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 > LWLINK takes one or more files in supported input formats and links them | 2870 > 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 |