Mercurial > hg > index.cgi

annotate docs/manual.docbook.sgml @ 577:e49d24f4a9a5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Correct bug in the object file output code leading to stack corruption It turns out leaving a pointer to a stack allocated temporary in a persistent data structure is not conducive to correct program operation. Undo the export check setup in the object file output sequence so a pointer to stack allocated memory is not left hanging when the function returns. This seems to correct at least one mysterious crash bug, and possibly others. Thanks to Boisy Pitre for reporting the crash bug that led to this discovery, as well as a previous crash bug that likely has the same root cause. Additional thanks to Ciaran Anscomb whose debugger wielding wizardry revealed the exact location of this particular bit of unbrilliance.
author William Astle <lost@l-w.ca>
date Sat, 03 Aug 2024 14:30:06 -0600
parents d562ecd3ffd8
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2 <book>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3 <bookinfo>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
4 <title>LW Tool Chain</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
5 <author><firstname>William</firstname><surname>Astle</surname></author>
324
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
6 <author><firstname>LWTools Contributors</firstname><surname></surname></author>
518
b530ff19f7c0 Update copyright years for manual
William Astle <lost@l-w.ca>
parents: 517
diff changeset
7 <copyright><year>2009-2021</year><holder>William Astle and LWTools contributors</holder></copyright>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
8 </bookinfo>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
9 <chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
10
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
11 <title>Introduction</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
12
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
13 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
14 The LW tool chain provides utilities for building binaries for MC6809 and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
15 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
16 which support several styles of output.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
17 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
18
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
19 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
20 <title>History</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
21 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
22 For a long time, I have had an interest in creating an operating system for
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
23 the Coco3. I finally started working on that project around the beginning of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
24 2006. I had a number of assemblers I could choose from. Eventually, I settled
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
25 on one and started tinkering. After a while, I realized that assembler was not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
26 going to be sufficient due to lack of macros and issues with forward references.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
27 Then I tried another which handled forward references correctly but still did
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
28 not support macros. I looked around at other assemblers and they all lacked
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
29 one feature or another that I really wanted for creating my operating system.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
30 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
31
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
32 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
33 The solution seemed clear at that point. I am a fair programmer so I figured
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
34 I could write an assembler that would do everything I wanted an assembler to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
35 do. Thus the LWASM probject was born. After more than two years of on and off
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
36 work, version 1.0 of LWASM was released in October of 2008.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
37 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
38
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
39 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
40 As the aforementioned operating system project progressed further, it became
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
41 clear that while assembling the whole project through a single file was doable,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
42 it was not practical. When I found myself playing some fancy games with macros
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
43 in a bid to simulate sections, I realized I needed a means of assembling
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
44 source files separately and linking them later. This spawned a major development
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
45 effort to add an object file support to LWASM. It also spawned the LWLINK
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
46 project to provide a means to actually link the files.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
47 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
48
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
49 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
50
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
51 </chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
52
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
53 <chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
54 <title>Output Formats</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
55
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
56 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
57 The LW tool chain supports multiple output formats. Each format has its
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
58 advantages and disadvantages. Each format is described below.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
59 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
60
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
61 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
62 <title>Raw Binaries</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
63 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
64 A raw binary is simply a string of bytes. There are no headers or other
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
65 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
66 in the source code only serve to set the addresses that will be used for
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
67 symbols but otherwise have no direct impact on the resulting binary.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
68 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
69
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
70 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
71 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
72 <title>DECB Binaries</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
73
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
74 <para>A DECB binary is compatible with the LOADM command in Disk Extended
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
75 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
76 Color Basic. These binaries include the load address of the binary as well
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
77 as encoding an execution address. These binaries may contain multiple loadable
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
78 sections, each of which has its own load address.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
79
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
80 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
81 Each binary starts with a preamble. Each preamble is five bytes long. The
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
82 first byte is zero. The next two bytes specify the number of bytes to load
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
83 and the last two bytes specify the address to load the bytes at. Then, a
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
84 string of bytes follows. After this string of bytes, there may be another
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
85 preamble or a postamble. A postamble is also five bytes in length. The first
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
86 byte of the postamble is $FF, the next two are zero, and the last two are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
87 the execution address for the binary.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
88 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
89
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
90 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
91 Both LWASM and LWLINK can output this format.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
92 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
93 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
94
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
95 <section>
324
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
96 <title>ASCII Hexadecimal</title>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
97
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
98 <para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
99 This human-readable ASCII hexadecimal format consists of CR+LF terminated
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
100 lines of ASCII text. Each line has the following structure: a zero-padded
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
101 four-digit ASCII hex address, a colon separator, and one or more zero-padded
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
102 two-digit hex values separated by commas. ASCII Hexadecimal format favors
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
103 paragraph-aligned addresses (i.e. a least significant address nybble value
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
104 of zero). During output, the number of hex values on each line are adjusted
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
105 to align the address of the next line on a paragraph boundary. The sequence
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
106 of addresses in the ASCII Hexadecimal file directly follows that of the source
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
107 file; multiple ORG directives in the source code may result in out-of-sequence
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
108 addresses in the ASCII Hexadecimal output.
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
109 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
110
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
111 <para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
112 LWASM can output this format since version 4.10.
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
113 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
114 </section>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
115
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
116 <section>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
117 <title>Motorola S-Record</title>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
118
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
119 <para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
120 This ASCII format consists of a series of CR+LF terminated "records" of ASCII
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
121 text. Each record has the following structure: a start-of-record character
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
122 "S", an ASCII record type digit (0-9), a two-digit ASCII hex byte count, a
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
123 four-digit ASCII hex address, an optional sequence of two-digit ASCII hex data
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
124 values, and a two-digit ASCII hex checksum. The LW tool chain issues only S0,
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
125 S1, S5 and S9 record types. S1 records are limited to maximum of 16 data bytes
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
126 in length, and paragraph alignment of addresses is favored. The address
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
127 sequence of the S-Records directly follows that of the source file; multiple
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
128 ORG directives in the source code may result in out-of-sequence addresses in
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
129 the S-Record output.
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
130 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
131
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
132 <para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
133 Motorola S-Record format is a standard ASCII format accepted by most memory
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
134 device programming equipment. It is particularly useful when the assembled
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
135 code output is destined to reside within an EPROM or Flash memory device,
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
136 for example.
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
137 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
138
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
139 <para>
345
e95f07cbce4e Update manual to reflect lwlink support for S-record output
William Astle <lost@l-w.ca>
parents: 333
diff changeset
140 LWASM can output this format since version 4.10. LWLINK can output this format
e95f07cbce4e Update manual to reflect lwlink support for S-record output
William Astle <lost@l-w.ca>
parents: 333
diff changeset
141 since version 4.11.
324
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
142 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
143 </section>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
144
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
145 <section>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
146 <title>Intel Hex</title>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
147
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
148 <para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
149 This ASCII format consists of a series of CR+LF terminated "records" of ASCII
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
150 text. Each record has the following structure: a start-of-record character
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
151 ":", a two-digit ASCII hex byte count, a four-digit ASCII hex address, a two-
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
152 digit ASCII hex record type, an optional sequence of two-digit ASCII hex data
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
153 values, and a two-digit ASCII hex checksum. The LW tool chain issues only 00,
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
154 and 01 Intel Hex record types. Data records are limited to maximum of 16
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
155 data bytes in length, and paragraph alignment of addresses is favored. The
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
156 address sequence of the Intel hex records directly follows that of the source
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
157 file; multiple ORG directives in the source code may result in out-of-sequence
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
158 addresses in the Intel Hex output.
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
159 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
160
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
161 <para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
162 Intel Hex format is the other standard ASCII format accepted by most memory
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
163 device programming equipment, it and the Motorola S-Record format are used for
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
164 similar purposes.
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
165 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
166
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
167 <para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
168 LWASM can output this format since version 4.10.
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
169 </para>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
170 </section>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
171
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
172 <section>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
173 <title>OS9 Modules</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
174 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
175
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
176 Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
177 basically the same as for other assemblers. A module starts with the MOD
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
178 directive and ends with the EMOD directive. The OS9 directive is provided
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
179 as a shortcut for writing system calls.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
180
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
181 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
182
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
183 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
184
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
185 LWASM does NOT provide an OS9Defs file. You must provide your own. Also note
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
186 that the common practice of using "ifp1" around the inclusion of the OS9Defs
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
187 file is discouraged as it is pointless and can lead to unintentional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
188 problems and phasing errors. Because LWASM reads each file exactly once,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
189 there is no benefit to restricting the inclusion to the first assembly pass.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
190
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
191 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
192
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
193 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
194
143
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
195 As of version 4.5, LWASM also implements the standard data/code address
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
196 streams for OS9 modules. That means that between MOD and EMOD, any RMB,
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
197 RMD, RMQ, or equivalent directives will move the data address ahead and
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
198 leave the code address unmodified. Outside of an actual module, both the
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
199 code and data addresses are moved ahead equally. That last bit is critical
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
200 to understand because it means any directives that follow an EMOD directive
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
201 may have different results than other assemblers.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
202
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
203 </para>
143
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
204 <para>
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
205
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
206 Additionally, within a module body, the ORG directive sets only the data
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
207 address, not the code address. However, outside a module body, ORG sets both
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
208 addresses.
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
209
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
210 </para>
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
211
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
212 <para>
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
213 Both code and data addresses are reset to 0 by the MOD directive.
42a7a16a058f Documented the addition of data/code address streams for OS9 modules.
lost@l-w.ca
parents: 120
diff changeset
214 </para>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
215
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
216 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
217
152
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
218 As of version 4.5, LWLINK also supports creation of OS9 modules.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
219
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
220 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
221 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
222
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
223 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
224 <title>Object Files</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
225 <para>LWASM supports generating a proprietary object file format which is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
226 described in <xref linkend="objchap">. LWLINK is then used to link these
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
227 object files into a final binary in any of LWLINK's supported binary
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
228 formats.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
229
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
230 <para>Object files also support the concept of sections which are not valid
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
231 for other output types. This allows related code from each object file
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
232 linked to be collapsed together in the final binary.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
233
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
234 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
235 Object files are very flexible in that they allow references that are not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
236 known at assembly time to be resolved at link time. However, because the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
237 addresses of such references are not known at assembly time, there is no way
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
238 for the assembler to deduce that an eight bit addressing mode is possible.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
239 That means the assember will default to using sixteen bit addressing
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
240 whenever an external or cross-section reference is used.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
241 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
242
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
243 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
244 As of LWASM 2.4, it is possible to force direct page addressing for an
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
245 external reference. Care must be taken to ensure the resulting addresses
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
246 are really in the direct page since the linker does not know what the direct
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
247 page is supposed to be and does not emit errors for byte overflows.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
248 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
249
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
250 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
251 It is also possible to use external references in an eight bit immediate
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
252 mode instruction. In this case, only the low order eight bits will be used.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
253 Again, no byte overflows will be flagged.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
254 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
255
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
256
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
257 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
258
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
259 </chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
260
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
261 <chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
262 <title>LWASM</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
263 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
264 The LWTOOLS assembler is called LWASM. This chapter documents the various
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
265 features of the assembler. It is not, however, a tutorial on 6x09 assembly
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
266 language programming.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
267 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
268
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
269 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
270 <title>Command Line Options</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
271 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
272 The binary for LWASM is called "lwasm". Note that the binary is in lower
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
273 case. lwasm takes the following command line arguments.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
274 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
275
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
276 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
277
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
278 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
279 <term><option>--6309</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
280 <term><option>-3</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
281 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
282 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
283 This will cause the assembler to accept the additional instructions available
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
284 on the 6309 processor. This is the default mode; this option is provided for
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
285 completeness and to override preset command arguments.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
286 </para>
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
287 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
288 This option is the same as if the first line of the source code is "PRAGMA 6309".
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
289 </para>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
290 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
291 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
292
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
293 <varlistentry>
333
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
294 <term><option>--6800compat</option></term>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
295 <listitem>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
296 <para>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
297 This is equivalent to <option>--pragma=6800compat</option>.</para>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
298 <para>This will enable recognition of 6800 compatibility instructions.</para>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
299 </listitem>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
300 </varlistentry>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
301
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
302 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
303 <term><option>--6809</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
304 <term><option>-9</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
305 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
306 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
307 This will cause the assembler to reject instructions that are only available
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
308 on the 6309 processor. This actually has the effect of starting the assembler
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
309 as though the first line of the source is "PRAGMA 6809".
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
310 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
311 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
312 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
313
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
314 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
315 <term><option>--decb</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
316 <term><option>-b</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
317 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
318 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
319 Select the DECB output format target. Equivalent to <option>--format=decb</option>.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
320 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
321 <para>While this is the default output format currently, it is not safe to rely
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
322 on that fact. Future versions may have different defaults. It is also trivial
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
323 to modify the source code to change the default. Thus, it is recommended to specify
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
324 this option if you need DECB output.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
325 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
326 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
327
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
328 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
329 <term><option>--format=type</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
330 <term><option>-f type</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
331 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
332 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
333 Select the output format. Valid values are <option>obj</option> for the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
334 object file target, <option>decb</option> for the DECB LOADM format,
324
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
335 <option>os9</option> for creating OS9 modules, <option>raw</option> for
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
336 a raw binary, <option>hex</option> for ASCII hexadecminal format,
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
337 <option>srec</option> for Motorola S-Record format, and <option>ihex</option>
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
338 for Intel Hex format.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
339 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
340 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
341 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
342
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
343 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
344 <term><option>--list[=file]</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
345 <term><option>-l[file]</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
346 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
347 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
348 Cause LWASM to generate a listing. If <option>file</option> is specified,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
349 the listing will go to that file. Otherwise it will go to the standard output
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
350 stream. By default, no listing is generated. Unless <option>--symbols</option>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
351 is specified, the list will not include the symbol table.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
352 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
353 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
354 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
355
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
356 <varlistentry>
488
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
357 <term><option>--symbol-dump[=file]</option></term>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
358 <listitem>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
359 <para>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
360 Cause LWASM to output the global symbol table in assembly source format. If
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
361 <option>file</option> is specified, the table output will go to the specified
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
362 file. Otherwise, it will go to the standard output stream. Local symbols will
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
363 not be included. Incomplete symbols will be defined to zero with a comment
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
364 indicating incompleteness. Symbols defined with SET will also be listed using
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
365 SET in the symbol dump. However, if the symbol is defined multiple times, the
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
366 order of the definitions in the dump file is undefined.
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
367 </para>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
368 </listitem>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
369 </varlistentry>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
370
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
371 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
372 <term><option>--symbols</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
373 <term><option>-s</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
374 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
375 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
376 Causes LWASM to generate a list of symbols when generating a listing.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
377 It has no effect unless a listing is being generated.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
378 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
379 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
380 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
381
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
382 <varlistentry>
369
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
383 <term><option>--symbols-nolocals</option></term>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
384 <listitem>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
385 <para>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
386 Behaves just like <option>--symbols</option> but with local labels omitted.
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
387 </para>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
388 </listitem>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
389 </varlistentry>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
390
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
391 <varlistentry>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
392 <term><option>--map=FILE</option></term>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
393 <listitem>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
394 <para>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
395
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
396 This option generates a map file which can be used by debuggers and monitors to provide symbol information. A map file may be created independent of a listing file. (Patches are pending for MAME and exec09.)
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
397
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
398 </para>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
399 </listitem>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
400 </varlistentry>
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
401
682524a1f32f Updated documentation for --symbols-nolocals and --map
William Astle <lost@l-w.ca>
parents: 348
diff changeset
402 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
403 <term><option>--obj</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
404 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
405 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
406 Select the proprietary object file format as the output target.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
407 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
408 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
409 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
410
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
411 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
412 <term><option>--output=FILE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
413 <term><option>-o FILE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
414 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
415 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
416 This option specifies the name of the output file. If not specified, the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
417 default is <option>a.out</option>.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
418 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
419 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
420 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
421
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
422 <varlistentry>
488
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
423 <term><option>--no-output</option></term>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
424 <listitem>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
425 <para>Do assembly as usual but suppress generation of the output file.</para>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
426 </listitem>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
427 </varlistentry>
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
428
94bbdb2890b7 Update documentation for new options
William Astle <lost@l-w.ca>
parents: 472
diff changeset
429 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
430 <term><option>--pragma=pragma</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
431 <term><option>-p pragma</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
432 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
433 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
434 Specify assembler pragmas. Multiple pragmas are separated by commas. The
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
435 pragmas accepted are the same as for the PRAGMA assembler directive described
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
436 below.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
437 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
438 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
439 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
440
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
441 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
442 <term><option>--raw</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
443 <term><option>-r</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
444 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
445 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
446 Select raw binary as the output target.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
447 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
448 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
449 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
450
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
451 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
452 <term><option>--includedir=path</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
453 <term><option>-I path</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
454 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
455 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
456 Add <option>path</option> to the end of the include path.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
457 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
458 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
459 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
460
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
461 <varlistentry>
231
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
462 <term><option>--define=SYM[=VAL]</option></term>
245
0bc1c88fe776 Fix typo in documentation of lwasm --define switch.
William Astle <lost@l-w.ca>
parents: 236
diff changeset
463 <term><option>-D SYM[=VAL]</option></term>
231
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
464 <listitem>
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
465 <para>
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
466 Pre-defines the symbol SYM as either the specified VAL. If VAL is omitted,
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
467 the symbol is defined as 1. The symbol will be defined as though it were
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
468 defined using the SET directive in the assembly source. That means it can
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
469 be overridden by a SET directive within the source code. Attempting to
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
470 redefine SYM using EQU will result in a multiply defined symbol error.
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
471 </para>
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
472 </listitem>
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
473 </varlistentry>
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
474
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
475 <varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
476 <term><option>-t WIDTH</option></term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
477 <term><option>--tabs=WIDTH</option></term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
478 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
479 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
480 Specifies the handling of tabs in listing files. <option>--tabs=0</option>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
481 disables tab expansion. <option>--tabs=8</option> is the default setting.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
482 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
483 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
484 </varlistentry>
231
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
485
2cc599f1bebf Added --define to lwasm documentation.
William Astle <lost@l-w.ca>
parents: 210
diff changeset
486 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
487 <term><option>--help</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
488 <term><option>-?</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
489 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
490 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
491 Present a help screen describing the command line options.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
492 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
493 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
494 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
495
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
496 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
497 <term><option>--usage</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
498 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
499 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
500 Provide a summary of the command line options.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
501 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
502 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
503 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
504
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
505 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
506 <term><option>--version</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
507 <term><option>-V</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
508 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
509 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
510 Display the software version.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
511 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
512 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
513 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
514
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
515 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
516 <term><option>--debug</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
517 <term><option>-d</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
518 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
519 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
520 Increase the debugging level. Only really useful to people hacking on the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
521 LWASM source code itself.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
522 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
523 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
524 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
525
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
526 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
527
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
528 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
529
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
530 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
531 <title>Dialects</title>
333
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
532
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
533 <para> LWASM supports all documented MC6809 instructions as defined by
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
534 Motorola. By default, this does not include any MC6800 compatibility
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
535 instructions. As of LWASM 4.11, those compatibility instructions can be
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
536 enabled using the <parameter>--6800compat</parameter> option or the
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
537 <parameter>6800compat</parameter> pragma. It also supports all known HD6309
544
f12c767c363e Fix typo in manual.
William Astle <lost@l-w.ca>
parents: 533
diff changeset
538 instructions. While there is general agreement on the mnemonics for most
333
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
539 of the 6309 instructions, there is some variance with the block transfer
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
540 instructions. TFM for all four variations seems to have gained the most
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
541 traction and, thus, this is the form that is recommended for LWASM.
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
542 However, it also supports COPY, COPY-, IMP, EXP, TFRP, TFRM, TFRS, and TFRR.
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
543 It further adds COPY+ as a synomym for COPY, IMPLODE for IMP, and EXPAND for
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
544 EXP. </para>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
545
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
546 <para>By default, LWASM accepts 6309 instructions. However, using the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
547 <parameter>--6809</parameter> parameter, you can cause it to throw errors on
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
548 6309 instructions instead.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
549
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
550 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
551 The standard addressing mode specifiers are supported. These are the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
552 hash sign ("#") for immediate mode, the less than sign ("&lt;") for forced
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
553 eight bit modes, and the greater than sign ("&gt;") for forced sixteen bit modes.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
554 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
555
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
556 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
557 Additionally, LWASM supports using the asterisk ("*") to indicate
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
558 base page addressing. This should not be used in hand-written source code,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
559 however, because it is non-standard and may or may not be present in future
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
560 versions of LWASM.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
561 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
562
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
563 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
564
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
565 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
566 <title>Source Format</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
567
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
568 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
569 LWASM accepts plain text files in a relatively free form. It can handle
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
570 lines terminated with CR, LF, CRLF, or LFCR which means it should be able
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
571 to assemble files on any platform on which it compiles.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
572 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
573 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
574 Each line may start with a symbol. If a symbol is present, there must not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
575 be any whitespace preceding it. It is legal for a line to contain nothing
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
576 but a symbol.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
577 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
578 The op code is separated from the symbol by whitespace. If there is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
579 no symbol, there must be at least one white space character preceding it.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
580 If applicable, the operand follows separated by whitespace. Following the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
581 opcode and operand is an optional comment.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
582 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
583
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
584 <para> It is important to note that operands cannot contain any whitespace
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
585 except in the case of delimited strings. This is because the first
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
586 whitespace character will be interpreted as the separator between the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
587 operand column and the comment. This behaviour is required for approximate
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
588 source compatibility with other 6x09 assemblers. </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
589
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
590 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
591 A comment can also be introduced with a * or a ;. The comment character is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
592 optional for end of statement comments. However, if a symbol is the only
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
593 thing present on the line other than the comment, the comment character is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
594 mandatory to prevent the assembler from interpreting the comment as an opcode.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
595 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
596
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
597 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
598 For compatibility with the output generated by some C preprocessors, LWASM
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
599 will also ignore lines that begin with a #. This should not be used as a general
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
600 comment character, however.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
601 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
602
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
603 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
604 The opcode is not treated case sensitively. Neither are register names in
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
605 the operand fields. Symbols, however, are case sensitive.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
606 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
607
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
608 <para> As of version 2.6, LWASM supports files with line numbers. If line
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
609 numbers are present, the line must start with a digit. The line number
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
610 itself must consist only of digits. The line number must then be followed
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
611 by either the end of the line or exactly one white space character. After
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
612 that white space character, the lines are interpreted exactly as above.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
613 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
614
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
615 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
616
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
617 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
618 <title>Symbols</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
619
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
620 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
621 Symbols have no length restriction. They may contain letters, numbers, dots,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
622 dollar signs, and underscores. They must start with a letter, dot, or
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
623 underscore.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
624 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
625
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
626 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
627 LWASM also supports the concept of a local symbol. A local symbol is one
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
628 which contains either a "?" or a "@", which can appear anywhere in the symbol.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
629 The scope of a local symbol is determined by a number of factors. First,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
630 each included file gets its own local symbol scope. A blank line will also
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
631 be considered a local scope barrier. Macros each have their own local symbol
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
632 scope as well (which has a side effect that you cannot use a local symbol
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
633 as an argument to a macro). There are other factors as well. In general,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
634 a local symbol is restricted to the block of code it is defined within.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
635 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
636
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
637 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
638 By default, unless assembling to the os9 target, a "$" in the symbol will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
639 also make it local. This can be controlled by the "dollarlocal" and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
640 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, for
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
641 the os9 target, a "$" in the symbol will not make it considered local while
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
642 for all other targets it will.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
643 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
644
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
645 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
646
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
647 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
648 <title>Numbers and Expressions</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
649 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
650
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
651 Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
652 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B".
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
653 Octal numbers may be prefixed with "@" or suffixed with "Q", "q", "O", or
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
654 "o". Hexadecimal numbers may be prefixed with "$", "0x" or "0X", or suffixed
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
655 with "H". No prefix or suffix is required for decimal numbers but they can
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
656 be prefixed with "&amp;" if desired. Any constant which begins with a letter
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
657 must be expressed with the correct prefix base identifier or be prefixed
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
658 with a 0. Thus hexadecimal FF would have to be written either 0FFH or $FF.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
659 Numbers are not case sensitive.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
660
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
661 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
662
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
663 <para> A symbol may appear at any point where a number is acceptable. The
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
664 special symbol "*" can be used to represent the starting address of the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
665 current source line within expressions. </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
666
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
667 <para>The ASCII value of a character can be included by prefixing it with a
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
668 single quote ('). The ASCII values of two characters can be included by
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
669 prefixing the characters with a quote (").</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
670
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
671 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
672
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
673 LWASM supports the following basic binary operators: +, -, *, /, and %.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
674 These represent addition, subtraction, multiplication, division, and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
675 modulus. It also supports unary negation and unary 1's complement (- and ^
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
676 respectively). It is also possible to use ~ for the unary 1's complement
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
677 operator. For completeness, a unary positive (+) is supported though it is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
678 a no-op. LWASM also supports using |, &, and ^ for bitwise or, bitwise and,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
679 and bitwise exclusive or respectively.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
680
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
681 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
682
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
683 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
684
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
685 Operator precedence follows the usual rules. Multiplication, division, and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
686 modulus take precedence over addition and subtraction. Unary operators take
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
687 precedence over binary operators. Bitwise operators are lower precdence
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
688 than addition and subtraction. To force a specific order of evaluation,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
689 parentheses can be used in the usual manner.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
690
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
691 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
692
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
693 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
694
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
695 As of LWASM 2.5, the operators && and || are recognized for boolean and and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
696 boolean or respectively. They will return either 0 or 1 (false or true).
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
697 They have the lowest precedence of all the binary operators.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
698
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
699 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
700
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
701 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
702
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
703 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
704 <title>Assembler Directives</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
705 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
706 Various directives can be used to control the behaviour of the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
707 assembler or to include non-code/data in the resulting output. Those directives
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
708 that are not described in detail in other sections of this document are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
709 described below.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
710 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
711
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
712 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
713 <title>Data Directives</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
714 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
715 <varlistentry><term>FCB <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
716 <term>.DB <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
717 <term>.BYTE <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
718 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
719 <para>Include one or more constant bytes (separated by commas) in the output.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
720 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
721 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
722
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
723 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
724 <term>FDB <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
725 <term>.DW <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
726 <term>.WORD <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
727 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
728 <para>Include one or more words (separated by commas) in the output.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
729 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
730 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
731
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
732 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
733 <term>FQB <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
734 <term>.QUAD <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
735 <term>.4BYTE <parameter>expr[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
736 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
737 <para>Include one or more double words (separated by commas) in the output.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
738 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
739 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
740
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
741 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
742 <term>FCC <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
743 <term>.ASCII <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
744 <term>.STR <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
745 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
746 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
747 Include a string of text in the output. The first character of the operand
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
748 is the delimiter which must appear as the last character and cannot appear
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
749 within the string. The string is included with no modifications>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
750 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
751 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
752 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
753
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
754 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
755 <term>FCN <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
756 <term>.ASCIZ <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
757 <term>.STRZ <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
758 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
759 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
760 Include a NUL terminated string of text in the output. The first character of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
761 the operand is the delimiter which must appear as the last character and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
762 cannot appear within the string. A NUL byte is automatically appended to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
763 the string.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
764 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
765 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
766 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
767
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
768 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
769 <term>FCS <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
770 <term>.ASCIS <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
771 <term>.STRS <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
772 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
773 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
774 Include a string of text in the output with bit 7 of the final byte set. The
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
775 first character of the operand is the delimiter which must appear as the last
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
776 character and cannot appear within the string.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
777 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
778 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
779 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
780
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
781 <varlistentry><term>ZMB <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
782 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
783 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
784 Include a number of NUL bytes in the output. The number must be fully resolvable
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
785 during pass 1 of assembly so no forward or external references are permitted.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
786 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
787 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
788 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
789
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
790 <varlistentry><term>ZMD <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
791 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
792 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
793 Include a number of zero words in the output. The number must be fully
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
794 resolvable during pass 1 of assembly so no forward or external references are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
795 permitted.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
796 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
797 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
798 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
799
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
800 <varlistentry><term>ZMQ <parameter>expr<parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
801 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
802 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
803 Include a number of zero double-words in the output. The number must be fully
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
804 resolvable during pass 1 of assembly so no forward or external references are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
805 permitted.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
806 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
807 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
808 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
809
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
810 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
811 <term>RMB <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
812 <term>.BLKB <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
813 <term>.DS <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
814 <term>.RS <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
815 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
816 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
817 Reserve a number of bytes in the output. The number must be fully resolvable
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
818 during pass 1 of assembly so no forward or external references are permitted.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
819 The value of the bytes is undefined.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
820 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
821 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
822 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
823
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
824 <varlistentry><term>RMD <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
825 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
826 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
827 Reserve a number of words in the output. The number must be fully
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
828 resolvable during pass 1 of assembly so no forward or external references are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
829 permitted. The value of the words is undefined.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
830 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
831 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
832 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
833
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
834 <varlistentry><term>RMQ <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
835 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
836 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
837 Reserve a number of double-words in the output. The number must be fully
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
838 resolvable during pass 1 of assembly so no forward or external references are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
839 permitted. The value of the double-words is undefined.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
840 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
841 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
842 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
843
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
844 <varlistentry>
565
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
845 <term>INCLUDEBIN <parameter>filename</parameter>[,<parameter>start</parameter>[,<parameter>length</parameter>]]</term>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
846 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
847 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
848 Treat the contents of <parameter>filename</parameter> as a string of bytes to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
849 be included literally at the current assembly point. This has the same effect
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
850 as converting the file contents to a series of FCB statements and including
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
851 those at the current assembly point.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
852 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
853
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
854 <para> If <parameter>filename</parameter> beings with a /, the file name
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
855 will be taken as absolute. Otherwise, the current directory will be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
856 searched followed by the search path in the order specified.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
857
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
858 <para> Please note that absolute path detection including drive letters will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
859 not function correctly on Windows platforms. Non-absolute inclusion will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
860 work, however.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
861
565
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
862 <para> The optional <parameter>start</parameter> parameter allows you to set
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
863 the byte offset to start reading from the binary file. Positive values are
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
864 from the beginning of the file, negative values are from the end of the file.</para>
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
865
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
866 <para> The optional <parameter>length</parameter> parameter allows you to set
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
867 the number of bytes read from the binary file. If missing, then the file is
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
868 read to the end.</para>
fc072f6cde09 Update documentation to reflect includebin offset/length feature
William Astle <lost@l-w.ca>
parents: 563
diff changeset
869
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
870 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
871 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
872
254
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
873 <varlistentry>
450
6b19418c465c Correct documentation of FILL pseudo op
William Astle <lost@l-w.ca>
parents: 440
diff changeset
874 <term>FILL <parameter>byte</parameter>,<parameter>size</parameter></term>
254
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
875 <listitem>
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
876
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
877 <para>
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
878 Insert <parameter>size</parameter> bytes of <parameter>byte</parameter>.
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
879 </para>
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
880
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
881 </listitem>
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
882 </varlistentry>
155799f6cfa5 Add documentation for the FILL pseudo operation
William Astle <lost@l-w.ca>
parents: 253
diff changeset
883
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
884 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
885
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
886 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
887
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
888 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
889 <title>Address Definition</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
890 <para>The directives in this section all control the addresses of symbols
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
891 or the assembly process itself.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
892
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
893 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
894 <varlistentry><term>ORG <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
895 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
896 <para>Set the assembly address. The address must be fully resolvable on the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
897 first pass so no external or forward references are permitted. ORG is not
324
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
898 permitted within sections when outputting to object files. For target formats
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
899 that include address information (decb, hex, srec, and ihex), an ORG
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
900 directive will re-start the address sequence within the output. When using
b30091890d62 Add documentation of the new hex output formats.
William Astle <lost@l-w.ca>
parents: 316
diff changeset
901 the raw target format, ORG is used only to determine the addresses of symbols.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
902 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
903 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
904 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
905
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
906 <varlistentry>
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
907 <term>REORG</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
908 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
909 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
910 Sets the assembly address to the value it had immediately prior to the
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
911 previous ORG statement. It is used to continue assembly after some
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
912 specification that required an additional ORG. This directive is primarily
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
913 intended for MACRO-80c compatibility. Consider using alternatives in
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
914 modern code.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
915 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
916 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
917 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
918
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
919 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
920 <term><parameter>sym</parameter> EQU <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
921 <term><parameter>sym</parameter> = <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
922 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
923 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
924 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
925 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
926
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
927 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
928 <term><parameter>sym</parameter> SET <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
929 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
930 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
931 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
932 is used for all instances. Use of the symbol before the first SET statement
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
933 that sets its value is undefined.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
934 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
935 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
936
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
937 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
938 <term>SETDP <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
939 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
940 <para>Inform the assembler that it can assume the DP register contains
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
941 <parameter>expr</parameter>. This directive is only advice to the assembler
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
942 to determine whether an address is in the direct page and has no effect
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
943 on the contents of the DP register. The value must be fully resolved during
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
944 the first assembly pass because it affects the sizes of subsequent instructions.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
945 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
946 <para>This directive has no effect in the object file target.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
947 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
948 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
949 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
950
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
951 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
952 <term>ALIGN <parameter>expr</parameter>[,<parameter>value</parameter>]</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
953 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
954
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
955 <para>Force the current assembly address to be a multiple of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
956 <parameter>expr</parameter>. If <parameter>value</parameter> is not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
957 specified, a series of NUL bytes is output to force the alignment, if
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
958 required. Otherwise, the low order 8 bits of <parameter>value</parameter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
959 will be used as the fill. The alignment value must be fully resolved on the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
960 first pass because it affects the addresses of subsquent instructions.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
961 However, <parameter>value</parameter> may include forward references; as
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
962 long as it resolves to a constant for the second pass, the value will be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
963 accepted.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
964
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
965 <para>Unless <parameter>value</parameter> is specified as something like $12,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
966 this directive is not suitable for inclusion in the middle of actual code.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
967 The default padding value is $00 which is intended to be used within data
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
968 blocks. </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
969
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
970 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
971 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
972
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
973 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
974
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
975 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
976
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
977 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
978 <title>Conditional Assembly</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
979 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
980 Portions of the source code can be excluded or included based on conditions
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
981 known at assembly time. Conditionals can be nested arbitrarily deeply. The
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
982 directives associated with conditional assembly are described in this section.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
983 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
984 <para>All conditionals must be fully bracketed. That is, every conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
985 statement must eventually be followed by an ENDC at the same level of nesting.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
986 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
987 <para>Conditional expressions are only evaluated on the first assembly pass.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
988 It is not possible to game the assembly process by having a conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
989 change its value between assembly passes. Due to the underlying architecture
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
990 of LWASM, there is no possible utility to IFP1 and IFP2, nor can they, as of LWASM 3.0, actually
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
991 be implemented meaningfully. Thus there is not and never will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
992 be any equivalent of IFP1 or IFP2 as provided by other assemblers. Use of those opcodes
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
993 will throw a warning and be ignored.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
994
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
995 <para>It is important to note that if a conditional does not resolve to a constant
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
996 during the first parsing pass, an error will be thrown. This is unavoidable because the assembler
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
997 must make a decision about which source to include and which source to exclude at this stage.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
998 Thus, expressions that work normally elsewhere will not work for conditions.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
999
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1000 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1001 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1002 <term>IFEQ <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1003 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1004 <para>If <parameter>expr</parameter> evaluates to zero, the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1005 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1006 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1007 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1008 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1009
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1010 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1011 <term>IFNE <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1012 <term>IF <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1013 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1014 <para>If <parameter>expr</parameter> evaluates to a non-zero value, the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1015 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1016 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1017 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1018 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1019
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1020 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1021 <term>IFGT <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1022 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1023 <para>If <parameter>expr</parameter> evaluates to a value greater than zero, the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1024 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1025 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1026 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1027 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1028
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1029 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1030 <term>IFGE <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1031 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1032 <para>If <parameter>expr</parameter> evaluates to a value greater than or equal to zero, the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1033 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1034 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1035 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1036 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1037
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1038 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1039 <term>IFLT <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1040 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1041 <para>If <parameter>expr</parameter> evaluates to a value less than zero, the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1042 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1043 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1044 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1045 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1046
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1047 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1048 <term>IFLE <parameter>expr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1049 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1050 <para>If <parameter>expr</parameter> evaluates to a value less than or equal to zero , the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1051 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1052 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1053 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1054 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1055
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1056 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1057 <term>IFDEF <parameter>sym</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1058 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1059 <para>If <parameter>sym</parameter> is defined at this point in the assembly
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1060 process, the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1061 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1062 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1063 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1064 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1065
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1066 <varlistentry>
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1067 <term>IFPRAGMA <parameter>pragma</parameter></term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1068 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1069 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1070 If <parameter>pragma</parameter> is in effect, the condition will be considered true.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1071 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1072 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1073 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1074
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1075
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1076 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1077 <term>IFNDEF <parameter>sym</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1078 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1079 <para>If <parameter>sym</parameter> is not defined at this point in the assembly
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1080 process, the conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1081 will be considered true.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1082 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1083 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1084 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1085
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1086 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1087 <term>ELSE</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1088 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1089 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1090 If the preceding conditional at the same level of nesting was false, the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1091 statements following will be assembled. If the preceding conditional at
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1092 the same level was true, the statements following will not be assembled.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1093 Note that the preceding conditional might have been another ELSE statement
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1094 although this behaviour is not guaranteed to be supported in future versions
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1095 of LWASM.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1096 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1097 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1098
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1099 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1100 <term>ENDC</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1101 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1102 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1103 This directive marks the end of a conditional construct. Every conditional
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1104 construct must end with an ENDC directive.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1105 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1106 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1107 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1108
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1109 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1110 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1111
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1112 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1113 <title>OS9 Target Directives</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1114
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1115 <para>This section includes directives that apply solely to the OS9
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1116 target.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1117
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1118 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1119
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1120 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1121 <term>OS9 <parameter>syscall</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1122 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1123 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1124
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1125 This directive generates a call to the specified system call. <parameter>syscall</parameter> may be an arbitrary expression.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1126
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1127 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1128 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1129 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1130
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1131 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1132 <term>MOD <parameter>size</parameter>,<parameter>name</parameter>,<parameter>type</parameter>,<parameter>flags</parameter>,<parameter>execoff</parameter>,<parameter>datasize</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1133 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1134 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1135
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1136 This tells LWASM that the beginning of the actual module is here. It will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1137 generate a module header based on the parameters specified. It will also
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1138 begin calcuating the module CRC.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1139
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1140 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1141
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1142 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1143
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1144 The precise meaning of the various parameters is beyond the scope of this
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1145 document since it is not a tutorial on OS9 module programming.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1146
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1147 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1148
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1149 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1150 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1151
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1152 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1153 <term>EMOD</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1154 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1155 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1156
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1157 This marks the end of a module and causes LWASM to emit the calculated CRC
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1158 for the module.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1159
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1160 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1161 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1162
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1163 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1164 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1165
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1166 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1167 <title>Miscelaneous Directives</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1168
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1169 <para>This section includes directives that do not fit into the other
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1170 categories.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1171
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1172 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1173
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1174 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1175 <term>INCLUDE <parameter>filename</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1176 <term>USE <parameter>filename</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1177
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1178 <listitem> <para> Include the contents of <parameter>filename</parameter> at
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1179 this point in the assembly as though it were a part of the file currently
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1180 being processed. Note that if whitespace appears in the name of the file,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1181 you must enclose <parameter>filename</parameter> in quotes.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1182 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1183
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1184 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1185 Note that the USE variation is provided only for compatibility with other
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1186 assemblers. It is recommended to use the INCLUDE variation.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1187
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1188 <para>If <parameter>filename</parameter> begins with a &quot;/&quot;, it is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1189 interpreted as an absolute path. If it does not, the search path will be used
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1190 to find the file. First, the directory containing the file that contains this
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1191 directive. (Includes within an included file are relative to the included file,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1192 not the file that included it.) If the file is not found there, the include path
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1193 is searched. If it is still not found, an error will be thrown. Note that the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1194 current directory as understood by your shell or operating system is not searched.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1195 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1196
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1197 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1198 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1199
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1200 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1201 <term>END <parameter>[expr]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1202 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1203 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1204 This directive causes the assembler to stop assembling immediately as though
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1205 it ran out of input. For the DECB target only, <parameter>expr</parameter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1206 can be used to set the execution address of the resulting binary. For all
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1207 other targets, specifying <parameter>expr</parameter> will cause an error.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1208 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1209 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1210 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1211
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1212 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1213 <term>ERROR <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1214 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1215 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1216 Causes a custom error message to be printed at this line. This will cause
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1217 assembly to fail. This directive is most useful inside conditional constructs
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1218 to cause assembly to fail if some condition that is known bad happens. Everything
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1219 from the directive to the end of the line is considered the error message.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1220 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1221 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1222 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1223
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1224 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1225 <term>WARNING <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1226 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1227 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1228 Causes a custom warning message to be printed at this line. This will not cause
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1229 assembly to fail. This directive is most useful inside conditional constructs
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1230 or include files to alert the programmer to a deprecated feature being used
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1231 or some other condition that may cause trouble later, but which may, in fact,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1232 not cause any trouble.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1233 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1234 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1235 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1236
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1237 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1238 <term>.MODULE <parameter>string</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1239 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1240 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1241 This directive is ignored for most output targets. If the output target
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1242 supports encoding a module name into it, <parameter>string</parameter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1243 will be used as the module name.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1244 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1245 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1246 As of version 3.0, no supported output targets support this directive.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1247 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1248 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1249 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1250
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1251 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1252 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1253
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1254 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1255
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1256 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1257 <title>Macros</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1258 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1259 LWASM is a macro assembler. A macro is simply a name that stands in for a
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1260 series of instructions. Once a macro is defined, it is used like any other
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1261 assembler directive. Defining a macro can be considered equivalent to adding
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1262 additional assembler directives.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1263 </para>
60
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1264
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1265 <para>Macros may accept parameters. These parameters are referenced within a
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1266 macro by the a backslash ("\") followed by a digit 1 through 9 for the first
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1267 through ninth parameters. They may also be referenced by enclosing the
60
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1268 decimal parameter number in braces ("{num}"). The special expansion "\*"
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1269 translates to the exact parameter string, including all parameters, passed
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1270 to the macro. These parameter references are replaced with the verbatim text
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1271 of the parameter passed to the macro. A reference to a non-existent
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1272 parameter will be replaced by an empty string. Macro parameters are expanded
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1273 everywhere on each source line. That means the parameter to a macro could be
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1274 used as a symbol or it could even appear in a comment or could cause an
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1275 entire source line to be commented out when the macro is expanded. </para>
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1276
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1277 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1278 Parameters passed to a macro are separated by commas and the parameter list
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1279 is terminated by any whitespace. This means that neither a comma nor whitespace
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1280 may be included in a macro parameter.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1281 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1282 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1283 Macro expansion is done recursively. That is, within a macro, macros are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1284 expanded. This can lead to infinite loops in macro expansion. If the assembler
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1285 hangs for a long time while assembling a file that uses macros, this may be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1286 the reason.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1287
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1288 <para>Each macro expansion receives its own local symbol context which is not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1289 inherited by any macros called by it nor is it inherited from the context
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1290 the macro was instantiated in. That means it is possible to use local symbols
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1291 within macros without having them collide with symbols in other macros or
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1292 outside the macro itself. However, this also means that using a local symbol
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1293 as a parameter to a macro, while legal, will not do what it would seem to do
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1294 as it will result in looking up the local symbol in the macro's symbol context
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1295 rather than the enclosing context where it came from, likely yielding either
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1296 an undefined symbol error or bizarre assembly results.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1297 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1298 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1299 Note that there is no way to define a macro as local to a symbol context. All
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1300 macros are part of the global macro namespace. However, macros have a separate
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1301 namespace from symbols so it is possible to have a symbol with the same name
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1302 as a macro.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1303 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1304
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1305 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1306 Macros are defined only during the first pass. Macro expansion also
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1307 only occurs during the first pass. On the second pass, the macro
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1308 definition is simply ignored. Macros must be defined before they are used.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1309 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1310
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1311 <para>The following directives are used when defining macros.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1312
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1313 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1314 <varlistentry>
51
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1315 <term><parameter>macroname</parameter> MACRO [NOEXPAND]</term>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1316 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1317 <para>This directive is used to being the definition of a macro called
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1318 <parameter>macroname</parameter>. If <parameter>macroname</parameter> already
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1319 exists, it is considered an error. Attempting to define a macro within a
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1320 macro is undefined. It may work and it may not so the behaviour should not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1321 be relied upon.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1322 </para>
51
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1323
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1324 <para>If NOEXPAND is specified, the macro will not be expanded in a program
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1325 listing. Instead, all bytes emitted by all instructions within the macro
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1326 will appear to be emitted on the line where the macro is invoked, starting
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1327 at the address of the line of the invokation. If the macro uses ORG or other
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1328 directives that define symbols or change the assembly address, these things
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1329 will also be hidden (except in the symbol table) and the output bytes will
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1330 appear with incorrect address attribution. Thus, NOEXPAND should only be
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1331 used for macros that do not mess with the assembly address or otherwise
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1332 define symbols that should be visible.</para>
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents: 0
diff changeset
1333
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1334 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1335 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1336
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1337 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1338 <term>ENDM</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1339 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1340 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1341 This directive indicates the end of the macro currently being defined. It
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1342 causes the assembler to resume interpreting source lines as normal.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1343 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1344 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1345 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1346
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1347 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1348
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1349 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1350 <title>Structures</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1351 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1352
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1353 Structures are used to group related data in a fixed structure. A structure
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1354 consists a number of fields, defined in sequential order and which take up
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1355 specified size. The assembler does not enforce any means of access within a
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1356 structure; it assumes that whatever you are doing, you intended to do.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1357 There are two pseudo ops that are used for defining structures.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1358
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1359 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1360
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1361 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1362 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1363 <term><parameter>structname</parameter> STRUCT</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1364 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1365 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1366
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1367 This directive is used to begin the definition of a structure with name
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1368 <parameter>structname</parameter>. Subsequent statements all form part of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1369 the structure definition until the end of the structure is declared.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1370
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1371 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1372 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1373 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1374 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1375 <term>ENDSTRUCT</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1376 <term>ENDS</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1377 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1378 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1379 This directive ends the definition of the structure. ENDSTRUCT is the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1380 preferred form. Prior to version 3.0 of LWASM, ENDS was used to end a
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1381 section instead of a structure.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1382 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1383 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1384 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1385 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1386
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1387 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1388
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1389 Within a structure definition, only reservation pseudo ops are permitted.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1390 Anything else will cause an assembly error.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1391 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1392
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1393 <para> Once a structure is defined, you can reserve an area of memory in the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1394 same structure by using the structure name as the opcode. Structures can
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1395 also contain fields that are themselves structures. See the example
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1396 below.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1397
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1398 <programlisting>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1399 tstruct2 STRUCT
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1400 f1 rmb 1
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1401 f2 rmb 1
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1402 ENDSTRUCT
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1403
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1404 tstruct STRUCT
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1405 field1 rmb 2
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1406 field2 rmb 3
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1407 field3 tstruct2
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1408 ENDSTRUCT
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1409
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1410 ORG $2000
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1411 var1 tstruct
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1412 var2 tstruct2
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1413 </programlisting>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1414
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1415 <para>Fields are referenced using a dot (.) as a separator. To refer to the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1416 generic offset within a structure, use the structure name to the left of the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1417 dot. If referring to a field within an actual variable, use the variable's
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1418 symbol name to the left of the dot.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1419
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1420 <para>You can also refer to the actual size of a structure (or a variable
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1421 declared as a structure) using the special symbol sizeof{structname} where
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1422 structname will be the name of the structure or the name of the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1423 variable.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1424
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1425 <para>Essentially, structures are a shortcut for defining a vast number of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1426 symbols. When a structure is defined, the assembler creates symbols for the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1427 various fields in the form structname.fieldname as well as the appropriate
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1428 sizeof{structname} symbol. When a variable is declared as a structure, the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1429 assembler does the same thing using the name of the variable. You will see
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1430 these symbols in the symbol table when the assembler is instructed to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1431 provide a listing. For instance, the above listing will create the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1432 following symbols (symbol values in parentheses): tstruct2.f1 (0),
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1433 tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1434 (2), tstruct.field3 (5), tstruct.field3.f1 (5), tstruct.field3.f2 (6),
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1435 sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1436 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005},
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1437 var1.field3.f2 {$2006}, sizeof(var1.field3} (2), sizeof{var1} (7), var2
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1438 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2). </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1439
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1440 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1441
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1442 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1443 <title>Object Files and Sections</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1444 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1445 The object file target is very useful for large project because it allows
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1446 multiple files to be assembled independently and then linked into the final
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1447 binary at a later time. It allows only the small portion of the project
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1448 that was modified to be re-assembled rather than requiring the entire set
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1449 of source code to be available to the assembler in a single assembly process.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1450 This can be particularly important if there are a large number of macros,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1451 symbol definitions, or other metadata that uses resources at assembly time.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1452 By far the largest benefit, however, is keeping the source files small enough
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1453 for a mere mortal to find things in them.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1454 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1455
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1456 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1457 With multi-file projects, there needs to be a means of resolving references to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1458 symbols in other source files. These are known as external references. The
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1459 addresses of these symbols cannot be known until the linker joins all the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1460 object files into a single binary. This means that the assembler must be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1461 able to output the object code without knowing the value of the symbol. This
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1462 places some restrictions on the code generated by the assembler. For
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1463 example, the assembler cannot generate direct page addressing for instructions
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1464 that reference external symbols because the address of the symbol may not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1465 be in the direct page. Similarly, relative branches and PC relative addressing
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1466 cannot be used in their eight bit forms. Everything that must be resolved
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1467 by the linker must be assembled to use the largest address size possible to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1468 allow the linker to fill in the correct value at link time. Note that the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1469 same problem applies to absolute address references as well, even those in
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1470 the same source file, because the address is not known until link time.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1471 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1472
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1473 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1474 It is often desired in multi-file projects to have code of various types grouped
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1475 together in the final binary generated by the linker as well. The same applies
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1476 to data. In order for the linker to do that, the bits that are to be grouped
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1477 must be tagged in some manner. This is where the concept of sections comes in.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1478 Each chunk of code or data is part of a section in the object file. Then,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1479 when the linker reads all the object files, it coalesces all sections of the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1480 same name into a single section and then considers it as a unit.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1481 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1482
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1483 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1484 The existence of sections, however, raises a problem for symbols even
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1485 within the same source file. Thus, the assembler must treat symbols from
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1486 different sections within the same source file in the same manner as external
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1487 symbols. That is, it must leave them for the linker to resolve at link time,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1488 with all the limitations that entails.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1489 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1490
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1491 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1492 In the object file target mode, LWASM requires all source lines that
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1493 cause bytes to be output to be inside a section. Any directives that do
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1494 not cause any bytes to be output can appear outside of a section. This includes
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1495 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1496 makes no sense within a section because it is the linker that determines
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1497 the starting address of the section's code, not the assembler.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1498 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1499
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1500 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1501 All symbols defined globally in the assembly process are local to the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1502 source file and cannot be exported. All symbols defined within a section are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1503 considered local to the source file unless otherwise explicitly exported.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1504 Symbols referenced from external source files must be declared external,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1505 either explicitly or by asking the assembler to assume that all undefined
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1506 symbols are external.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1507 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1508
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1509 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1510 It is often handy to define a number of memory addresses that will be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1511 used for data at run-time but which need not be included in the binary file.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1512 These memory addresses are not initialized until run-time, either by the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1513 program itself or by the program loader, depending on the operating environment.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1514 Such sections are often known as BSS sections. LWASM supports generating
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1515 sections with a BSS attribute set which causes the section definition including
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1516 symbols exported from that section and those symbols required to resolve
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1517 references from the local file, but with no actual code in the object file.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1518 It is illegal for any source lines within a BSS flagged section to cause any
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1519 bytes to be output.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1520 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1521
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1522 <para>The following directives apply to section handling.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1523
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1524 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1525 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1526 <term>SECTION <parameter>name[,flags]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1527 <term>SECT <parameter>name[,flags]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1528 <term>.AREA <parameter>name[,flags]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1529 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1530 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1531 Instructs the assembler that the code following this directive is to be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1532 considered part of the section <parameter>name</parameter>. A section name
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1533 may appear multiple times in which case it is as though all the code from
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1534 all the instances of that section appeared adjacent within the source file.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1535 However, <parameter>flags</parameter> may only be specified on the first
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1536 instance of the section.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1537 </para>
168
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1538
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1539 <para><parameter>flags</parameter> is a comma separated list of flags. If a
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1540 flag is "bss", the section will be treated as a BSS section and no
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1541 statements that generate output are permitted.</para>
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1542
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1543 <para>If the flag is "constant",
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1544 the same restrictions apply as for BSS sections. Additionally, all symbols
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1545 defined in a constant section define absolute values and will not be
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1546 adjusted by the linker at link time. Constant sections cannot define
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1547 complex expressions for symbols; the value must be fully defined at assembly
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1548 time. Additionally, multiple instances of a constant section do not
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1549 coalesce into a single addressing unit; each instance starts again at offset
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1550 0.</para>
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1551
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1552 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1553 If the section name is "bss" or ".bss" in any combination of upper and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1554 lower case, the section is assumed to be a BSS section. In that case,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1555 the flag <parameter>!bss</parameter> can be used to override this assumption.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1556 </para>
168
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1557
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1558 <para> If the section name is "_constants" or "_constant", in any
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1559 combination of upper and lower case, the section is assumed to be a constant
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1560 section. This assumption can be overridden with the "!constant"
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1561 flag.</para>
1e0a0e6cd918 Documentation updates
lost@l-w.ca
parents: 152
diff changeset
1562
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1563 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1564 If assembly is already happening within a section, the section is implicitly
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1565 ended and the new section started. This is not considered an error although
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1566 it is recommended that all sections be explicitly closed.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1567 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1568 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1569 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1570
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1571 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1572 <term>ENDSECTION</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1573 <term>ENDSECT</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1574 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1575 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1576 This directive ends the current section. This puts assembly outside of any
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1577 sections until the next SECTION directive. ENDSECTION is the preferred form.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1578 Prior to version 3.0 of LWASM, ENDS could also be used to end a section but
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1579 as of version 3.0, it is now an alias for ENDSTRUCT instead.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1580 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1581 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1582
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1583 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1584 <term><parameter>sym</parameter> EXTERN</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1585 <term><parameter>sym</parameter> EXTERNAL</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1586 <term><parameter>sym</parameter> IMPORT</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1587 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1588 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1589 This directive defines <parameter>sym</parameter> as an external symbol.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1590 This directive may occur at any point in the source code. EXTERN definitions
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1591 are resolved on the first pass so an EXTERN definition anywhere in the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1592 source file is valid for the entire file. The use of this directive is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1593 optional when the assembler is instructed to assume that all undefined
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1594 symbols are external. In fact, in that mode, if the symbol is referenced
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1595 before the EXTERN directive, an error will occur.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1596 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1597 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1598 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1599
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1600 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1601 <term><parameter>sym</parameter> EXPORT</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1602 <term><parameter>sym</parameter> .GLOBL</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1603
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1604 <term>EXPORT <parameter>sym</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1605 <term>.GLOBL <parameter>sym</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1606
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1607 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1608 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1609 This directive defines <parameter>sym</parameter> as an exported symbol.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1610 This directive may occur at any point in the source code, even before the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1611 definition of the exported symbol.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1612 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1613 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1614 Note that <parameter>sym</parameter> may appear as the operand or as the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1615 statement's symbol. If there is a symbol on the statement, that will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1616 take precedence over any operand that is present.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1617 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1618 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1619
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1620 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1621
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1622 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1623 <term><parameter>sym</parameter> EXTDEP</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1624 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1625
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1626 <para>This directive forces an external dependency on
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1627 <parameter>sym</parameter>, even if it is never referenced anywhere else in
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1628 this file.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1629
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1630 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1631 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1632 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1633
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1634 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1635
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1636 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1637 <title>Assembler Modes and Pragmas</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1638 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1639 There are a number of options that affect the way assembly is performed.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1640 Some of these options can only be specified on the command line because
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1641 they determine something absolute about the assembly process. These include
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1642 such things as the output target. Other things may be switchable during
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1643 the assembly process. These are known as pragmas and are, by definition,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1644 not portable between assemblers.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1645 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1646
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1647 <para>LWASM supports a number of pragmas that affect code generation or
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1648 otherwise affect the behaviour of the assembler. These may be specified by
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1649 way of a command line option or by assembler directives. The directives
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1650 are as follows.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1651 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1652
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1653 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1654 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1655 <term>PRAGMA <parameter>pragma[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1656 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1657 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1658 Specifies that the assembler should bring into force all <parameter>pragma</parameter>s
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1659 specified. Any unrecognized pragma will cause an assembly error. The new
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1660 pragmas will take effect immediately. This directive should be used when
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1661 the program will assemble incorrectly if the pragma is ignored or not supported.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1662 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1663 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1664 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1665
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1666 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1667 <term>*PRAGMA <parameter>pragma[,...]</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1668 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1669 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1670 This is identical to the PRAGMA directive except no error will occur with
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1671 unrecognized or unsupported pragmas. This directive, by virtue of starting
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1672 with a comment character, will also be ignored by assemblers that do not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1673 support this directive. Use this variation if the pragma is not required
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1674 for correct functioning of the code.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1675 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1676 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1677 </varlistentry>
111
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1678
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1679 <varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1680 <term>*PRAGMAPUSH <parameter>pragma[,...]</parameter></term>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1681 <listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1682 <para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1683 This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1684 </para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1685
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1686 <para>This directive will not throw any errors for any reason.</para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1687
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1688 </listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1689 </varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1690
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1691 <varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1692 <term>*PRAGMAPOP <parameter>pragma[,...]</parameter></term>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1693 <listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1694 <para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1695 This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1696 </para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1697
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1698 <para>This directive will not throw any errors for any reason.</para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1699
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1700 </listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1701 </varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1702 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1703
207
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1704 <para>Each pragma supported has a positive version and a negative version.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1705 The positive version enables the pragma while the negative version disables
207
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1706 it. The negatitve version is simply the positive version with "no" prefixed
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1707 to it. For instance, "pragma" vs. "nopragma". When only one version is
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1708 listed below, its opposite can be obtained by prepending "no" if it is not
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1709 present or removing "no" from the beginning if it is present.</para>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1710
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1711 <para>Pragmas are not case sensitive.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1712
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1713 <variablelist>
333
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1714
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1715 <varlistentry>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1716 <term>6800compat</term>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1717 <listitem>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1718
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1719 <para>When in force, this pragma enables recognition of various
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1720 compatibility instructions useful when assembling 6800 code. These
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1721 compatibility instructions are assembled into equivalent 6809 instructions.
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1722 This mode also includes several analogous instructions which are not
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1723 strictly 6800 instructions but allow the similar style to be applied to 6809
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1724 specific features.</para>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1725
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1726 <para>Technically, a compliant 6809 assembler must recognize these
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1727 instructions by default since Motorola advertised the 6809 as being source
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1728 compatible with the 6800. However, most source code does not require this
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1729 compatibility and LWASM itself did not support these instructions prior to
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1730 version 4.11 so this mode is disabled by default.</para>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1731
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1732 </listitem>
507f442dc71e Add support for 6800 compatibility instructions.
William Astle <lost@l-w.ca>
parents: 324
diff changeset
1733
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1734 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1735
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1736 <varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1737 <term>6809</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1738 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1739 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1740 This pragma allows you to mark a section of code as 6809-only. In ths mode,
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1741 the assembler will throw an error if any 6309 instructions are used.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1742 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1743 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1744 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1745
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1746 <varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1747 <term>6309</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1748 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1749 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1750 This pragma enables the use of 6309 instructions and disables any 6809 specific
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1751 instructions. It also changes the cycle count listing output (if selected)
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1752 to display 6309 timings.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1753 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1754 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1755 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1756
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1757 <varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1758 <term>6809conv</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1759 <term>6309conv</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1760 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1761 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1762 These pragmas enable convenience instructions extending the 6809 and 6309
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1763 instruction sets respectively. For more information, see
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1764 <xref linkend="convinst">.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1765 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1766 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1767 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1768
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
1769
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1770 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1771 <term>index0tonone</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1772 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1773 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1774 When in force, this pragma enables an optimization affecting indexed addressing
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1775 modes. When the offset expression in an indexed mode evaluates to zero but is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1776 not explicity written as 0, this will replace the operand with the equivalent
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1777 no offset mode, thus creating slightly faster code. Because of the advantages
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1778 of this optimization, it is enabled by default.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1779 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1780 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1781 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1782
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1783 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1784 <term>cescapes</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1785 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1786 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1787 This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1788 have C-style escape sequences interpreted. The one departure from the official
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1789 spec is that unrecognized escape sequences will return either the character
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1790 immediately following the backslash or some undefined value. Do not rely
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1791 on the behaviour of undefined escape sequences.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1792 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1793 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1794 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1795
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1796 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1797 <term>importundefexport</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1798 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1799 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1800 This pragma is only valid for targets that support external references. When
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1801 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1802 to be exported is not defined. This is provided for compatibility with the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1803 output of gcc6809 and should not be used in hand written code. Because of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1804 the confusion this pragma can cause, it is disabled by default.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1805 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1806 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1807 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1808
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1809 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1810 <term>undefextern</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1811 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1812 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1813 This pragma is only valid for targets that support external references. When in
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1814 force, if the assembler sees an undefined symbol on the second pass, it will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1815 automatically define it as an external symbol. This automatic definition will
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1816 apply for the remainder of the assembly process, even if the pragma is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1817 subsequently turned off. Because this behaviour would be potentially surprising,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1818 this pragma defaults to off.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1819 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1820 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1821 The primary use for this pragma is for projects that share a large number of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1822 symbols between source files. In such cases, it is impractical to enumerate
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1823 all the external references in every source file. This allows the assembler
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1824 and linker to do the heavy lifting while not preventing a particular source
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1825 module from defining a local symbol of the same name as an external symbol
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1826 if it does not need the external symbol. (This pragma will not cause an
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1827 automatic external definition if there is already a locally defined symbol.)
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1828 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1829 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1830 This pragma will often be specified on the command line for large projects.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1831 However, depending on the specific dynamics of the project, it may be sufficient
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1832 for one or two files to use this pragma internally.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1833 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1834 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1835 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1836
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1837 <varlistentry>
253
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1838 <term>export</term>
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1839 <listitem>
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1840
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1841 <para>This pragma causes all symbols to be added to the export list
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1842 automatically. This is useful when a large number of symbols need to be
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1843 exported but you do not wish to include an EXPORT directive for all of them.
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1844 This is often useful on the command line but might be useful even inline
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1845 with the PRAGMA directive if a large number of symbols in a row are to be
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1846 exported.</para>
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1847
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1848 </listitem>
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1849 </varlistentry>
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1850
ed1009bce533 Document the "export" pragma
William Astle <lost@l-w.ca>
parents: 245
diff changeset
1851 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1852 <term>dollarlocal</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1853 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1854
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1855 <para>When set, a "$" in a symbol makes it local. When not set, "$" does not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1856 cause a symbol to be local. It is set by default except when using the OS9
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1857 target.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1858
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1859 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1860 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1861
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1862 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1863 <term>dollarnotlocal</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1864 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1865
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1866 <para> This is the same as the "dollarlocal" pragma except its sense is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1867 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1868 "nodollarlocal" and "dollarnotlocal" are equivalent. </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1869
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1870 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1871 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1872
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1873 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1874 <term>pcaspcr</term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1875 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1876
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1877 <para> Normally, LWASM makes a distinction between PC and PCR in program
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1878 counter relative addressing. In particular, the use of PC means an absolute
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1879 offset from PC while PCR causes the assembler to calculate the offset to the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1880 specified operand and use that as the offset from PC. By setting this
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1881 pragma, you can have PC treated the same as PCR. </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1882
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1883
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1884 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1885 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1886
60
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1887 <varlistentry>
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1888 <term>shadow</term>
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1889 <listitem>
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1890
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1891 <para>When this pragma is in effect, it becomes possible to define a macro
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1892 that matches an internal operation code. Thus, it makes it possible to
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1893 redefine either CPU instructions or pseudo operations. Because this feature
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1894 is of dubious utility, it is disabled by default.</para>
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1895
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1896 </listitem>
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1897 </varlistentry>
9ded7e6fc1b0 Updated documentation to include recently added features
lost@l-w.ca
parents: 51
diff changeset
1898
111
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1899 <varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1900 <term>nolist</term>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1901 <listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1902
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1903 <para>Lines where this pragma is in effect will not appear in the assembly
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1904 listing. Also, any symbols defined under this pragma will not show up in
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1905 the symbol list. This is most useful in include files to avoid spamming the
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1906 assembly listing with dozens, hundreds, or thousands of irrelevant
563
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1907 symbols. It is important to note that this pragma will not hide lines that
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1908 generate output to the binary.</para>
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1909
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1910 </listitem>
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1911 </varlistentry>
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1912
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1913 <varlistentry>
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1914 <term>nolistcode</term>
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1915 <listitem>
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1916
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1917 <para>Lines where this pragma is in effect will not appear in the assembly
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1918 listing. Also, any symbols defined under this pragma will not show up in
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1919 the symbol list. This is most useful in include files to avoid spamming the
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1920 assembly listing with dozens, hundreds, or thousands of irrelevant
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1921 symbols. Unlike "nolist", this pragma will hide lines that generate output
8c6c3363e18e Update manual to reflect pragma nolistcode and correct nolist semantics
William Astle <lost@l-w.ca>
parents: 544
diff changeset
1922 to the binary.</para>
111
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1923
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1924 </listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1925 </varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
1926
117
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1927 <varlistentry>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1928 <term>autobranchlength</term>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1929 <listitem>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1930
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1931 <para>One of the perennial annoyances for 6809 programmers is that the
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1932 mneumonics for the short and long branch instructions are different (bxx vs.
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1933 lbxx), which is at odds with the rest of the instruction set. This pragma
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1934 is a solution to those annoying byte overflow errors that short branch
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1935 instructions tend to aquire.</para>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1936
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1937 <para>When this pragma is in effect, which is not the default, whenever any
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1938 relative branch instruction is used, its size will be automatically
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1939 determined based on the actual distance to the destination. In other words,
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1940 one can write code with long or short branches everywhere and the assembler
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1941 will choose a size for the branch.</para>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1942
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1943 <para>Also, while this pragma is in effect, the > and < symbols can be used
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1944 to force the branch size, analogous to their use for other instructions with
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1945 < forcing 8 bit offsets and > forcing 16 bit offets.</para>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1946
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1947 <para>Because this pragma leads to source that is incompatible with other
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1948 assemblers, it is strongly recommended that it be invoked using the PRAGMA
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1949 directive within the source code rather than on the command line or via the
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1950 *PRAGMA directive. This way, an error will be raised if someone tries to
207
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1951 assemble the code under a different assembler.</para>
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1952
517
1faf14de9d04 Update manual to correctly reflect forwardrefmax behaviour
William Astle <lost@l-w.ca>
parents: 488
diff changeset
1953 <para>Note that if the "forwardrefmax" pragma is ineffect, as is the current
1faf14de9d04 Update manual to correctly reflect forwardrefmax behaviour
William Astle <lost@l-w.ca>
parents: 488
diff changeset
1954 default, this pragma will not behave as expected.</para>
1faf14de9d04 Update manual to correctly reflect forwardrefmax behaviour
William Astle <lost@l-w.ca>
parents: 488
diff changeset
1955
207
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1956 <varlistentry>
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1957 <term>nosymbolcase</term>
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1958 <term>symbolnocase</term>
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1959 <listitem>
117
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1960
207
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1961 <para>Any symbol defined while this pragma is in force will be treated as
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1962 case insensitive, regardless whether the pragma is in force when the symbol
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1963 is referenced.</para>
117
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1964
207
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1965 <para>It is important to note that this pragma will not work as expected in
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1966 all cases when using the object file assembly target. It is intended for
07e1fac76321 Added pragma to allow non case sensitive symbols
William Astle <lost@l-w.ca>
parents: 168
diff changeset
1967 use only when the assembler will be producing the final binary.</para>
117
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1968
210
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1969 <varlistentry>
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1970 <term>condundefzero</term>
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1971 <listitem>
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1972
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1973 <para>This pragma will cause the assembler to change the way it handles
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1974 symbols in conditional expressions. Ordinarily, any symbol that is not
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1975 defined prior to the conditional will throw an undefined symbol error. With
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1976 this pragma in effect, symbols that are not yet defined at the point the
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1977 conditional is encountered will be treated as zero.</para>
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1978
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1979 <para>This is not the default because it encourages poor code design. One
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1980 should use the "IFDEF" or "IFNDEF" conditionals to test for the presence of
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1981 a symbol.</para>
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1982
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1983 <para>It is important to note that if a symbol is defined but it does not
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1984 yet evaluate to a constant value at the point where the conditional appears,
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1985 the assembler will still complain about a non constant condition.</para>
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1986
5d969517db74 Added condundefzero pragma
William Astle <lost@l-w.ca>
parents: 207
diff changeset
1987
117
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1988 </listitem>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1989 </varlistentry>
8e2523061ce9 Document the new autobranchlength pragma
lost@l-w.ca
parents: 111
diff changeset
1990
347
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1991 <varlistentry>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1992 <term>forwardrefmax</term>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1993 <listitem>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1994
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1995 <para>This pragma will disable forward reference optimization completely.
517
1faf14de9d04 Update manual to correctly reflect forwardrefmax behaviour
William Astle <lost@l-w.ca>
parents: 488
diff changeset
1996 However, many source files, especially
347
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1997 those not using the PCR relative addressing modes, this optimization is
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1998 pointless since the assembler will almost certainly settle on a 16 bit
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
1999 offset or address. If all variables in the direct page are defined before
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2000 the main body of the code, the benefit of forward reference optimization
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2001 almost certainly vanishes completely. However, the cost of doing that
517
1faf14de9d04 Update manual to correctly reflect forwardrefmax behaviour
William Astle <lost@l-w.ca>
parents: 488
diff changeset
2002 optimization remains and can result in a very long assembly time. Because
1faf14de9d04 Update manual to correctly reflect forwardrefmax behaviour
William Astle <lost@l-w.ca>
parents: 488
diff changeset
2003 of this, "forwardrefmax" has been the default setting since version 4.14 of
1faf14de9d04 Update manual to correctly reflect forwardrefmax behaviour
William Astle <lost@l-w.ca>
parents: 488
diff changeset
2004 LWTOOLS. To turn it off, use "noforwardrefmax".</para>
347
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2005
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2006 <para>Enabling this pragma will cause all forward references to use the
575
d562ecd3ffd8 Fix typo in manual
William Astle <lost@l-w.ca>
parents: 565
diff changeset
2007 maximum offset or address size, much the same as EDTASM and other pure
347
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2008 two pass assemblers do. The side effect is that all line lengths and
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2009 symbol values are fully resolved after the initial parsing pass and the
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2010 amount of work to resolve everything becomes almost nil.</para>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2011
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2012 <para>While this pragma can be applied selectively to sections of source
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2013 code (use *PRAGMA if doing so and compatibility with other assemblers
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2014 is desired), it is likely more useful when provided as a command line
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2015 pragma.</para>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2016
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2017 <para>It should be noted that the presence or absence of this pragma
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2018 will not change the correctness of the generated code unless cycle counts
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2019 or byte counts are critical (which they usually are not). It also will
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2020 not override the operand size override prefixes (&lt; and &gt;). It only
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2021 applies when the assembler is left to guess what the operand size is.</para>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2022
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2023 </listitem>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2024 </varlistentry>
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2025
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2026 <varlistentry>
455
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2027 <term>operandsizewarning</term>
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2028 <listitem>
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2029
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2030 <para>Enabling this pragma will cause LWASM to show a warning when it
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2031 detects that a smaller addressing mode could be used for an instruction.
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2032 This is particularly useful for finding places where long branches are used
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2033 where short branches could be used instead. It will also show the warnings
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2034 for indexing offsets (regardless of whether the operand size is
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2035 forced).</para>
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2036
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2037 <para>As of LWASM 4.16, no other checks are performed.</para>
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2038
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2039 </listitem>
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2040 </varlistentry>
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2041
cad5937314cb Add operandsizewarning pragma
William Astle <lost@l-w.ca>
parents: 450
diff changeset
2042 <varlistentry>
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2043 <term>qrts</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2044 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2045 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2046
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2047 Enables the use of the ?RTS branch target. ?RTS is implemented to maintain
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2048 compatibility with the MACRO-80c assembler. It works by searching backward
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2049 in the code for an RTS instruction. If none is found, it inverts the branch
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2050 logic and inserts an RTS following the branch instruction. Below you can
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2051 see how a BMI (2B xx) has been assembled as a BPL *+1 (2A 01) to skip over an
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2052 inserted RTS (39).
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2053 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2054 <programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2055 1D1E 7D1D1D TST WHICH1
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2056 1D21 2A0139 BMI ?RTS
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2057 1D24 BD1D65 JSR INV
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2058 </programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2059 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2060 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2061
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2062 <varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2063 <term>m80ext</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2064 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2065 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2066
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2067 This pragma (along with pragma qrts) enables some uncommon behaviors to
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2068 accomodate The Micro Works MACRO-80c assembler from 1982. This assembler
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2069 was used by a number of notable TRS-80 Color Computer applications and the
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2070 goal of this pragma is to allow them to build identical binaries from
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2071 unmodified, vintage source code.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2072 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2073 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2074
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2075 In m80ext mode, the handling of the "END" pseudo-op changes when used inside
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2076 an include file. Instead of terminating all assembly, it merely stops
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2077 processing of the current include file (this behavior matches the original
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2078 Motorola 6809 assembler). In addition, loading an ASCII value with a single
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2079 quote (e.g., LDA #'N) is extended to 16-bit registers (e.g., LDD #'NO).
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2080 LWASM normally supports this via double quote and that is the proper use in
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2081 modern code. Finally, the FCC pseudo-op is extended to handle FCB-like
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2082 behavior after the closing delimiter:
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2083 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2084 <programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2085 FCC "Greetings from 1982",13,0
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2086 </programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2087 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2088 </varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2089
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2090
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2091
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2092 <varlistentry>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2093 <term>testmode</term>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2094 <listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2095 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2096
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2097 This pragma is intended for internal testing purposes. In testmode, the
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2098 assembler searches for a specially-formatted comment starting with a
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2099 semicolon followed by a period. Immediately afterward are a list of hex
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2100 bytes that the assembler is expected to generate. Likewise, if the
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2101 assembler is expected to throw an error or warning on a given line, you can
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2102 check by specifying "E:" followed by the error number. In this case the
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2103 error is ignored and the assembler continues ignoring the line in question.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2104
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2105 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2106 <programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2107 1D1E 7D1D1D TST WHICH1 ;.7d1d1d
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2108 1D21 2A0139 BMI ?RTS ;.2a0139
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2109 1D24 1D24 FDB * ;.1d24
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2110 1D26 xyz INV ;.E:32 (Error 32 is "Bad opcode")
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2111 </programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2112 </listitem>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2113 </varlistentry>
347
330a66a0f45a Document the forwardrefmax pragma
William Astle <lost@l-w.ca>
parents: 345
diff changeset
2114
472
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2115
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2116
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2117
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2118 <varlistentry>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2119 <term>emuext</term>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2120 <listitem>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2121 <para>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2122
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2123 This pragma enables two instructions useful when running code in compatible
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2124 emulators. Break breaks into the debugger. Log writes printf-style
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2125 output to the debug window
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2126
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2127 </para>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2128 <programlisting>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2129 LOG ; log output
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2130 FDB FSTR ; pointer to format string
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2131 FDB PX1 ; 16 bit pointer to 16 bit value
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2132 FDB PY1 ; 16 bit pointer to 8 bit value (see format string!)
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2133 FDB PX2 ; 16 bit pointer to 16 bit value
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2134 FDB PY2 ; 16 bit pointer to 8 bit value
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2135 ; execution continues here ...
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2136 RTS
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2137
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2138 ; format string
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2139 FSTR FCC "%hu,%hhu - %hu,%hhu"
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2140 FCB 10,0
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2141 </programlisting>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2142 </listitem>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2143 </varlistentry>
e97f9a302c6a Add emuext pragma and associated instructions.
William Astle <lost@l-w.ca>
parents: 455
diff changeset
2144
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2145 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2146
111
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2147 <para>As a convenience, each input file has a pragma state stack. This
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2148 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2149 pragma state and then restore it to the precise state it had previously.
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2150 If, at the end of an input file, all pragma states have not been popped,
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2151 they will be removed from the stack. Thus, it is critical to employ
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2152 *PRAGMAPOP correctly. Because each input file has its own pragma stack,
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2153 using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2154 work.</para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2155
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2156 <para>Pragma stacks are more useful in include files, in particular in
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2157 conjunction with the nolist pragma. One can push the state of the nolist
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2158 pragma, engage the nolist pragma, and then pop the state of the nolist
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2159 pragma at the end of the include file. This will cause the entire include
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2160 file to operate under the nolist pragma. However, if the file is included
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2161 while nolist is already engaged, it will not undo that state.</para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2162
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2163
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks
lost@l-w.ca
parents: 68
diff changeset
2164
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2165 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2166
394
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2167 <section id="convinst">
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2168 <title id="convinsttitle">Convenience Instructions</title>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2169 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2170
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2171 Similar to the 6800 compatibility instructions (pragma 6800compat) these
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2172 pragma 6809conv and pragma 6309conv enable convenience extensions to the
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2173 6809 and 6309 instruction set. Originally intended for compatibility with
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2174 the MACRO-80c assembler, these have proven useful in large codebases that
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2175 target both the 6809 and the 6309.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2176 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2177
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2178 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2179
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2180 The 6809 extensions are straightforward with the exception of "TSTD" which
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2181 assembles as "STD -2,S". A benefit of using these is they will "just work"
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2182 and take on their 6309 equivalent when you enable 6309 assembly mode.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2183 Supported instructions: ASRD, CLRD, COMD, LSLD, LSRD, NEGD, TSTD.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2184 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2185 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2186
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2187 6309 extensions are based on common patterns described by Chris Burke and
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2188 Darren Atkinson in their 6309 documentation and include the following
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2189 instructions: ASRQ, CLRQ, COMQ, LSLE, LSLF, LSLQ, LSRQ, NEGE,
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2190 NEGF, NEGW, NEGQ, TSTQ.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2191 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2192 </section>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2193
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2194 <section>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2195 <title>Cycle Counts</title>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2196 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2197
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2198 The following options for displaying cycle counts in listings are provided.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2199 These options are enabled from pragmas on the command line or in the
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2200 assembly files themselves. For compatibility with other assemblers you can
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2201 use the "OPT" keyword in addition to "PRAGMA."
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2202 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2203
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2204 <programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2205 opt c - enable cycle counts: [8]
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2206 opt cd - enable detailed cycle counts breaking down addressing modes: [5+3]
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2207 opt ct - show a running subtotal of cycles
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2208 opt cc - clear the running subtotal
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2209 </programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2210
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2211 <para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2212
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2213 The assembler supports both 6809 as well as native-mode 6309 cycle counts.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2214 In 6309 mode the counts are displayed in parenthesis instead of brackets.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2215 In addition, some operations have a variable cycle count. In this case a
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2216 "+?" is displayed to alert the reader. Sample output is shown below.
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2217 </para>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2218
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2219 <programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2220 266f 7d25e2 (window.asm):00313 [7] 7 move tst putflg
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2221 2672 2602 (window.asm):00314 [5] 12 bne a@
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2222 2674 1e13 (window.asm):00315 [8] 20 exg x,u
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2223 2676 0dd6 (window.asm):00316 [6] 26 a@ tst is6309
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2224 2678 2618 (window.asm):00317 [5] 31 bne exit@
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2225 (window.asm):00318 opt 6309
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2226 267a 10860085 (window.asm):00319 (4) 35 b@ ldw #133
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2227 267e 113813 (window.asm):00320 (6+?) 41 tfm x+,u+
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2228 2681 30881b (window.asm):00321 (4+1) 46 leax 27,x
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2229 2684 33c81b (window.asm):00322 (4+1) 51 leau 27,u
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2230 2687 4a (window.asm):00323 (1) 52 deca
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2231 2688 26f0 (window.asm):00324 (5) 57 bne b@
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2232 </programlisting>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2233 </section>
fc166b3bbae3 Update manual for recent additions.
William Astle <lost@l-w.ca>
parents: 369
diff changeset
2234
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2235 </chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2236
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2237 <chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2238 <title>LWLINK</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2239 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2240 The LWTOOLS linker is called LWLINK. This chapter documents the various features
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2241 of the linker.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2242 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2243
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2244 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2245 <title>Command Line Options</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2246 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2247 The binary for LWLINK is called "lwlink". Note that the binary is in lower
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2248 case. lwlink takes the following command line arguments.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2249 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2250 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2251 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2252 <term><option>--decb</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2253 <term><option>-b</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2254 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2255 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2256 Selects the DECB output format target. This is equivalent to <option>--format=decb</option>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2257 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2258 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2259 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2260
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2261 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2262 <term><option>--output=FILE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2263 <term><option>-o FILE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2264 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2265 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2266 This option specifies the name of the output file. If not specified, the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2267 default is <option>a.out</option>.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2268 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2269 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2270 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2271
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2272 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2273 <term><option>--format=TYPE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2274 <term><option>-f TYPE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2275 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2276 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2277 This option specifies the output format. Valid values are <option>decb</option>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2278 and <option>raw</option>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2279 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2280 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2281 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2282
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2283 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2284 <term><option>--raw</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2285 <term><option>-r</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2286 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2287 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2288 This option specifies the raw output format.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2289 It is equivalent to <option>--format=raw</option>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2290 and <option>-f raw</option>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2291 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2292 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2293 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2294
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2295 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2296 <term><option>--script=FILE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2297 <term><option>-s</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2298 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2299 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2300 This option allows specifying a linking script to override the linker's
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2301 built in defaults.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2302 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2303 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2304 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2305
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2306 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2307 <term><option>--section-base=SECT=BASE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2308 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2309 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2310 Cause section SECT to load at base address BASE. This will be prepended
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2311 to the built-in link script. It is ignored if a link script is provided.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2312 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2313 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2314 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2315
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2316 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2317 <term><option>--map=FILE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2318 <term><option>-m FILE</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2319 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2320 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2321 This will output a description of the link result to FILE.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2322 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2323 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2324 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2325
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2326 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2327 <term><option>--library=LIBSPEC</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2328 <term><option>-l LIBSPEC</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2329 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2330 <para>
440
fda62f676ed4 Allow specifying exact filenames for -l in lwlink
William Astle <lost@l-w.ca>
parents: 394
diff changeset
2331 Load a library using the library search path. If LIBSPEC is prefixed with a
fda62f676ed4 Allow specifying exact filenames for -l in lwlink
William Astle <lost@l-w.ca>
parents: 394
diff changeset
2332 colon (":"), then LIBSPEC is the precise filename to be searched for in the
fda62f676ed4 Allow specifying exact filenames for -l in lwlink
William Astle <lost@l-w.ca>
parents: 394
diff changeset
2333 library path. Otherwise, LIBSPEC will have "lib" prepended and ".a" appended.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2334 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2335 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2336 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2337
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2338 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2339 <term><option>--library-path=DIR</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2340 <term><option>-L DIR</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2341 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2342 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2343 Add DIR to the library search path.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2344 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2345 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2346 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2347
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2348 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2349 <term><option>--debug</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2350 <term><option>-d</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2351 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2352 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2353 This option increases the debugging level. It is only useful for LWTOOLS
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2354 developers.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2355 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2356 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2357 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2358
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2359 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2360 <term><option>--help</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2361 <term><option>-?</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2362 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2363 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2364 This provides a listing of command line options and a brief description
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2365 of each.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2366 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2367 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2368 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2369
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2370 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2371 <term><option>--usage</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2372 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2373 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2374 This will display a usage summary
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2375 of each command line option.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2376 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2377 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2378 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2379
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2380
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2381 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2382 <term><option>--version</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2383 <term><option>-V</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2384 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2385 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2386 This will display the version of LWLINK.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2387 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2388 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2389 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2390
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2391 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2392
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2393 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2394 <title>Linker Operation</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2395
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2396 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2397
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2398 LWLINK takes one or more files in supported input formats and links them
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2399 into a single binary. Currently supported formats are the LWTOOLS object
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2400 file format and the archive format used by LWAR. While the precise method is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2401 slightly different, linking can be conceptualized as the following steps.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2402
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2403 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2404
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2405 <orderedlist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2406 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2407 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2408 First, the linker loads a linking script. If no script is specified, it
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2409 loads a built-in default script based on the output format selected. This
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2410 script tells the linker how to lay out the various sections in the final
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2411 binary.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2412 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2413 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2414
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2415 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2416 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2417 Next, the linker reads all the input files into memory. At this time, it
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2418 flags any format errors in those files. It constructs a table of symbols
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2419 for each object at this time.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2420 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2421 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2422
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2423 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2424 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2425 The linker then proceeds with organizing the sections loaded from each file
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2426 according to the linking script. As it does so, it is able to assign addresses
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2427 to each symbol defined in each object file. At this time, the linker may
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2428 also collapse different instances of the same section name into a single
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2429 section by appending the data from each subsequent instance of the section
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2430 to the first instance of the section.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2431 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2432 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2433
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2434 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2435 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2436 Next, the linker looks through every object file for every incomplete reference.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2437 It then attempts to fully resolve that reference. If it cannot do so, it
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2438 throws an error. Once a reference is resolved, the value is placed into
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2439 the binary code at the specified section. It should be noted that an
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2440 incomplete reference can reference either a symbol internal to the object
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2441 file or an external symbol which is in the export list of another object
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2442 file.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2443 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2444 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2445
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2446 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2447 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2448 If all of the above steps are successful, the linker opens the output file
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2449 and actually constructs the binary.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2450 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2451 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2452 </orderedlist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2453
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2454 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2455
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2456 <section
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2457 <title>Linking Scripts</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2458 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2459 A linker script is used to instruct the linker about how to assemble the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2460 various sections into a completed binary. It consists of a series of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2461 directives which are considered in the order they are encountered.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2462 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2463 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2464 The sections will appear in the resulting binary in the order they are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2465 specified in the script file. If a referenced section is not found, the linker will behave as though the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2466 section did exist but had a zero size, no relocations, and no exports.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2467 A section should only be referenced once. Any subsequent references will have
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2468 an undefined effect.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2469 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2470
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2471 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2472 All numbers are in linking scripts are specified in hexadecimal. All directives
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2473 are case sensitive although the hexadecimal numbers are not.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2474 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2475
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2476 <para>A section name can be specified as a "*", then any section not
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2477 already matched by the script will be matched. The "*" can be followed
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2478 by a comma and a flag to narrow the section down slightly, also.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2479 If the flag is "!bss", then any section that is not flagged as a bss section
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2480 will be matched. If the flag is "bss", then any section that is flagged as
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2481 bss will be matched.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2482 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2483
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2484 <para>The following directives are understood in a linker script.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2485 <variablelist>
234
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2486
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2487 <varlistentry>
236
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2488 <term>sectopt <parameter>section</parameter> padafter <parameter>byte,...</parameter></term>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2489 <listitem>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2490
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2491 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2492
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2493 This will cause the linker to append the specified list of byte values
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2494 (specified in hexadecimal separated by commas) to the end of the named
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2495 section. This is done once all instances of the specified section are
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2496 collected together. This has no effect if the specified section does not
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2497 appear anywhere in any of the objects specified for linking.
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2498
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2499 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2500
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2501 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2502
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2503 If code depends on the presence of this padding somewhere, it is sufficient
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2504 to include an empty section of the specified name in the object that depends
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2505 on it.
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2506
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2507 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2508
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2509 </listitem>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2510
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2511 <varlistentry>
234
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2512 <term>define basesympat <parameter>string</parameter></term>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2513 <listitem>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2514
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2515 <para>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2516
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2517 This causes the linker to define a symbol for the ultimate base address of
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2518 each section using the pattern specified by <parameter>string</parameter>.
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2519 In the string, %s can appear exactly once and will be replaced with the
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2520 section name. The base address is calculated after all instances of each
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2521 section have been collapsed together.
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2522
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2523 </para>
236
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2524
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2525 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2526
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2527 It should be noted that if none of the objects to be linked contains a
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2528 particular section name, there will be no base symbol defined for it, even
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2529 if it is listed explicitly in the link script. If code depends on the
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2530 presence of these symbols, it is sufficient to include an empty section of
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2531 the specified name in the object that depends on it.
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2532
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2533 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2534
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2535
234
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2536 <para> If the pattern resolves to the same string for multiple
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2537 sections, the results are undefined.
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2538
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2539 </para>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2540 </listitem>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2541
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2542 <varlistentry>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2543 <term>define lensympat <parameter>string</parameter></term>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2544 <listitem>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2545
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2546 <para>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2547
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2548 This causes the linker to define a symbol for the ultimate length of each
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2549 section using the pattern specified by <parameter>string</parameter>. In
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2550 the string, %s can appear exactly once and will be replaced with the section
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2551 name. The length is calculated after all instances of a section have been
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2552 collapsed together.
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2553
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2554 </para>
236
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2555
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2556 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2557
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2558 It should be noted that if none of the objects to be linked contains a
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2559 particular section name, there will be no length symbol defined for it, even
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2560 if it is listed explicitly in the link script. If code depends on the
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2561 presence of these symbols, it is sufficient to include an empty section of
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2562 the specified name in the object that depends on it.
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2563
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2564 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2565
ce1fdc8d6568 Added ability to add padding after a section when linking.
William Astle <lost@l-w.ca>
parents: 234
diff changeset
2566
234
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2567 <para>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2568 If the pattern resolves to the same string for multiple
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2569 sections, the results are undefined.
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2570
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2571 </para>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2572 </listitem>
d389adbcc4ab Added section base and length symbols to lwlink
William Astle <lost@l-w.ca>
parents: 232
diff changeset
2573
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2574 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2575 <term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2576 <listitem><para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2577
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2578 This causes the section <parameter>name</parameter> to load at
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2579 <parameter>addr</parameter>. For the raw target, only one "load at" entry is
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2580 allowed for non-bss sections and it must be the first one. For raw targets,
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2581 it affects the addresses the linker assigns to symbols but has no other
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2582 affect on the output. bss sections may all have separate load addresses but
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2583 since they will not appear in the binary anyway, this is okay.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2584 </para><para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2585 For the decb target, each "load" entry will cause a new "block" to be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2586 output to the binary which will contain the load address. It is legal for
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2587 sections to overlap in this manner - the linker assumes the loader will sort
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2588 everything out.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2589 </para></listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2590 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2591
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2592 <varlistentry>
316
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2593 <term>section <parameter>name</parameter> high <parameter>addr</parameter></term>
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2594 <listitem><para>
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2595
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2596 This causes the section <parameter>name</parameter> to load with its end
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2597 address just below <parameter>addr</parameter>. Subsequent sections are
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2598 loaded at progressively lower addresses. This may lead to inefficient file
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2599 encoding for some targets. As of this writing, it will also almost
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2600 certainly do the wrong thing for a raw target.
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2601
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2602 </para><para>
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2603
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2604 This is useful for aligning a block of code with high memory. As an
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2605 example, if the total size of a section is $100 bytes and a high address of
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2606 $FE00 is specified, the section will actually load at $FD00.
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2607
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2608 </para></listitem>
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2609 </varlistentry>
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2610
c4853a54b4a1 Documented new "high" option for link scripts.
William Astle <lost@l-w.ca>
parents: 254
diff changeset
2611 <varlistentry>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2612 <term>section <parameter>name</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2613 <listitem><para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2614
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2615 This will cause the section <parameter>name</parameter> to load after the previously listed
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2616 section.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2617 </para></listitem></varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2618 <varlistentry>
68
99ce348b0e6b Fixed error in documentation - linkscripts use "entry" instead of "exec"
lost@l-w.ca
parents: 60
diff changeset
2619 <term>entry <parameter>addr or sym</parameter></term>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2620 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2621 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2622 This will cause the execution address (entry point) to be the address
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2623 specified (in hex) or the specified symbol name. The symbol name must
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2624 match a symbol that is exported by one of the object files being linked.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2625 This has no effect for targets that do not encode the entry point into the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2626 resulting file. If not specified, the entry point is assumed to be address 0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2627 which is probably not what you want. The default link scripts for targets
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2628 that support this directive automatically starts at the beginning of the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2629 first section (usually "init" or "code") that is emitted in the binary.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2630 </para>
533
543b5d1341d2 Add note to manual about numeric entry addresses in scripts
William Astle <lost@l-w.ca>
parents: 518
diff changeset
2631
543b5d1341d2 Add note to manual about numeric entry addresses in scripts
William Astle <lost@l-w.ca>
parents: 518
diff changeset
2632 <para>Note that if you use a numeric value here, you will need to ensure
543b5d1341d2 Add note to manual about numeric entry addresses in scripts
William Astle <lost@l-w.ca>
parents: 518
diff changeset
2633 it starts with a digit. That may mean adding a leading zero.</para>
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2634 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2635 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2636
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2637 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2638 <term>pad <parameter>size</parameter></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2639 <listitem><para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2640 This will cause the output file to be padded with NUL bytes to be exactly
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2641 <parameter>size</parameter> bytes in length. This only makes sense for a raw target.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2642 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2643 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2644 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2645 </variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2646
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2647
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2648
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2649 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2650
152
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2651 <section>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2652 <title>Format Specific Linking Notes</title>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2653
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2654 <para>Some formats require special information to be able to generate actual
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2655 binaries. If the specific format you are interested in is not listed in
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2656 this section, then there is nothing special you need to know about to create
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2657 a final binary.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2658
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2659 <section>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2660 <title>OS9 Modules</title>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2661
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2662 <para>OS9 modules need to embed several items into the module header. These
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2663 items are the type of module, the langauge of the module, the module
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2664 attributes, the module revision number, the data size (bss), and the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2665 execution offset. These are all either calculated or default to reasonable
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2666 values.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2667
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2668 <para>The data size is calcuated as the sum of all sections named "bss" or
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2669 ".bss" in all object files that are linked together.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2670
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2671 <para>The execution offset is calculated from the address of the special
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2672 symbol "__start" which must be an exported (external) symbol in one of the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2673 objects to be linked.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2674
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2675 <para>The type defaults to "Prgrm" or "Program module". The language
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2676 defaults to "Objct" or "6809 object code". Attributes default to enabling
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2677 the re-entrant flag. And finally, the revision defaults to zero.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2678
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2679 <para>The embedded module name is the output filename. If the output
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2680 filename includes more than just the filename, this will probably not be
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2681 what you want.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2682
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2683 <para>The type, language, attributes, revision, and module name can all be
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2684 overridden by providing a special section in exactly one of the object files
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2685 to be linked. This section is called "__os9" (note the two underscores).
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2686 To override the type, language, attributes, or revision values, define a
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2687 non-exported symbol in this section called "type", "lang", "attr", or "rev"
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2688 respectively. Any other symbols defined are ignored. To override the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2689 module name, include as the only actual code in the section a NUL terminated
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2690 string (the FCN directive is useful for this). If there is no code in the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2691 section or it beings with a NUL, the default name will be used. Any of the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2692 preceeding that are not defined in the special section will retain their
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2693 default values.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2694
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2695 <para>The built-in link script for OS9 modules will place the following
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2696 sections, in order, in the module: "code", ".text", "data", ".data". It
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2697 will merge all sections with the name "bss" or ".bss" into the "data"
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2698 section. All other section names are ignored. What this means is that you
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2699 must define your data variables in the a section called "bss" or ".bss" even
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2700 though you will be refencing them all as offsets from U. This does have the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2701 unpleasant side effect that all BSS references will end up being 16 bit
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2702 offsets because the assembler cannot know what the offset will be once the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2703 linker is finished its work. Thus, if the tightest possible code is
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2704 required, having LWASM directly output the module is a better choice.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2705
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2706 <para>While the built-in link script is probably sufficient for most
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2707 purposes, you can provide your own script. If you provide a custom link
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2708 script, you must start your code and data sections at location 000D to
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2709 accommodate the module header. Otherwise, you will have an incorrect
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2710 location for the execution offset. You must use the ENTRY directive in the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2711 script to define the entry point for the module.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2712
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2713 <para>It should also be obvious from the above that you cannot mix the bss
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2714 (rmb) definitions with the module code when linking separately. Those
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2715 familiar with typical module creation will probably find this an unpleasant
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2716 difference but it is unavoidable.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2717
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2718 <para>It should also be noted that direct page references should also be
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2719 avoided because you cannot know ahead of time whether the linker is going to
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2720 end up putting a particular variable in the first 256 bytes of the module's
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2721 data space. If, however, you know for certain you will have less than 256
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2722 bytes of defined data space across all of the object files that will be
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2723 linked, you can instead use forced DP addressing for your data addresses
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2724 instead of the ,u notation. When linking with 3rd party libraries, this
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2725 practice should be avoided. Also, when creating libraries, always use the
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2726 offset from U technique.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2727
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2728 </section>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2729
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2730 </section>
a26b045c4e18 Added documentation about OS9 module support in lwlink
lost@l-w.ca
parents: 143
diff changeset
2731
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2732 </chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2733
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2734 <chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2735 <title>Libraries and LWAR</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2736
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2737 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2738 LWTOOLS also includes a tool for managing libraries. These are analogous to
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2739 the static libraries created with the "ar" tool on POSIX systems. Each library
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2740 file contains one or more object files. The linker will treat the object
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2741 files within a library as though they had been specified individually on
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2742 the command line except when resolving external references. External references
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2743 are looked up first within the object files within the library and then, if
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2744 not found, the usual lookup based on the order the files are specified on
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2745 the command line occurs.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2746 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2747
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2748 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2749 The tool for creating these libary files is called LWAR.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2750 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2751
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2752 <section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2753 <title>Command Line Options</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2754 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2755 The binary for LWAR is called "lwar". Note that the binary is in lower
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2756 case. The options lwar understands are listed below. For archive manipulation
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2757 options, the first non-option argument is the name of the archive. All other
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2758 non-option arguments are the names of files to operate on.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2759 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2760
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2761 <variablelist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2762 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2763 <term><option>--add</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2764 <term><option>-a</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2765 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2766 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2767 This option specifies that an archive is going to have files added to it.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2768 If the archive does not already exist, it is created. New files are added
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2769 to the end of the archive.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2770 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2771 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2772 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2773
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2774 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2775 <term><option>--create</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2776 <term><option>-c</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2777 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2778 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2779 This option specifies that an archive is going to be created and have files
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2780 added to it. If the archive already exists, it is truncated.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2781 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2782 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2783 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2784
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2785 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2786 <term><option>--merge</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2787 <term><option>-m</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2788 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2789 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2790 If specified, any files specified to be added to an archive will be checked
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2791 to see if they are archives themselves. If so, their constituent members are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2792 added to the archive. This is useful for avoiding archives containing archives.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2793 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2794 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2795 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2796
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2797 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2798 <term><option>--list</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2799 <term><option>-l</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2800 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2801 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2802 This will display a list of the files contained in the archive.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2803 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2804 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2805 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2806
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2807 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2808 <term><option>--debug</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2809 <term><option>-d</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2810 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2811 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2812 This option increases the debugging level. It is only useful for LWTOOLS
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2813 developers.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2814 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2815 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2816 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2817
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2818 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2819 <term><option>--help</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2820 <term><option>-?</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2821 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2822 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2823 This provides a listing of command line options and a brief description
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2824 of each.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2825 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2826 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2827 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2828
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2829 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2830 <term><option>--usage</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2831 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2832 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2833 This will display a usage summary
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2834 of each command line option.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2835 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2836 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2837 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2838
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2839
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2840 <varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2841 <term><option>--version</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2842 <term><option>-V</option></term>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2843 <listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2844 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2845 This will display the version of LWLINK.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2846 of each.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2847 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2848 </listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2849 </varlistentry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2850
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2851 </section>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2852
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2853 </chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2854
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2855 <chapter id="objchap">
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2856 <title>Object Files</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2857 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2858 LWTOOLS uses a proprietary object file format. It is proprietary in the sense
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2859 that it is specific to LWTOOLS, not that it is a hidden format. It would be
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2860 hard to keep it hidden in an open source tool chain anyway. This chapter
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2861 documents the object file format.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2862 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2863
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2864 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2865 An object file consists of a series of sections each of which contains a
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2866 list of exported symbols, a list of incomplete references, and a list of
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2867 "local" symbols which may be used in calculating incomplete references. Each
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2868 section will obviously also contain the object code.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2869 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2870
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2871 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2872 Exported symbols must be completely resolved to an address within the
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2873 section it is exported from. That is, an exported symbol must be a constant
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2874 rather than defined in terms of other symbols.</para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2875
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2876 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2877 Each object file starts with a magic number and version number. The magic
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2878 number is the string "LWOBJ16" for this 16 bit object file format. The only
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2879 defined version number is currently 0. Thus, the first 8 bytes of the object
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2880 file are <code>4C574F424A313600</code>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2881 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2882
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2883 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2884 Each section has the following items in order:
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2885 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2886
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2887 <itemizedlist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2888 <listitem><para>section name</para></listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2889 <listitem><para>flags</para></listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2890 <listitem><para>list of local symbols (and addresses within the section)</para></listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2891 <listitem><para>list of exported symbols (and addresses within the section)</para></listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2892 <listitem><para>list of incomplete references along with the expressions to calculate them</para></listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2893 <listitem><para>the actual object code (for non-BSS sections)</para></listitem>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2894 </itemizedlist>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2895
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2896 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2897 The section starts with the name of the section with a NUL termination
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2898 followed by a series of flag bytes terminated by NUL. There are only two
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2899 flag bytes defined. A NUL (0) indicates no more flags and a value of 1
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2900 indicates the section is a BSS section. For a BSS section, no actual
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2901 code is included in the object file.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2902 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2903
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2904 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2905 Either a NULL section name or end of file indicate the presence of no more
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2906 sections.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2907 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2908
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2909 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2910 Each entry in the exported and local symbols table consists of the symbol
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2911 (NUL terminated) followed by two bytes which contain the value in big endian
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2912 order. The end of a symbol table is indicated by a NULL symbol name.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2913 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2914
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2915 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2916 Each entry in the incomplete references table consists of an expression
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2917 followed by a 16 bit offset where the reference goes. Expressions are
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2918 defined as a series of terms up to an "end of expression" term. Each term
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2919 consists of a single byte which identifies the type of term (see below)
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2920 followed by any data required by the term. Then end of the list is flagged
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2921 by a NULL expression (only an end of expression term).
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2922 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2923
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2924 <table frame="all"><title>Object File Term Types</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2925 <tgroup cols="2">
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2926 <thead>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2927 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2928 <entry>TERMTYPE</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2929 <entry>Meaning</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2930 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2931 </thead>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2932 <tbody>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2933 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2934 <entry>00</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2935 <entry>end of expression</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2936 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2937
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2938 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2939 <entry>01</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2940 <entry>integer (16 bit in big endian order follows)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2941 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2942 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2943 <entry>02</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2944 <entry> external symbol reference (NUL terminated symbol name follows)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2945 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2946
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2947 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2948 <entry>03</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2949 <entry>local symbol reference (NUL terminated symbol name follows)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2950 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2951
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2952 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2953 <entry>04</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2954 <entry>operator (1 byte operator number)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2955 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2956 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2957 <entry>05</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2958 <entry>section base address reference</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2959 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2960
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2961 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2962 <entry>FF</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2963 <entry>This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. Flag 01 indicates an 8 bit relocation. Flag 02 indicates a zero-width relocation (see the EXTDEP pseudo op in LWASM).</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2964 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2965 </tbody>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2966 </tgroup>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2967 </table>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2968
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2969
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2970 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2971 External references are resolved using other object files while local
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2972 references are resolved using the local symbol table(s) from this file. This
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2973 allows local symbols that are not exported to have the same names as
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2974 exported symbols or external references.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2975 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2976
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2977 <table frame="all"><title>Object File Operator Numbers</title>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2978 <tgroup cols="2">
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2979 <thead>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2980 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2981 <entry>Number</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2982 <entry>Operator</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2983 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2984 </thead>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2985 <tbody>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2986 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2987 <entry>01</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2988 <entry>addition (+)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2989 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2990 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2991 <entry>02</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2992 <entry>subtraction (-)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2993 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2994 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2995 <entry>03</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2996 <entry>multiplication (*)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2997 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2998 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2999 <entry>04</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3000 <entry>division (/)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3001 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3002 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3003 <entry>05</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3004 <entry>modulus (%)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3005 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3006 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3007 <entry>06</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3008 <entry>integer division (\) (same as division)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3009 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3010
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3011 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3012 <entry>07</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3013 <entry>bitwise and</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3014 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3015
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3016 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3017 <entry>08</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3018 <entry>bitwise or</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3019 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3020
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3021 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3022 <entry>09</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3023 <entry>bitwise xor</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3024 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3025
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3026 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3027 <entry>0A</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3028 <entry>boolean and</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3029 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3030
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3031 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3032 <entry>0B</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3033 <entry>boolean or</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3034 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3035
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3036 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3037 <entry>0C</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3038 <entry>unary negation, 2's complement (-)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3039 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3040
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3041 <row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3042 <entry>0D</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3043 <entry>unary 1's complement (^)</entry>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3044 </row>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3045 </tbody>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3046 </tgroup>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3047 </table>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3048
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3049 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3050 An expression is represented in a postfix manner with both operands for
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3051 binary operators preceding the operator and the single operand for unary
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3052 operators preceding the operator.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3053 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3054
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3055 </chapter>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3056 </book>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3057