Mercurial > hg > index.cgi

comparison docs/manual.docbook.sgml @ 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 fda62f676ed4
comparison
equal deleted inserted replaced
393:f2decd9b276d 394:fc166b3bbae3
282 <para> 282 <para>
283 This will cause the assembler to accept the additional instructions available 283 This will cause the assembler to accept the additional instructions available
284 on the 6309 processor. This is the default mode; this option is provided for 284 on the 6309 processor. This is the default mode; this option is provided for
285 completeness and to override preset command arguments. 285 completeness and to override preset command arguments.
286 </para> 286 </para>
287 <para>
288 This option is the same as if the first line of the source code is "PRAGMA 6309".
289 </para>
287 </listitem> 290 </listitem>
288 </varlistentry> 291 </varlistentry>
289 292
290 <varlistentry> 293 <varlistentry>
291 <term><option>--6800compat</option></term> 294 <term><option>--6800compat</option></term>
300 <term><option>--6809</option></term> 303 <term><option>--6809</option></term>
301 <term><option>-9</option></term> 304 <term><option>-9</option></term>
302 <listitem> 305 <listitem>
303 <para> 306 <para>
304 This will cause the assembler to reject instructions that are only available 307 This will cause the assembler to reject instructions that are only available
305 on the 6309 processor. 308 on the 6309 processor. This actually has the effect of starting the assembler
309 as though the first line of the source is "PRAGMA 6809".
306 </para> 310 </para>
307 </listitem> 311 </listitem>
308 </varlistentry> 312 </varlistentry>
309 313
310 <varlistentry> 314 <varlistentry>
444 redefine SYM using EQU will result in a multiply defined symbol error. 448 redefine SYM using EQU will result in a multiply defined symbol error.
445 </para> 449 </para>
446 </listitem> 450 </listitem>
447 </varlistentry> 451 </varlistentry>
448 452
453 <varlistentry>
454 <term><option>-t WIDTH</option></term>
455 <term><option>--tabs=WIDTH</option></term>
456 <listitem>
457 <para>
458 Specifies the handling of tabs in listing files. <option>--tabs=0</option>
459 disables tab expansion. <option>--tabs=8</option> is the default setting.
460 </para>
461 </listitem>
462 </varlistentry>
449 463
450 <varlistentry> 464 <varlistentry>
451 <term><option>--help</option></term> 465 <term><option>--help</option></term>
452 <term><option>-?</option></term> 466 <term><option>-?</option></term>
453 <listitem> 467 <listitem>
858 </para> 872 </para>
859 </listitem> 873 </listitem>
860 </varlistentry> 874 </varlistentry>
861 875
862 <varlistentry> 876 <varlistentry>
877 <term>REORG</term>
878 <listitem>
879 <para>
880 Sets the assembly address to the value it had immediately prior to the
881 previous ORG statement. It is used to continue assembly after some
882 specification that required an additional ORG. This directive is primarily
883 intended for MACRO-80c compatibility. Consider using alternatives in
884 modern code.
885 </para>
886 </listitem>
887 </varlistentry>
888
889 <varlistentry>
863 <term><parameter>sym</parameter> EQU <parameter>expr</parameter></term> 890 <term><parameter>sym</parameter> EQU <parameter>expr</parameter></term>
864 <term><parameter>sym</parameter> = <parameter>expr</parameter></term> 891 <term><parameter>sym</parameter> = <parameter>expr</parameter></term>
865 <listitem> 892 <listitem>
866 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>. 893 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>.
867 </listitem> 894 </listitem>
1003 process, the conditional 1030 process, the conditional
1004 will be considered true. 1031 will be considered true.
1005 </para> 1032 </para>
1006 </listitem> 1033 </listitem>
1007 </varlistentry> 1034 </varlistentry>
1035
1036 <varlistentry>
1037 <term>IFPRAGMA <parameter>pragma</parameter></term>
1038 <listitem>
1039 <para>
1040 If <parameter>pragma</parameter> is in effect, the condition will be considered true.
1041 </para>
1042 </listitem>
1043 </varlistentry>
1044
1008 1045
1009 <varlistentry> 1046 <varlistentry>
1010 <term>IFNDEF <parameter>sym</parameter></term> 1047 <term>IFNDEF <parameter>sym</parameter></term>
1011 <listitem> 1048 <listitem>
1012 <para>If <parameter>sym</parameter> is not defined at this point in the assembly 1049 <para>If <parameter>sym</parameter> is not defined at this point in the assembly
1662 compatibility and LWASM itself did not support these instructions prior to 1699 compatibility and LWASM itself did not support these instructions prior to
1663 version 4.11 so this mode is disabled by default.</para> 1700 version 4.11 so this mode is disabled by default.</para>
1664 1701
1665 </listitem> 1702 </listitem>
1666 1703
1704 </varlistentry>
1705
1706 <varlistentry>
1707 <term>6809</term>
1708 <listitem>
1709 <para>
1710 This pragma allows you to mark a section of code as 6809-only. In ths mode,
1711 the assembler will throw an error if any 6309 instructions are used.
1712 </para>
1713 </listitem>
1714 </varlistentry>
1715
1716 <varlistentry>
1717 <term>6309</term>
1718 <listitem>
1719 <para>
1720 This pragma enables the use of 6309 instructions and disables any 6809 specific
1721 instructions. It also changes the cycle count listing output (if selected)
1722 to display 6309 timings.
1723 </para>
1724 </listitem>
1725 </varlistentry>
1726
1727 <varlistentry>
1728 <term>6809conv</term>
1729 <term>6309conv</term>
1730 <listitem>
1731 <para>
1732 These pragmas enable convenience instructions extending the 6809 and 6309
1733 instruction sets respectively. For more information, see
1734 <xref linkend="convinst">.
1735 </para>
1736 </listitem>
1737 </varlistentry>
1738
1739
1667 <varlistentry> 1740 <varlistentry>
1668 <term>index0tonone</term> 1741 <term>index0tonone</term>
1669 <listitem> 1742 <listitem>
1670 <para> 1743 <para>
1671 When in force, this pragma enables an optimization affecting indexed addressing 1744 When in force, this pragma enables an optimization affecting indexed addressing
1899 applies when the assembler is left to guess what the operand size is.</para> 1972 applies when the assembler is left to guess what the operand size is.</para>
1900 1973
1901 </listitem> 1974 </listitem>
1902 </varlistentry> 1975 </varlistentry>
1903 1976
1977 <varlistentry>
1978 <term>qrts</term>
1979 <listitem>
1980 <para>
1981
1982 Enables the use of the ?RTS branch target. ?RTS is implemented to maintain
1983 compatibility with the MACRO-80c assembler. It works by searching backward
1984 in the code for an RTS instruction. If none is found, it inverts the branch
1985 logic and inserts an RTS following the branch instruction. Below you can
1986 see how a BMI (2B xx) has been assembled as a BPL *+1 (2A 01) to skip over an
1987 inserted RTS (39).
1988 </para>
1989 <programlisting>
1990 1D1E 7D1D1D TST WHICH1
1991 1D21 2A0139 BMI ?RTS
1992 1D24 BD1D65 JSR INV
1993 </programlisting>
1994 </listitem>
1995 </varlistentry>
1996
1997 <varlistentry>
1998 <term>m80ext</term>
1999 <listitem>
2000 <para>
2001
2002 This pragma (along with pragma qrts) enables some uncommon behaviors to
2003 accomodate The Micro Works MACRO-80c assembler from 1982. This assembler
2004 was used by a number of notable TRS-80 Color Computer applications and the
2005 goal of this pragma is to allow them to build identical binaries from
2006 unmodified, vintage source code.
2007 </para>
2008 <para>
2009
2010 In m80ext mode, the handling of the "END" pseudo-op changes when used inside
2011 an include file. Instead of terminating all assembly, it merely stops
2012 processing of the current include file (this behavior matches the original
2013 Motorola 6809 assembler). In addition, loading an ASCII value with a single
2014 quote (e.g., LDA #'N) is extended to 16-bit registers (e.g., LDD #'NO).
2015 LWASM normally supports this via double quote and that is the proper use in
2016 modern code. Finally, the FCC pseudo-op is extended to handle FCB-like
2017 behavior after the closing delimiter:
2018 </para>
2019 <programlisting>
2020 FCC "Greetings from 1982",13,0
2021 </programlisting>
2022 </listitem>
2023 </varlistentry>
2024
2025
2026
2027 <varlistentry>
2028 <term>testmode</term>
2029 <listitem>
2030 <para>
2031
2032 This pragma is intended for internal testing purposes. In testmode, the
2033 assembler searches for a specially-formatted comment starting with a
2034 semicolon followed by a period. Immediately afterward are a list of hex
2035 bytes that the assembler is expected to generate. Likewise, if the
2036 assembler is expected to throw an error or warning on a given line, you can
2037 check by specifying "E:" followed by the error number. In this case the
2038 error is ignored and the assembler continues ignoring the line in question.
2039
2040 </para>
2041 <programlisting>
2042 1D1E 7D1D1D TST WHICH1 ;.7d1d1d
2043 1D21 2A0139 BMI ?RTS ;.2a0139
2044 1D24 1D24 FDB * ;.1d24
2045 1D26 xyz INV ;.E:32 (Error 32 is "Bad opcode")
2046 </programlisting>
2047 </listitem>
2048 </varlistentry>
1904 2049
1905 </variablelist> 2050 </variablelist>
1906 2051
1907 <para>As a convenience, each input file has a pragma state stack. This 2052 <para>As a convenience, each input file has a pragma state stack. This
1908 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a 2053 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
1920 file to operate under the nolist pragma. However, if the file is included 2065 file to operate under the nolist pragma. However, if the file is included
1921 while nolist is already engaged, it will not undo that state.</para> 2066 while nolist is already engaged, it will not undo that state.</para>
1922 2067
1923 2068
1924 2069
2070 </section>
2071
2072 <section id="convinst">
2073 <title id="convinsttitle">Convenience Instructions</title>
2074 <para>
2075
2076 Similar to the 6800 compatibility instructions (pragma 6800compat) these
2077 pragma 6809conv and pragma 6309conv enable convenience extensions to the
2078 6809 and 6309 instruction set. Originally intended for compatibility with
2079 the MACRO-80c assembler, these have proven useful in large codebases that
2080 target both the 6809 and the 6309.
2081 </para>
2082
2083 <para>
2084
2085 The 6809 extensions are straightforward with the exception of "TSTD" which
2086 assembles as "STD -2,S". A benefit of using these is they will "just work"
2087 and take on their 6309 equivalent when you enable 6309 assembly mode.
2088 Supported instructions: ASRD, CLRD, COMD, LSLD, LSRD, NEGD, TSTD.
2089 </para>
2090 <para>
2091
2092 6309 extensions are based on common patterns described by Chris Burke and
2093 Darren Atkinson in their 6309 documentation and include the following
2094 instructions: ASRQ, CLRQ, COMQ, LSLE, LSLF, LSLQ, LSRQ, NEGE,
2095 NEGF, NEGW, NEGQ, TSTQ.
2096 </para>
2097 </section>
2098
2099 <section>
2100 <title>Cycle Counts</title>
2101 <para>
2102
2103 The following options for displaying cycle counts in listings are provided.
2104 These options are enabled from pragmas on the command line or in the
2105 assembly files themselves. For compatibility with other assemblers you can
2106 use the "OPT" keyword in addition to "PRAGMA."
2107 </para>
2108
2109 <programlisting>
2110 opt c - enable cycle counts: [8]
2111 opt cd - enable detailed cycle counts breaking down addressing modes: [5+3]
2112 opt ct - show a running subtotal of cycles
2113 opt cc - clear the running subtotal
2114 </programlisting>
2115
2116 <para>
2117
2118 The assembler supports both 6809 as well as native-mode 6309 cycle counts.
2119 In 6309 mode the counts are displayed in parenthesis instead of brackets.
2120 In addition, some operations have a variable cycle count. In this case a
2121 "+?" is displayed to alert the reader. Sample output is shown below.
2122 </para>
2123
2124 <programlisting>
2125 266f 7d25e2 (window.asm):00313 [7] 7 move tst putflg
2126 2672 2602 (window.asm):00314 [5] 12 bne a@
2127 2674 1e13 (window.asm):00315 [8] 20 exg x,u
2128 2676 0dd6 (window.asm):00316 [6] 26 a@ tst is6309
2129 2678 2618 (window.asm):00317 [5] 31 bne exit@
2130 (window.asm):00318 opt 6309
2131 267a 10860085 (window.asm):00319 (4) 35 b@ ldw #133
2132 267e 113813 (window.asm):00320 (6+?) 41 tfm x+,u+
2133 2681 30881b (window.asm):00321 (4+1) 46 leax 27,x
2134 2684 33c81b (window.asm):00322 (4+1) 51 leau 27,u
2135 2687 4a (window.asm):00323 (1) 52 deca
2136 2688 26f0 (window.asm):00324 (5) 57 bne b@
2137 </programlisting>
1925 </section> 2138 </section>
1926 2139
1927 </chapter> 2140 </chapter>
1928 2141
1929 <chapter> 2142 <chapter>