LWTools: docs/manual.docbook.sgml annotate

annotate docs/manual.docbook.sgml @ 436:9f49f0966c1e lwtools-4.14

Version 4.14

author	William Astle <lost@l-w.ca>
date	Sun, 09 Apr 2017 00:14:00 -0600
parents	fc166b3bbae3
children	fda62f676ed4

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>
348 379ef4e08dd2 Update copyright year for manual William Astle <lost@l-w.ca> parents: 347 diff changeset	7 <copyright><year>2009-2015</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>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	357 <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	358 <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	359 <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	360 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	361 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	362 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	363 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	364 </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	365 </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	366
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	367 <varlistentry>
369 682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	368 <term><option>--symbols-nolocals</option></term>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	369 <listitem>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	370 <para>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	371 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	372 </para>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	373 </listitem>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	374 </varlistentry>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	375
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	376 <varlistentry>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	377 <term><option>--map=FILE</option></term>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	378 <listitem>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	379 <para>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	380
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	381 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	382
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	383 </para>
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 </varlistentry>
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	386
682524a1f32f Updated documentation for --symbols-nolocals and --map William Astle <lost@l-w.ca> parents: 348 diff changeset	387 <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	388 <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	389 <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	390 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	391 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	392 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	393 </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	394 </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	395
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	396 <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	397 <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	398 <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	399 <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	400 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	401 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	402 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	403 </para>
2c24602be78f 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 </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	406
2c24602be78f 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 <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	408 <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	409 <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	410 <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	411 <para>
2c24602be78f 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 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	413 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	414 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	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 </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	417 </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	418
2c24602be78f 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 <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	420 <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	421 <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	422 <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	423 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	424 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	425 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	426 </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	427 </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	428
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	429 <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	430 <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	431 <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	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 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	435 </para>
2c24602be78f 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 </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	437 </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	438
2c24602be78f 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>
231 2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	440 <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	441 <term><option>-D SYM[=VAL]</option></term>
231 2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	442 <listitem>
2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	443 <para>
2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	444 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	445 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	446 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	447 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	448 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	449 </para>
2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	450 </listitem>
2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	451 </varlistentry>
2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	452
394 fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	453 <varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	454 <term><option>-t WIDTH</option></term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	455 <term><option>--tabs=WIDTH</option></term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	456 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	457 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	458 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	459 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	460 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	461 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	462 </varlistentry>
231 2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	463
2cc599f1bebf Added --define to lwasm documentation. William Astle <lost@l-w.ca> parents: 210 diff changeset	464 <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	465 <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	466 <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	467 <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	468 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	469 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	470 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	471 </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	472 </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	473
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	474 <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	475 <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	476 <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	477 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	478 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	479 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	480 </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	481 </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	482
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	483 <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	484 <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	485 <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	486 <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	487 <para>
2c24602be78f 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 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	489 </para>
2c24602be78f 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 </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	491 </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	492
2c24602be78f 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 <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	494 <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	495 <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	496 <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	497 <para>
2c24602be78f 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 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	499 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	500 </para>
2c24602be78f 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 </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	502 </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	503
2c24602be78f 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 </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	505
2c24602be78f 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 </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	507
2c24602be78f 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 <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	509 <title>Dialects</title>
333 507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	510
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	511 <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	512 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	513 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	514 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	515 <parameter>6800compat</parameter> pragma. It also supports all known HD6309
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	516 instructions. While there is general agreement on the pneumonics for most
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	517 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	518 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	519 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	520 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	521 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	522 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	523
2c24602be78f 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 <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	525 <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	526 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	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 <para>
2c24602be78f 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 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	530 hash sign ("#") for immediate mode, the less than sign ("<") 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	531 eight bit modes, and the greater than sign (">") 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	532 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	533
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	534 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	535 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	536 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	537 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	538 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	539 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	540
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	541 </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	542
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	543 <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	544 <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	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>
2c24602be78f 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 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	548 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	549 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	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 <para>
2c24602be78f 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 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	553 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	554 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	555 <para>
2c24602be78f 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 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	557 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	558 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	559 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	560 </para>
2c24602be78f 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
2c24602be78f 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 <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	563 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	564 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	565 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	566 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	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 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	570 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	571 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	572 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	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
2c24602be78f 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 <para>
2c24602be78f 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 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	577 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	578 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	579 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	583 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	584 </para>
2c24602be78f 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
2c24602be78f 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 <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	587 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	588 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	589 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	590 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	591 </para>
2c24602be78f 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
2c24602be78f 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 </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	594
2c24602be78f 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 <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	596 <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	597
2c24602be78f 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 <para>
2c24602be78f 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 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	600 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	601 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	602 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	606 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	607 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	608 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	609 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	610 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	611 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	612 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	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 <para>
2c24602be78f 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 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	617 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	618 "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	619 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	620 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	621 </para>
2c24602be78f 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
2c24602be78f 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 </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	624
2c24602be78f 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 <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	626 <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	627 <para>
2c24602be78f 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
2c24602be78f 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 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	630 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	631 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	632 "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	633 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	634 be prefixed with "&" 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	635 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	636 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	637 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	638
2c24602be78f 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 </para>
2c24602be78f 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
2c24602be78f 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 <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	642 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	643 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	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 <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	646 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	647 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	648
2c24602be78f 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 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	652 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	653 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	654 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	655 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	656 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	657 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	658
2c24602be78f 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 </para>
2c24602be78f 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 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	664 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	665 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	666 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	667 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	668
2c24602be78f 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 </para>
2c24602be78f 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 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	674 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	675 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	676
2c24602be78f 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 </para>
2c24602be78f 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
2c24602be78f 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 </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	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 <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	682 <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	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 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	685 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	686 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	687 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	688 </para>
2c24602be78f 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
2c24602be78f 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 <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	691 <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	692 <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	693 <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	694 <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	695 <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	696 <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	697 <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	698 </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	699 </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	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 <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	702 <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	703 <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	704 <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	705 <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	706 <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	707 </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	708 </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	709
2c24602be78f 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 <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	711 <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	712 <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	713 <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	714 <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	715 <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	716 </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	717 </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	718
2c24602be78f 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 <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	720 <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	721 <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	722 <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	723 <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	724 <para>
2c24602be78f 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 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	726 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	727 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	728 </para>
2c24602be78f 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>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	734 <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	735 <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	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>
2c24602be78f 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 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	739 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	740 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	741 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	742 </para>
2c24602be78f 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 </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	744 </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	745
2c24602be78f 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 <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	747 <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	748 <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	749 <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	750 <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	751 <para>
2c24602be78f 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 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	753 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	754 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	755 </para>
2c24602be78f 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 </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	757 </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	758
2c24602be78f 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 <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	760 <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	761 <para>
2c24602be78f 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 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	763 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	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><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	769 <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	770 <para>
2c24602be78f 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 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	772 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	773 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	774 </para>
2c24602be78f 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 </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	776 </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	777
2c24602be78f 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 <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	779 <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	780 <para>
2c24602be78f 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 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	782 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	783 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	784 </para>
2c24602be78f 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 </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	786 </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	787
2c24602be78f 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 <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	790 <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	791 <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	792 <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	793 <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	794 <para>
2c24602be78f 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 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	796 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	797 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	798 </para>
2c24602be78f 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 </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	800 </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	801
2c24602be78f 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 <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	803 <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	804 <para>
2c24602be78f 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 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	806 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	807 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	808 </para>
2c24602be78f 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 </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	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
2c24602be78f 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 <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	813 <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	814 <para>
2c24602be78f 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 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	816 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	817 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	818 </para>
2c24602be78f 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 </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	820 </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	821
2c24602be78f 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 <term>INCLUDEBIN <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	824 <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	825 <para>
2c24602be78f 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 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	827 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	828 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	829 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	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
2c24602be78f 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 <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	833 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	834 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	835
2c24602be78f 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> 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	837 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	838 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	839
2c24602be78f 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 </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	841 </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	842
254 155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	843 <varlistentry>
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	844 <term>FILL <parameter>size</parameter>,<parameter>byte</parameter></term>
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	845 <listitem>
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	846
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	847 <para>
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	848 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	849 </para>
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	850
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	851 </listitem>
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	852 </varlistentry>
155799f6cfa5 Add documentation for the FILL pseudo operation William Astle <lost@l-w.ca> parents: 253 diff changeset	853
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	854 </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	855
2c24602be78f 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 </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	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 <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	859 <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	860 <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	861 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	862
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	863 <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	864 <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	865 <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	866 <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	867 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	868 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	869 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	870 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	871 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	872 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	873 </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	874 </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	875
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	876 <varlistentry>
394 fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	877 <term>REORG</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	878 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	879 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	880 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	881 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	882 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	883 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	884 modern code.
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	885 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	886 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	887 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	888
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	889 <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	890 <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	891 <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	892 <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	893 <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	894 </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	895 </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	896
2c24602be78f 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 <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	898 <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	899 <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	900 <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	901 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	902 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	903 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	904 </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	905 </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	906
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	907 <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	908 <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	909 <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	910 <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	911 <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	912 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	913 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	914 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	915 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	916 <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	917 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	918 </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	919 </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	920
2c24602be78f 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 <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	922 <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	923 <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	924
2c24602be78f 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 <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	926 <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	927 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	928 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	929 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	930 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	931 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	932 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	933 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	934
2c24602be78f 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 <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	936 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	937 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	938 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	939
2c24602be78f 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 </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	941 </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	942
2c24602be78f 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 </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	944
2c24602be78f 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 </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	946
2c24602be78f 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 <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	948 <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	949 <para>
2c24602be78f 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 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	951 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	952 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	953 </para>
2c24602be78f 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 <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	955 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	956 </para>
2c24602be78f 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 <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	958 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	959 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	960 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	961 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	962 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	963 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	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>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	966 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	967 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	968 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	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 <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	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 <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	973 <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	974 <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	975 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	976 </para>
2c24602be78f 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 </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	978 </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	979
2c24602be78f 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 <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	981 <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	982 <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	983 <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	984 <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	985 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	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 </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	988 </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	989
2c24602be78f 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 <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	991 <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	992 <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	993 <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	994 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	995 </para>
2c24602be78f 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 </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	997 </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	998
2c24602be78f 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 <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	1000 <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	1001 <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	1002 <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	1003 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	1004 </para>
2c24602be78f 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 </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	1006 </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	1007
2c24602be78f 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 <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	1010 <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	1011 <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	1012 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	1013 </para>
2c24602be78f 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 </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	1015 </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	1016
2c24602be78f 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 <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	1018 <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	1019 <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	1020 <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	1021 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	1022 </para>
2c24602be78f 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 </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	1024 </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	1025
2c24602be78f 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 <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	1027 <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	1028 <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	1029 <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	1030 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	1031 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	1032 </para>
2c24602be78f 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 </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	1034 </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	1035
2c24602be78f 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>
394 fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1037 <term>IFPRAGMA <parameter>pragma</parameter></term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1038 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1039 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1040 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	1041 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1042 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1043 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1044
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1045
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1046 <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	1047 <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	1048 <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	1049 <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	1050 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	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>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	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>
2c24602be78f 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 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	1061 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	1062 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	1063 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	1064 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	1065 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	1066 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1067 </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	1068
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1069 <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	1070 <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	1071 <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	1072 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1073 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	1074 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	1075 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1076 </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	1077 </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	1078
2c24602be78f 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 </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	1080 </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	1081
2c24602be78f 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 <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	1083 <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	1084
2c24602be78f 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 <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	1086 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	1087
2c24602be78f 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 <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	1089
2c24602be78f 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 <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	1091 <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	1092 <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	1093 <para>
2c24602be78f 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
2c24602be78f 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 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	1096
2c24602be78f 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 </para>
2c24602be78f 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 </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	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
2c24602be78f 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 <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	1102 <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	1103 <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	1104 <para>
2c24602be78f 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
2c24602be78f 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 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	1107 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	1108 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	1109
2c24602be78f 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 </para>
2c24602be78f 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 <para>
2c24602be78f 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
2c24602be78f 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 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	1115 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	1116
2c24602be78f 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 </para>
2c24602be78f 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
2c24602be78f 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 </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	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
2c24602be78f 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 <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	1123 <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	1124 <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	1125 <para>
2c24602be78f 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 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	1128 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	1129
2c24602be78f 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 </para>
2c24602be78f 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
2c24602be78f 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 </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	1134 </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	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 <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	1137 <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	1138
2c24602be78f 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 <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	1140 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	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 <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	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 <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	1145 <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	1146 <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	1147
2c24602be78f 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 <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	1149 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	1150 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	1151 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	1152 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	1156 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	1157
2c24602be78f 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 <para>If <parameter>filename</parameter> begins with a "/", 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	1159 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	1160 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	1161 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	1162 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	1163 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	1164 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	1165 </para>
2c24602be78f 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
2c24602be78f 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 </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	1168 </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	1169
2c24602be78f 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 <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	1171 <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	1172 <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	1173 <para>
2c24602be78f 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 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	1175 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	1176 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	1177 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	1178 </para>
2c24602be78f 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 </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	1180 </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	1181
2c24602be78f 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 <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	1183 <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	1184 <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	1185 <para>
2c24602be78f 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 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	1187 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	1188 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	1189 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	1190 </para>
2c24602be78f 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 </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	1192 </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	1193
2c24602be78f 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 <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	1195 <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	1196 <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	1197 <para>
2c24602be78f 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 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	1199 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	1200 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	1201 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	1202 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	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 </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	1205 </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	1206
2c24602be78f 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 <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	1208 <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	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 <para>
2c24602be78f 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 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	1212 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	1213 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	1214 </para>
2c24602be78f 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 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	1217 </para>
2c24602be78f 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 </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	1219 </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	1220
2c24602be78f 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 </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	1222 </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	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 </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	1225
2c24602be78f 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 <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	1227 <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	1228 <para>
2c24602be78f 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 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	1230 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	1231 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	1232 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	1233 </para>
60 9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1234
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1235 <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	1236 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	1237 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	1238 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	1239 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	1240 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	1241 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	1242 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	1243 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	1244 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	1245 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	1246
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	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 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	1249 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	1250 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	1251 </para>
2c24602be78f 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 <para>
2c24602be78f 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 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	1254 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	1255 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	1256 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	1257
2c24602be78f 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>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	1259 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	1260 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	1261 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	1262 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	1263 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	1264 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	1265 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	1266 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	1267 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1268 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1269 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	1270 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	1271 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	1272 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	1273 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1274
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1275 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1276 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	1277 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	1278 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	1279 </para>
2c24602be78f 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
2c24602be78f 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>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	1282
2c24602be78f 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 <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	1284 <varlistentry>
51 fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual lost@l-w.ca parents: 0 diff changeset	1285 <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	1286 <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	1287 <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	1288 <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	1289 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	1290 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	1291 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	1292 </para>
51 fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual lost@l-w.ca parents: 0 diff changeset	1293
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual lost@l-w.ca parents: 0 diff changeset	1294 <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	1295 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	1296 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	1297 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	1298 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	1299 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	1300 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	1301 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	1302 define symbols that should be visible.</para>
fd1ecc5d6e69 Added mention of NOEXPAND macro argument in manual lost@l-w.ca parents: 0 diff changeset	1303
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	1304 </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	1305 </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	1306
2c24602be78f 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 <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	1308 <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	1309 <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	1310 <para>
2c24602be78f 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 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	1312 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	1313 </para>
2c24602be78f 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 </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	1315 </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	1316
2c24602be78f 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 </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	1318
2c24602be78f 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 <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	1320 <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	1321 <para>
2c24602be78f 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
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1323 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	1324 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	1325 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	1326 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	1327 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	1328
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1329 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1330
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1331 <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	1332 <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	1333 <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	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 <para>
2c24602be78f 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 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	1338 <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	1339 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	1340
2c24602be78f 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 </para>
2c24602be78f 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 </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	1343 </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	1344 <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	1345 <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	1346 <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	1347 <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	1348 <para>
2c24602be78f 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 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	1350 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	1351 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	1352 </para>
2c24602be78f 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 </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	1354 </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	1355 </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	1356
2c24602be78f 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 <para>
2c24602be78f 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 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	1360 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	1361 </para>
2c24602be78f 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
2c24602be78f 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 <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	1364 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	1365 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	1366 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	1367
2c24602be78f 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 <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	1369 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	1370 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	1371 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	1372 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	1373
2c24602be78f 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 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	1375 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	1376 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	1377 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	1378 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	1379
2c24602be78f 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 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	1381 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	1382 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	1383 </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	1384
2c24602be78f 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 <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	1386 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	1387 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	1388 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	1389
2c24602be78f 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 <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	1391 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	1392 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	1393 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	1394
2c24602be78f 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 <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	1396 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	1397 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	1398 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	1399 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	1400 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	1401 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	1402 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	1403 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	1404 (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	1405 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	1406 {$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	1407 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	1408 ($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	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 </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	1411
2c24602be78f 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 <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	1413 <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	1414 <para>
2c24602be78f 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 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	1416 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	1417 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	1418 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	1419 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	1420 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	1421 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	1422 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	1423 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	1424 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	1428 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	1429 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	1430 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	1431 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	1432 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	1433 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	1434 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	1435 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	1436 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	1437 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	1438 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	1439 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	1440 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	1441 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	1445 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	1446 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	1447 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	1448 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	1449 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	1450 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	1451 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	1455 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	1456 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	1457 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	1458 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	1459 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	1463 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	1464 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	1465 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	1466 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	1467 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	1468 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	1472 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	1473 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	1474 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	1475 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	1476 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	1477 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	1481 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	1482 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	1483 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	1484 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	1485 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	1486 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	1487 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	1488 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	1489 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	1490 </para>
2c24602be78f 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
2c24602be78f 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 <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	1493
2c24602be78f 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 <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	1495 <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	1496 <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	1497 <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	1498 <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	1499 <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	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 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	1502 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	1503 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	1504 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	1505 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	1506 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	1507 </para>
168 1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1508
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1509 <para><parameter>flags</parameter> is a comma separated list of flags. If a
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1510 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	1511 statements that generate output are permitted.</para>
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1512
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1513 <para>If the flag is "constant",
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1514 the same restrictions apply as for BSS sections. Additionally, all symbols
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1515 defined in a constant section define absolute values and will not be
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1516 adjusted by the linker at link time. Constant sections cannot define
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1517 complex expressions for symbols; the value must be fully defined at assembly
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1518 time. Additionally, multiple instances of a constant section do not
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1519 coalesce into a single addressing unit; each instance starts again at offset
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1520 0.</para>
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1521
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	1522 <para>
2c24602be78f 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 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	1524 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	1525 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	1526 </para>
168 1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1527
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1528 <para> If the section name is "_constants" or "_constant", in any
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1529 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	1530 section. This assumption can be overridden with the "!constant"
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1531 flag.</para>
1e0a0e6cd918 Documentation updates lost@l-w.ca parents: 152 diff changeset	1532
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	1533 <para>
2c24602be78f 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 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	1535 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	1536 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	1537 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1538 </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	1539 </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	1540
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1541 <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	1542 <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	1543 <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	1544 <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	1545 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1546 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	1547 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	1548 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	1549 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	1550 </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	1551 </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	1552
2c24602be78f 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 <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	1554 <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	1555 <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	1556 <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	1557 <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	1558 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1559 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	1560 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	1561 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	1562 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	1563 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	1564 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	1565 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	1566 </para>
2c24602be78f 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 </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	1568 </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	1569
2c24602be78f 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 <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	1571 <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	1572 <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	1573
2c24602be78f 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 <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	1575 <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	1576
2c24602be78f 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 <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	1578 <para>
2c24602be78f 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 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	1580 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	1581 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	1582 </para>
2c24602be78f 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 <para>
2c24602be78f 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 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	1585 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	1586 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	1587 </para>
2c24602be78f 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 </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	1589
2c24602be78f 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 </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	1591
2c24602be78f 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 <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	1593 <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	1594 <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	1595
2c24602be78f 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>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	1597 <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	1598 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	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 </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	1601 </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	1602 </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	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 </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	1605
2c24602be78f 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 <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	1607 <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	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 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	1610 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	1611 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	1612 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	1613 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	1614 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	1615 </para>
2c24602be78f 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
2c24602be78f 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>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	1618 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	1619 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	1620 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	1621 </para>
2c24602be78f 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
2c24602be78f 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 <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	1624 <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	1625 <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	1626 <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	1627 <para>
2c24602be78f 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 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	1629 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	1630 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	1631 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	1632 </para>
2c24602be78f 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 </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	1634 </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	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 <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	1637 <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	1638 <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	1639 <para>
2c24602be78f 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 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	1641 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	1642 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	1643 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	1644 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	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 </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	1647 </varlistentry>
111 c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1648
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1649 <varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1650 <term>*PRAGMAPUSH <parameter>pragma[,...]</parameter></term>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1651 <listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1652 <para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1653 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	1654 </para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1655
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1656 <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	1657
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1658 </listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1659 </varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1660
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1661 <varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1662 <term>*PRAGMAPOP <parameter>pragma[,...]</parameter></term>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1663 <listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1664 <para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1665 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	1666 </para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1667
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1668 <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	1669
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1670 </listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1671 </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	1672 </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	1673
207 07e1fac76321 Added pragma to allow non case sensitive symbols William Astle <lost@l-w.ca> parents: 168 diff changeset	1674 <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	1675 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	1676 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	1677 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	1678 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	1679 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	1680
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1681 <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	1682
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1683 <variablelist>
333 507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1684
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1685 <varlistentry>
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1686 <term>6800compat</term>
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1687 <listitem>
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1688
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1689 <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	1690 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	1691 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	1692 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	1693 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	1694 specific features.</para>
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1695
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1696 <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	1697 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	1698 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	1699 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	1700 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	1701
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1702 </listitem>
507f442dc71e Add support for 6800 compatibility instructions. William Astle <lost@l-w.ca> parents: 324 diff changeset	1703
394 fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1704 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1705
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1706 <varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1707 <term>6809</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1708 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1709 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1710 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	1711 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	1712 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1713 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1714 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1715
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1716 <varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1717 <term>6309</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1718 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1719 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1720 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	1721 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	1722 to display 6309 timings.
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1723 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1724 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1725 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1726
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1727 <varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1728 <term>6809conv</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1729 <term>6309conv</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1730 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1731 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1732 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	1733 instruction sets respectively. For more information, see
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1734 <xref linkend="convinst">.
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1735 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1736 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1737 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1738
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1739
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	1740 <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	1741 <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	1742 <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	1743 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1744 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	1745 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	1746 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	1747 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	1748 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	1749 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1750 </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	1751 </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	1752
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1753 <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	1754 <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	1755 <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	1756 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1757 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	1758 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	1759 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	1760 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	1761 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	1762 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1763 </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	1764 </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	1765
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1766 <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	1767 <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	1768 <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	1769 <para>
2c24602be78f 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 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	1771 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	1772 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	1773 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	1774 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	1775 </para>
2c24602be78f 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 </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	1777 </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	1778
2c24602be78f 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 <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	1780 <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	1781 <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	1782 <para>
2c24602be78f 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 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	1784 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	1785 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	1786 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	1787 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	1788 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	1789 </para>
2c24602be78f 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 <para>
2c24602be78f 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 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	1792 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	1793 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	1794 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	1795 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	1796 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	1797 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	1798 </para>
2c24602be78f 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 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	1801 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	1802 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	1803 </para>
2c24602be78f 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 </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	1805 </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	1806
2c24602be78f 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>
253 ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1808 <term>export</term>
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1809 <listitem>
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1810
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1811 <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	1812 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	1813 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	1814 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	1815 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	1816 exported.</para>
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1817
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1818 </listitem>
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1819 </varlistentry>
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1820
ed1009bce533 Document the "export" pragma William Astle <lost@l-w.ca> parents: 245 diff changeset	1821 <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	1822 <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	1823 <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	1824
2c24602be78f 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 <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	1826 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	1827 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	1828
2c24602be78f 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 </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	1830 </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	1831
2c24602be78f 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 <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	1833 <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	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
2c24602be78f 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 <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	1837 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	1838 "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	1839
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1840 </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	1841 </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	1842
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1843 <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	1844 <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	1845 <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	1846
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	1847 <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	1848 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	1849 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	1850 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	1851 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	1852
2c24602be78f 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
2c24602be78f 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 </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	1855 </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	1856
60 9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1857 <varlistentry>
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1858 <term>shadow</term>
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1859 <listitem>
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1860
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1861 <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	1862 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	1863 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	1864 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	1865
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1866 </listitem>
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1867 </varlistentry>
9ded7e6fc1b0 Updated documentation to include recently added features lost@l-w.ca parents: 51 diff changeset	1868
111 c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1869 <varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1870 <term>nolist</term>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1871 <listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1872
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1873 <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	1874 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	1875 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	1876 assembly listing with dozens, hundreds, or thousands of irrelevant
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1877 symbols.</para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1878
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1879 </listitem>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1880 </varlistentry>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	1881
117 8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1882 <varlistentry>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1883 <term>autobranchlength</term>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1884 <listitem>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1885
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1886 <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	1887 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	1888 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	1889 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	1890 instructions tend to aquire.</para>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1891
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1892 <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	1893 relative branch instruction is used, its size will be automatically
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1894 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	1895 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	1896 will choose a size for the branch.</para>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1897
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1898 <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	1899 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	1900 < forcing 8 bit offsets and > forcing 16 bit offets.</para>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1901
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1902 <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	1903 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	1904 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	1905 *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	1906 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	1907
07e1fac76321 Added pragma to allow non case sensitive symbols William Astle <lost@l-w.ca> parents: 168 diff changeset	1908 <varlistentry>
07e1fac76321 Added pragma to allow non case sensitive symbols William Astle <lost@l-w.ca> parents: 168 diff changeset	1909 <term>nosymbolcase</term>
07e1fac76321 Added pragma to allow non case sensitive symbols William Astle <lost@l-w.ca> parents: 168 diff changeset	1910 <term>symbolnocase</term>
07e1fac76321 Added pragma to allow non case sensitive symbols William Astle <lost@l-w.ca> parents: 168 diff changeset	1911 <listitem>
117 8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1912
207 07e1fac76321 Added pragma to allow non case sensitive symbols William Astle <lost@l-w.ca> parents: 168 diff changeset	1913 <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	1914 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	1915 is referenced.</para>
117 8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1916
207 07e1fac76321 Added pragma to allow non case sensitive symbols William Astle <lost@l-w.ca> parents: 168 diff changeset	1917 <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	1918 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	1919 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	1920
210 5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1921 <varlistentry>
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1922 <term>condundefzero</term>
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1923 <listitem>
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1924
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1925 <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	1926 symbols in conditional expressions. Ordinarily, any symbol that is not
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1927 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	1928 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	1929 conditional is encountered will be treated as zero.</para>
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1930
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1931 <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	1932 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	1933 a symbol.</para>
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1934
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1935 <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	1936 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	1937 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	1938
5d969517db74 Added condundefzero pragma William Astle <lost@l-w.ca> parents: 207 diff changeset	1939
117 8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1940 </listitem>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1941 </varlistentry>
8e2523061ce9 Document the new autobranchlength pragma lost@l-w.ca parents: 111 diff changeset	1942
347 330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1943 <varlistentry>
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1944 <term>forwardrefmax</term>
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1945 <listitem>
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1946
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1947 <para>This pragma will disable forward reference optimization completely.
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1948 Ordinarily, LWASM will attempt to select the shortest possible addressing
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1949 mode for forward references. However, in many source files, especially
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1950 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	1951 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	1952 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	1953 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	1954 almost certainly vanishes completely. However, the cost of doing that
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1955 optimization remains and can result in a very long assembly time.</para>
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1956
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1957 <para>Enabling this pragma will cause all forward references to use the
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1958 maximum offset or address size, much the same has EDTASM and other pure
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1959 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	1960 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	1961 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	1962
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1963 <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	1964 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	1965 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	1966 pragma.</para>
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1967
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1968 <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	1969 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	1970 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	1971 not override the operand size override prefixes (< and >). It only
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1972 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	1973
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1974 </listitem>
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1975 </varlistentry>
330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	1976
394 fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1977 <varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1978 <term>qrts</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1979 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1980 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1981
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1982 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	1983 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	1984 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	1985 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	1986 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	1987 inserted RTS (39).
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1988 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1989 <programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1990 1D1E 7D1D1D TST WHICH1
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1991 1D21 2A0139 BMI ?RTS
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1992 1D24 BD1D65 JSR INV
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1993 </programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1994 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1995 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1996
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1997 <varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1998 <term>m80ext</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	1999 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2000 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2001
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2002 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	2003 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	2004 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	2005 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	2006 unmodified, vintage source code.
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2007 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2008 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2009
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2010 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	2011 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	2012 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	2013 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	2014 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	2015 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	2016 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	2017 behavior after the closing delimiter:
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2018 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2019 <programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2020 FCC "Greetings from 1982",13,0
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2021 </programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2022 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2023 </varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2024
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2025
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2026
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2027 <varlistentry>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2028 <term>testmode</term>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2029 <listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2030 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2031
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2032 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	2033 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	2034 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	2035 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	2036 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	2037 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	2038 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	2039
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2040 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2041 <programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2042 1D1E 7D1D1D TST WHICH1 ;.7d1d1d
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2043 1D21 2A0139 BMI ?RTS ;.2a0139
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2044 1D24 1D24 FDB * ;.1d24
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2045 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	2046 </programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2047 </listitem>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2048 </varlistentry>
347 330a66a0f45a Document the forwardrefmax pragma William Astle <lost@l-w.ca> parents: 345 diff changeset	2049
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	2050 </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	2051
111 c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	2052 <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	2053 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	2054 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	2055 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	2056 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	2057 *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	2058 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	2059 work.</para>
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	2060
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	2061 <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	2062 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	2063 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	2064 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	2065 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	2066 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	2067
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	2068
c0aedb1584af Updated manual to describe nolist pragma and pragma stacks lost@l-w.ca parents: 68 diff changeset	2069
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	2070 </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	2071
394 fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2072 <section id="convinst">
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2073 <title id="convinsttitle">Convenience Instructions</title>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2074 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2075
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2076 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	2077 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	2078 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	2079 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	2080 target both the 6809 and the 6309.
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2081 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2082
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
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2085 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	2086 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	2087 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	2088 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	2089 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2090 <para>
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 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	2093 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	2094 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	2095 NEGF, NEGW, NEGQ, TSTQ.
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2096 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2097 </section>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2098
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2099 <section>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2100 <title>Cycle Counts</title>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2101 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2102
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2103 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	2104 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	2105 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	2106 use the "OPT" keyword in addition to "PRAGMA."
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2107 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2108
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2109 <programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2110 opt c - enable cycle counts: [8]
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2111 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	2112 opt ct - show a running subtotal of cycles
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2113 opt cc - clear the running subtotal
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2114 </programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2115
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2116 <para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2117
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2118 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	2119 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	2120 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	2121 "+?" 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	2122 </para>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2123
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2124 <programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2125 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	2126 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	2127 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	2128 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	2129 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	2130 (window.asm):00318 opt 6309
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2131 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	2132 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	2133 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	2134 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	2135 2687 4a (window.asm):00323 (1) 52 deca
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2136 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	2137 </programlisting>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2138 </section>
fc166b3bbae3 Update manual for recent additions. William Astle <lost@l-w.ca> parents: 369 diff changeset	2139
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	2140 </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	2141
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2142 <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	2143 <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	2144 <para>
2c24602be78f 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 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	2146 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	2147 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2148
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2149 <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	2150 <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	2151 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2152 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	2153 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	2154 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2155 <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	2156 <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	2157 <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	2158 <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	2159 <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	2160 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2161 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	2162 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2163 </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	2164 </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	2165
2c24602be78f 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 <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	2167 <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	2168 <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	2169 <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	2170 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2171 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	2172 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	2173 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2174 </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	2175 </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	2176
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2177 <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	2178 <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	2179 <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	2180 <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	2181 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2182 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	2183 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	2184 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2185 </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	2186 </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	2187
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2188 <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	2189 <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	2190 <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	2191 <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	2192 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2193 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	2194 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	2195 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	2196 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2197 </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	2198 </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	2199
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2200 <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	2201 <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	2202 <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	2203 <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	2204 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2205 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	2206 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	2207 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2208 </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	2209 </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	2210
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2211 <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	2212 <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	2213 <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	2214 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2215 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	2216 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	2217 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2218 </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	2219 </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	2220
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2221 <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	2222 <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	2223 <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	2224 <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	2225 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2226 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	2227 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2228 </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	2229 </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	2230
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2231 <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	2232 <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	2233 <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	2234 <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	2235 <para>
2c24602be78f 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 Load a library using the library search path. LIBSPEC will have "lib" 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	2237 and ".a" appended.
2c24602be78f 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 </para>
2c24602be78f 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 </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	2240 </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	2241
2c24602be78f 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 <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	2243 <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	2244 <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	2245 <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	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 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	2248 </para>
2c24602be78f 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 </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	2250 </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	2251
2c24602be78f 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 <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	2253 <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	2254 <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	2255 <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	2256 <para>
2c24602be78f 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 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	2258 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	2259 </para>
2c24602be78f 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 </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	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
2c24602be78f 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 <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	2264 <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	2265 <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	2266 <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	2267 <para>
2c24602be78f 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 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	2269 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	2270 </para>
2c24602be78f 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 </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	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
2c24602be78f 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 <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	2275 <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	2276 <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	2277 <para>
2c24602be78f 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 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	2279 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	2280 </para>
2c24602be78f 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 </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	2282 </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	2283
2c24602be78f 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
2c24602be78f 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 <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	2286 <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	2287 <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	2288 <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	2289 <para>
2c24602be78f 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 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	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 </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	2296
2c24602be78f 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 <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	2298 <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	2299
2c24602be78f 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 <para>
2c24602be78f 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
2c24602be78f 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 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	2303 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	2304 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	2305 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	2306
2c24602be78f 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 </para>
2c24602be78f 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
2c24602be78f 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 <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	2310 <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	2311 <para>
2c24602be78f 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 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	2313 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	2314 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	2315 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	2316 </para>
2c24602be78f 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 </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	2318
2c24602be78f 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 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	2322 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	2323 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	2324 </para>
2c24602be78f 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 </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	2326
2c24602be78f 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 <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	2328 <para>
2c24602be78f 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 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	2330 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	2331 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	2332 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	2333 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	2334 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	2335 </para>
2c24602be78f 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 </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	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 <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	2339 <para>
2c24602be78f 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 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	2341 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	2342 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	2343 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	2344 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	2345 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	2346 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	2347 </para>
2c24602be78f 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 </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	2349
2c24602be78f 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 <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	2351 <para>
2c24602be78f 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 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	2353 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	2354 </para>
2c24602be78f 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 </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	2356 </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	2357
2c24602be78f 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 </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	2359
2c24602be78f 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 <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	2361 <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	2362 <para>
2c24602be78f 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 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	2364 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	2365 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	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 <para>
2c24602be78f 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 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	2369 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	2370 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	2371 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	2372 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	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
2c24602be78f 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 <para>
2c24602be78f 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 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	2377 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	2378 </para>
2c24602be78f 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 <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	2381 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	2382 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	2383 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	2384 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	2385 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	2386 </para>
2c24602be78f 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
2c24602be78f 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 <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	2389 <variablelist>
234 d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2390
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2391 <varlistentry>
236 ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2392 <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	2393 <listitem>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2394
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2395 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2396
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2397 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	2398 (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	2399 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	2400 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	2401 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	2402
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2403 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2404
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2405 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2406
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2407 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	2408 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	2409 on it.
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2410
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2411 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2412
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2413 </listitem>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2414
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2415 <varlistentry>
234 d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2416 <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	2417 <listitem>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2418
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2419 <para>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2420
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2421 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	2422 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	2423 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	2424 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	2425 section have been collapsed together.
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2426
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2427 </para>
236 ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2428
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2429 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2430
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2431 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	2432 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	2433 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	2434 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	2435 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	2436
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2437 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2438
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2439
234 d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2440 <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	2441 sections, the results are undefined.
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2442
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2443 </para>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2444 </listitem>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2445
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2446 <varlistentry>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2447 <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	2448 <listitem>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2449
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2450 <para>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2451
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2452 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	2453 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	2454 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	2455 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	2456 collapsed together.
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2457
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2458 </para>
236 ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2459
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2460 <para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2461
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2462 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	2463 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	2464 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	2465 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	2466 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	2467
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2468 </para>
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2469
ce1fdc8d6568 Added ability to add padding after a section when linking. William Astle <lost@l-w.ca> parents: 234 diff changeset	2470
234 d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2471 <para>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2472 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	2473 sections, the results are undefined.
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2474
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2475 </para>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2476 </listitem>
d389adbcc4ab Added section base and length symbols to lwlink William Astle <lost@l-w.ca> parents: 232 diff changeset	2477
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	2478 <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	2479 <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	2480 <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	2481
2c24602be78f 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 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	2483 <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	2484 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	2485 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	2486 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	2487 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	2488 </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	2489 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	2490 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	2491 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	2492 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	2493 </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	2494 </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	2495
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2496 <varlistentry>
316 c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2497 <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	2498 <listitem><para>
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2499
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2500 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	2501 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	2502 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	2503 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	2504 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	2505
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2506 </para><para>
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2507
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2508 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	2509 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	2510 $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	2511
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2512 </para></listitem>
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2513 </varlistentry>
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2514
c4853a54b4a1 Documented new "high" option for link scripts. William Astle <lost@l-w.ca> parents: 254 diff changeset	2515 <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	2516 <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	2517 <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	2518
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2519 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	2520 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	2521 </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	2522 <varlistentry>
68 99ce348b0e6b Fixed error in documentation - linkscripts use "entry" instead of "exec" lost@l-w.ca parents: 60 diff changeset	2523 <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	2524 <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	2525 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2526 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	2527 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	2528 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	2529 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	2530 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	2531 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	2532 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	2533 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	2534 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2535 </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	2536 </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	2537
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2538 <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	2539 <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	2540 <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	2541 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	2542 <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	2543 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2544 </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	2545 </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	2546 </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	2547
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2548
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2549
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2550 </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	2551
152 a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2552 <section>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2553 <title>Format Specific Linking Notes</title>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2554
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2555 <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	2556 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	2557 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	2558 a final binary.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2559
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2560 <section>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2561 <title>OS9 Modules</title>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2562
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2563 <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	2564 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	2565 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	2566 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	2567 values.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2568
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2569 <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	2570 ".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	2571
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2572 <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	2573 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	2574 objects to be linked.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2575
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2576 <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	2577 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	2578 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	2579
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2580 <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	2581 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	2582 what you want.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2583
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2584 <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	2585 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	2586 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	2587 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	2588 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	2589 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	2590 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	2591 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	2592 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	2593 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	2594 default values.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2595
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2596 <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	2597 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	2598 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	2599 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	2600 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	2601 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	2602 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	2603 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	2604 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	2605 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	2606
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2607 <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	2608 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	2609 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	2610 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	2611 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	2612 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	2613
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2614 <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	2615 (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	2616 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	2617 difference but it is unavoidable.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2618
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2619 <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	2620 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	2621 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	2622 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	2623 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	2624 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	2625 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	2626 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	2627 offset from U technique.</para>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2628
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2629 </section>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2630
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2631 </section>
a26b045c4e18 Added documentation about OS9 module support in lwlink lost@l-w.ca parents: 143 diff changeset	2632
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	2633 </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	2634
2c24602be78f 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 <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	2636 <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	2637
2c24602be78f 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 <para>
2c24602be78f 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 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	2640 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	2641 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	2642 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	2643 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	2644 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	2645 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	2646 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	2647 </para>
2c24602be78f 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 <para>
2c24602be78f 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 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	2651 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2652
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2653 <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	2654 <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	2655 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2656 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	2657 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	2658 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	2659 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	2660 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2661
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2662 <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	2663 <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	2664 <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	2665 <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	2666 <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	2667 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2668 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	2669 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	2670 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	2671 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2672 </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	2673 </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	2674
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2675 <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	2676 <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	2677 <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	2678 <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	2679 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2680 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	2681 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	2682 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2683 </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	2684 </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	2685
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2686 <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	2687 <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	2688 <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	2689 <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	2690 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2691 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	2692 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	2693 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	2694 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2695 </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	2696 </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	2697
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2698 <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	2699 <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	2700 <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	2701 <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	2702 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2703 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	2704 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2705 </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	2706 </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	2707
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2708 <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	2709 <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	2710 <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	2711 <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	2712 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2713 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	2714 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	2715 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2716 </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	2717 </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	2718
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2719 <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	2720 <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	2721 <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	2722 <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	2723 <para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2724 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	2725 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	2726 </para>
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2727 </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	2728 </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	2729
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization lost@l-w.ca parents: diff changeset	2730 <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	2731 <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	2732 <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	2733 <para>
2c24602be78f 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 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	2735 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	2736 </para>
2c24602be78f 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 </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	2738 </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	2739
2c24602be78f 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
2c24602be78f 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 <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	2742 <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	2743 <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	2744 <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	2745 <para>
2c24602be78f 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 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	2747 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	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 </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	2750 </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	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
2c24602be78f 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 </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	2755
2c24602be78f 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 <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	2757 <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	2758 <para>
2c24602be78f 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 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	2760 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	2761 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	2762 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	2763 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	2767 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	2768 "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	2769 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	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
2c24602be78f 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 <para>
2c24602be78f 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 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	2774 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	2775 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	2776
2c24602be78f 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 <para>
2c24602be78f 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 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	2779 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	2780 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	2781 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	2782 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	2786 </para>
2c24602be78f 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
2c24602be78f 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 <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	2789 <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	2790 <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	2791 <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	2792 <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	2793 <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	2794 <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	2795 </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	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 <para>
2c24602be78f 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 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	2799 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	2800 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	2801 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	2802 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	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
2c24602be78f 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 <para>
2c24602be78f 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 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	2807 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	2808 </para>
2c24602be78f 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
2c24602be78f 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 <para>
2c24602be78f 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 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	2812 (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	2813 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	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
2c24602be78f 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 <para>
2c24602be78f 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 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	2818 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	2819 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	2820 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	2821 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	2822 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	2823 </para>
2c24602be78f 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
2c24602be78f 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 <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	2826 <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	2827 <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	2828 <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	2829 <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	2830 <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	2831 </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	2832 </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	2833 <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	2834 <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	2835 <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	2836 <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	2837 </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	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 <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	2840 <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	2841 <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	2842 </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	2843 <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	2844 <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	2845 <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	2846 </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	2847
2c24602be78f 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 <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	2849 <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	2850 <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	2851 </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	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 <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	2854 <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	2855 <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	2856 </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	2857 <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	2858 <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	2859 <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	2860 </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	2861
2c24602be78f 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 <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	2863 <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	2864 <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	2865 </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	2866 </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	2867 </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	2868 </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	2869
2c24602be78f 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 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	2873 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	2874 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	2875 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	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
2c24602be78f 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 <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	2879 <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	2880 <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	2881 <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	2882 <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	2883 <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	2884 </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	2885 </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	2886 <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	2887 <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	2888 <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	2889 <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	2890 </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	2891 <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	2892 <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	2893 <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	2894 </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	2895 <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	2896 <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	2897 <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	2898 </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	2899 <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	2900 <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	2901 <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	2902 </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	2903 <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	2904 <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	2905 <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	2906 </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	2907 <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	2908 <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	2909 <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	2910 </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	2911
2c24602be78f 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 <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	2913 <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	2914 <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	2915 </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	2916
2c24602be78f 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 <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	2918 <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	2919 <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	2920 </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	2921
2c24602be78f 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 <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	2923 <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	2924 <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	2925 </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	2926
2c24602be78f 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>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	2929 <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	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
2c24602be78f 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 <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	2933 <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	2934 <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	2935 </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	2936
2c24602be78f 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 <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	2938 <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	2939 <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	2940 </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	2941
2c24602be78f 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>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	2944 <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	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 </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	2947 </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	2948 </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	2949
2c24602be78f 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 <para>
2c24602be78f 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 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	2952 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	2953 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	2954 </para>
2c24602be78f 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
2c24602be78f 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 </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	2957 </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	2958

Mercurial > hg > index.cgi

annotate docs/manual.docbook.sgml @ 436:9f49f0966c1e lwtools-4.14