Mercurial > hg > index.cgi

comparison docs/manual.docbook.sgml @ 324:b30091890d62

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation of the new hex output formats. Thanks to text contributed by Tom LeMense, the manual now includes documentation of the hex formats he contributed. This also includes some updated text on the ORG directive. Only minor editorial changes vary the text from Tom's original.
author William Astle <lost@l-w.ca>
date Tue, 04 Mar 2014 23:10:13 -0700
parents c4853a54b4a1
children 507f442dc71e
comparison
equal deleted inserted replaced
323:ba9a0434b115 324:b30091890d62
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"> 1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
2 <book> 2 <book>
3 <bookinfo> 3 <bookinfo>
4 <title>LW Tool Chain</title> 4 <title>LW Tool Chain</title>
5 <author><firstname>William</firstname><surname>Astle</surname></author> 5 <author><firstname>William</firstname><surname>Astle</surname></author>
6 <copyright><year>2009-2013</year><holder>William Astle</holder></copyright> 6 <author><firstname>LWTools Contributors</firstname><surname></surname></author>
7 <copyright><year>2009-2014</year><holder>William Astle and LWTools contributors</holder></copyright>
7 </bookinfo> 8 </bookinfo>
8 <chapter> 9 <chapter>
9 10
10 <title>Introduction</title> 11 <title>Introduction</title>
11 12
90 Both LWASM and LWLINK can output this format. 91 Both LWASM and LWLINK can output this format.
91 </para> 92 </para>
92 </section> 93 </section>
93 94
94 <section> 95 <section>
96 <title>ASCII Hexadecimal</title>
97
98 <para>
99 This human-readable ASCII hexadecimal format consists of CR+LF terminated
100 lines of ASCII text. Each line has the following structure: a zero-padded
101 four-digit ASCII hex address, a colon separator, and one or more zero-padded
102 two-digit hex values separated by commas. ASCII Hexadecimal format favors
103 paragraph-aligned addresses (i.e. a least significant address nybble value
104 of zero). During output, the number of hex values on each line are adjusted
105 to align the address of the next line on a paragraph boundary. The sequence
106 of addresses in the ASCII Hexadecimal file directly follows that of the source
107 file; multiple ORG directives in the source code may result in out-of-sequence
108 addresses in the ASCII Hexadecimal output.
109 </para>
110
111 <para>
112 LWASM can output this format since version 4.10.
113 </para>
114 </section>
115
116 <section>
117 <title>Motorola S-Record</title>
118
119 <para>
120 This ASCII format consists of a series of CR+LF terminated "records" of ASCII
121 text. Each record has the following structure: a start-of-record character
122 "S", an ASCII record type digit (0-9), a two-digit ASCII hex byte count, a
123 four-digit ASCII hex address, an optional sequence of two-digit ASCII hex data
124 values, and a two-digit ASCII hex checksum. The LW tool chain issues only S0,
125 S1, S5 and S9 record types. S1 records are limited to maximum of 16 data bytes
126 in length, and paragraph alignment of addresses is favored. The address
127 sequence of the S-Records directly follows that of the source file; multiple
128 ORG directives in the source code may result in out-of-sequence addresses in
129 the S-Record output.
130 </para>
131
132 <para>
133 Motorola S-Record format is a standard ASCII format accepted by most memory
134 device programming equipment. It is particularly useful when the assembled
135 code output is destined to reside within an EPROM or Flash memory device,
136 for example.
137 </para>
138
139 <para>
140 LWASM can output this format since version 4.10.
141 </para>
142 </section>
143
144 <section>
145 <title>Intel Hex</title>
146
147 <para>
148 This ASCII format consists of a series of CR+LF terminated "records" of ASCII
149 text. Each record has the following structure: a start-of-record character
150 ":", a two-digit ASCII hex byte count, a four-digit ASCII hex address, a two-
151 digit ASCII hex record type, an optional sequence of two-digit ASCII hex data
152 values, and a two-digit ASCII hex checksum. The LW tool chain issues only 00,
153 and 01 Intel Hex record types. Data records are limited to maximum of 16
154 data bytes in length, and paragraph alignment of addresses is favored. The
155 address sequence of the Intel hex records directly follows that of the source
156 file; multiple ORG directives in the source code may result in out-of-sequence
157 addresses in the Intel Hex output.
158 </para>
159
160 <para>
161 Intel Hex format is the other standard ASCII format accepted by most memory
162 device programming equipment, it and the Motorola S-Record format are used for
163 similar purposes.
164 </para>
165
166 <para>
167 LWASM can output this format since version 4.10.
168 </para>
169 </section>
170
171 <section>
95 <title>OS9 Modules</title> 172 <title>OS9 Modules</title>
96 <para> 173 <para>
97 174
98 Since version 2.5, LWASM is able to generate OS9 modules. The syntax is 175 Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
99 basically the same as for other assemblers. A module starts with the MOD 176 basically the same as for other assemblers. A module starts with the MOD
239 <term><option>-f type</option></term> 316 <term><option>-f type</option></term>
240 <listitem> 317 <listitem>
241 <para> 318 <para>
242 Select the output format. Valid values are <option>obj</option> for the 319 Select the output format. Valid values are <option>obj</option> for the
243 object file target, <option>decb</option> for the DECB LOADM format, 320 object file target, <option>decb</option> for the DECB LOADM format,
244 <option>os9</option> for creating OS9 modules, and <option>raw</option> for 321 <option>os9</option> for creating OS9 modules, <option>raw</option> for
245 a raw binary. 322 a raw binary, <option>hex</option> for ASCII hexadecminal format,
323 <option>srec</option> for Motorola S-Record format, and <option>ihex</option>
324 for Intel Hex format.
246 </para> 325 </para>
247 </listitem> 326 </listitem>
248 </varlistentry> 327 </varlistentry>
249 328
250 <varlistentry> 329 <varlistentry>
737 <variablelist> 816 <variablelist>
738 <varlistentry><term>ORG <parameter>expr</parameter></term> 817 <varlistentry><term>ORG <parameter>expr</parameter></term>
739 <listitem> 818 <listitem>
740 <para>Set the assembly address. The address must be fully resolvable on the 819 <para>Set the assembly address. The address must be fully resolvable on the
741 first pass so no external or forward references are permitted. ORG is not 820 first pass so no external or forward references are permitted. ORG is not
742 permitted within sections when outputting to object files. For the DECB 821 permitted within sections when outputting to object files. For target formats
743 target, each ORG directive after which output is generated will cause 822 that include address information (decb, hex, srec, and ihex), an ORG
744 a new preamble to be output. ORG is only used to determine the addresses 823 directive will re-start the address sequence within the output. When using
745 of symbols when the raw target is used. 824 the raw target format, ORG is used only to determine the addresses of symbols.
746 </para> 825 </para>
747 </listitem> 826 </listitem>
748 </varlistentry> 827 </varlistentry>
749 828
750 <varlistentry> 829 <varlistentry>