Mercurial > hg > index.cgi
annotate docs/manual.docbook.sgml @ 91:95181f1ad183
Really fix memory leaks
author | lost@l-w.ca |
---|---|
date | Wed, 22 Jun 2011 19:06:14 -0600 |
parents | 99ce348b0e6b |
children | c0aedb1584af |
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> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
6 <copyright><year>2009, 2010</year><holder>William Astle</holder></copyright> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
7 </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
|
8 <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
|
9 |
2c24602be78f
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 <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
|
11 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
14 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
|
15 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
|
16 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
19 <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
|
20 <para> |
2c24602be78f
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 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
|
22 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
|
23 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
|
24 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
|
25 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
|
26 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
|
27 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
|
28 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
|
29 </para> |
2c24602be78f
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 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
33 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
|
34 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
|
35 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
|
36 </para> |
2c24602be78f
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 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
40 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
|
41 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
|
42 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
|
43 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
|
44 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
|
45 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
|
46 </para> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
49 |
2c24602be78f
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 </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
|
51 |
2c24602be78f
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 <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
|
53 <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
|
54 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
57 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
|
58 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
61 <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
|
62 <para> |
2c24602be78f
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 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
|
64 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
|
65 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
|
66 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
|
67 </para> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
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 <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
|
72 |
2c24602be78f
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 <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
|
74 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
|
75 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
|
76 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
|
77 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
|
78 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
81 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
|
82 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
|
83 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
|
84 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
|
85 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
|
86 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
|
87 </para> |
2c24602be78f
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 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
91 </para> |
2c24602be78f
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 </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
|
93 |
2c24602be78f
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 <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
|
95 <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
|
96 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
97 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
98 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
|
99 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
|
100 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
|
101 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
|
102 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
103 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
104 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
105 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
106 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
107 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
|
108 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
|
109 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
|
110 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
|
111 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
|
112 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
113 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
114 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
115 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
116 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
117 It is also critical to understand that unlike many OS9 assemblers, 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
|
118 does NOT maintain a separate data address counter. Thus, you must define |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
119 all your data offsets and so on outside of the mod/emod segment. 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
|
120 therefore, likely that source code targeted at other assemblers will require |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
121 edits to build correctly. |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
122 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
123 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
124 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
125 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
126 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
127 LWLINK does not, yet, have the ability to create OS9 modules from 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
|
128 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
|
129 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
130 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
131 </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
|
132 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
133 <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
|
134 <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
|
135 <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
|
136 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
|
137 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
|
138 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
|
139 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
140 <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
|
141 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
|
142 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
|
143 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
144 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
145 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
|
146 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
|
147 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
|
148 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
|
149 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
|
150 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
|
151 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
152 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
153 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
154 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
|
155 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
|
156 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
|
157 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
|
158 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
159 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
160 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
161 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
|
162 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
|
163 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
|
164 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
165 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
166 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
167 </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
|
168 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
169 </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
|
170 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
171 <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
|
172 <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
|
173 <para> |
2c24602be78f
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 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
|
175 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
|
176 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
|
177 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
180 <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
|
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 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
|
183 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
|
184 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
187 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
190 <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
|
191 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
194 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
|
195 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
|
196 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
197 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
198 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
199 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
200 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
201 <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
|
202 <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
|
203 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
204 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
205 This will cause the assembler to reject instructions that are only 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
|
206 on the 6309 processor. |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
207 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
208 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
209 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
210 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
211 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
212 <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
|
213 <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
|
214 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
217 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
218 <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
|
219 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
|
220 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
|
221 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
|
222 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
227 <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
|
228 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
231 object file target, <option>decb</option> for the DECB LOADM 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
|
232 <option>os9</option> for creating OS9 modules, and <option>raw</option> 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
|
233 a raw 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
240 <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
|
241 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
244 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
|
245 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
|
246 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
|
247 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
253 <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
|
254 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
257 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
|
258 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
264 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
273 <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
|
274 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
277 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
|
278 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
284 <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
|
285 <listitem> |
2c24602be78f
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> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
287 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
|
288 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
|
289 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
|
290 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
294 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
295 <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
|
296 <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
|
297 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
298 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
299 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
|
300 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
301 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
302 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
306 <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
|
307 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
308 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
309 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
|
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>--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
|
316 <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
|
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 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
326 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
329 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
335 <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
|
336 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
337 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
338 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
|
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>--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
|
345 <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
|
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 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
|
349 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
|
350 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
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 </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
|
357 |
2c24602be78f
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 <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
|
359 <title>Dialects</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
|
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 LWASM supports all documented MC6809 instructions as defined by Motorola. |
2c24602be78f
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 also supports all known HD6309 instructions. While there is 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
|
363 agreement on the pneumonics for most of the 6309 instructions, there is some |
2c24602be78f
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 variance with the block transfer instructions. TFM for all four variations |
2c24602be78f
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 seems to have gained the most traction and, thus, this is the form that 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
|
366 recommended for LWASM. However, it also supports COPY, COPY-, IMP, EXP, |
2c24602be78f
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 TFRP, TFRM, TFRS, and TFRR. It further adds COPY+ as a synomym for COPY, |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
368 IMPLODE for IMP, and EXPAND for EXP. |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
369 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
370 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
371 <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
|
372 <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
|
373 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
|
374 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
375 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
376 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
|
377 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
|
378 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
|
379 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
380 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
381 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
382 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
|
383 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
|
384 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
|
385 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
|
386 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
387 |
2c24602be78f
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 </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
|
389 |
2c24602be78f
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 <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
|
391 <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
|
392 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
395 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
|
396 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
|
397 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
400 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
|
401 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
|
402 <para> |
2c24602be78f
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 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
|
404 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
|
405 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
|
406 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
|
407 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
408 |
2c24602be78f
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 <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
|
410 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
|
411 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
|
412 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
|
413 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
|
414 |
2c24602be78f
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 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
|
417 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
|
418 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
|
419 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
|
420 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
421 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
422 <para> |
2c24602be78f
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 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
|
424 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
|
425 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
|
426 </para> |
2c24602be78f
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 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
430 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
|
431 </para> |
2c24602be78f
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 |
2c24602be78f
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> 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
|
434 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
|
435 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
|
436 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
|
437 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
|
438 </para> |
2c24602be78f
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 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
440 </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
|
441 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
442 <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
|
443 <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
|
444 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
445 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
446 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
|
447 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
|
448 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
|
449 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
450 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
451 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
452 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
|
453 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
|
454 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
|
455 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
|
456 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
|
457 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
|
458 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
|
459 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
|
460 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
461 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
462 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
463 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
|
464 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
|
465 "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
|
466 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
|
467 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
|
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 |
2c24602be78f
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 </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
|
471 |
2c24602be78f
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 <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
|
473 <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
|
474 <para> |
2c24602be78f
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 |
2c24602be78f
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 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
|
477 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
|
478 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
|
479 "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
|
480 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
|
481 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
|
482 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
|
483 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
|
484 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
|
485 |
2c24602be78f
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 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
489 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
|
490 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
|
491 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
492 <para>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
|
493 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
|
494 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
|
495 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
496 <para> |
2c24602be78f
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 |
2c24602be78f
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 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
|
499 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
|
500 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
|
501 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
|
502 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
|
503 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
|
504 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
|
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 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
510 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
|
511 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
|
512 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
|
513 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
|
514 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
|
515 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
516 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
517 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
518 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
519 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
520 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
|
521 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
|
522 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
|
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> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
525 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
526 </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
|
527 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
528 <section> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
529 <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
|
530 <para> |
2c24602be78f
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 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
|
532 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
|
533 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
|
534 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
|
535 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
538 <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
|
539 <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
|
540 <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
|
541 <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
|
542 <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
|
543 <listitem> |
2c24602be78f
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 <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
|
545 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
550 <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
|
551 <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
|
552 <listitem> |
2c24602be78f
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 <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
|
554 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
559 <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
|
560 <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
|
561 <listitem> |
2c24602be78f
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>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
|
563 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
568 <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
|
569 <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
|
570 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
573 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
|
574 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
581 <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
|
582 <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
|
583 <listitem> |
2c24602be78f
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 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
|
586 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
|
587 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
|
588 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
|
589 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
595 <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
|
596 <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
|
597 <listitem> |
2c24602be78f
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 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
|
600 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
|
601 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
607 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
608 <para> |
2c24602be78f
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 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
|
610 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
|
611 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <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
|
616 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
619 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
|
620 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <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
|
626 <listitem> |
2c24602be78f
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 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
|
629 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
|
630 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
|
631 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
637 <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
|
638 <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
|
639 <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
|
640 <listitem> |
2c24602be78f
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> |
2c24602be78f
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 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
|
643 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
|
644 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
|
645 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <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
|
650 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
653 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
|
654 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
|
655 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <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
|
660 <listitem> |
2c24602be78f
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 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
|
663 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
|
664 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
|
665 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
671 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
674 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
|
675 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
|
676 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
|
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 <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
|
680 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
|
681 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
|
682 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
683 <para> 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
|
684 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
|
685 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
|
686 |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 </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
|
691 |
2c24602be78f
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 </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
|
693 |
2c24602be78f
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 <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
|
695 <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
|
696 <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
|
697 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
|
698 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
699 <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
|
700 <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
|
701 <listitem> |
2c24602be78f
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 <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
|
703 first pass so no external or forward references are permitted. ORG 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
|
704 permitted within sections when outputting to object files. For the DECB |
2c24602be78f
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 target, each ORG directive after which output is generated 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
|
706 a new preamble to be output. ORG is only used to determine the 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
|
707 of symbols when the raw target 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
|
708 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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><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
|
714 <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
|
715 <listitem> |
2c24602be78f
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 <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
|
717 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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><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
|
722 <listitem> |
2c24602be78f
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 <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
|
724 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
|
725 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
|
726 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
|
727 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
728 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
732 <listitem> |
2c24602be78f
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 <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
|
734 <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
|
735 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
|
736 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
|
737 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
|
738 </para> |
2c24602be78f
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 <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
|
740 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
746 <listitem> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
749 <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
|
750 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
|
751 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
|
752 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
|
753 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
|
754 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
|
755 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
|
756 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
|
757 |
2c24602be78f
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 <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
|
759 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
|
760 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
|
761 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
|
762 |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
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 </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
|
769 |
2c24602be78f
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 <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
|
771 <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
|
772 <para> |
2c24602be78f
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 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
|
774 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
|
775 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
|
776 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
777 <para>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
|
778 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
|
779 </para> |
2c24602be78f
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>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
|
781 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
|
782 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
|
783 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
|
784 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
|
785 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
|
786 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
|
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 <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
|
789 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
|
790 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
|
791 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
|
792 |
2c24602be78f
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 <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
|
794 <varlistentry> |
2c24602be78f
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 <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
|
796 <listitem> |
2c24602be78f
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 <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
|
798 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
|
799 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
805 <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
|
806 <listitem> |
2c24602be78f
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 <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
|
808 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
|
809 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
814 <term>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
|
815 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
816 <para>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
|
817 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
|
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>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
|
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>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
|
826 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
|
827 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
833 <listitem> |
2c24602be78f
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 <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
|
835 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
|
836 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
837 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
842 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
843 <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
|
844 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
|
845 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
846 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
847 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
848 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
849 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
850 <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
|
851 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
852 <para>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
|
853 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
|
854 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
|
855 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
861 <listitem> |
2c24602be78f
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 <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
|
863 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
|
864 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
|
865 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
868 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
869 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
870 <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
|
871 <listitem> |
2c24602be78f
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 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
|
874 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
|
875 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
|
876 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
|
877 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
|
878 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
|
879 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
880 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
881 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
882 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
883 <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
|
884 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
885 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
886 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
|
887 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
|
888 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
889 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
893 </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
|
894 |
2c24602be78f
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 <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
|
896 <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
|
897 |
2c24602be78f
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 <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
|
899 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
|
900 |
2c24602be78f
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 <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
|
902 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
905 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 |
2c24602be78f
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 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
|
909 |
2c24602be78f
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> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
916 <listitem> |
2c24602be78f
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 |
2c24602be78f
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 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
|
920 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
|
921 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
|
922 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
923 </para> |
2c24602be78f
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> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
926 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
927 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
|
928 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
|
929 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
930 </para> |
2c24602be78f
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 |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
937 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
941 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
|
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 </para> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
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 |
2c24602be78f
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 <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
|
950 <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
|
951 |
2c24602be78f
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 <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
|
953 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
|
954 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
955 <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
|
956 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
959 <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
|
960 |
2c24602be78f
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 <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
|
962 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
|
963 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
|
964 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
|
965 </para> |
2c24602be78f
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 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
969 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
|
970 |
2c24602be78f
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 <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
|
972 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
|
973 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
|
974 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
|
975 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
|
976 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
|
977 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
|
978 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
985 <listitem> |
2c24602be78f
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 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
|
988 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
|
989 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
|
990 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
|
991 </para> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
994 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
995 <varlistentry> |
2c24602be78f
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 <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
|
997 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1000 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
|
1001 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
|
1002 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
|
1003 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1009 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1012 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
|
1013 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
|
1014 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
|
1015 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
|
1016 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1017 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1018 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1019 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1020 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1021 <term>.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
|
1022 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1023 <para> |
2c24602be78f
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 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
|
1025 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
|
1026 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
|
1027 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1030 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1031 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1032 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
1035 </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
|
1036 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1037 </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
|
1038 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1039 <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
|
1040 <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
|
1041 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1042 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
|
1043 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
|
1044 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
|
1045 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
|
1046 </para> |
60
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1047 |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1048 <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
|
1049 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
|
1050 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
|
1051 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
|
1052 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
|
1053 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
|
1054 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
|
1055 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
|
1056 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
|
1057 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
|
1058 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
|
1059 |
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
|
1060 <para> |
2c24602be78f
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 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
|
1062 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
|
1063 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
|
1064 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1067 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
|
1068 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
|
1069 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
|
1070 |
2c24602be78f
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 <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
|
1072 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
|
1073 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
|
1074 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
|
1075 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
|
1076 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
|
1077 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
|
1078 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
|
1079 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
|
1080 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1083 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
|
1084 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
|
1085 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
|
1086 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1090 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
|
1091 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
|
1092 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
1095 |
2c24602be78f
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 <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
|
1097 <varlistentry> |
51
fd1ecc5d6e69
Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents:
0
diff
changeset
|
1098 <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
|
1099 <listitem> |
2c24602be78f
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 <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
|
1101 <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
|
1102 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
|
1103 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
|
1104 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
|
1105 </para> |
51
fd1ecc5d6e69
Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents:
0
diff
changeset
|
1106 |
fd1ecc5d6e69
Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents:
0
diff
changeset
|
1107 <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
|
1108 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
|
1109 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
|
1110 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
|
1111 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
|
1112 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
|
1113 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
|
1114 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
|
1115 define symbols that should be visible.</para> |
fd1ecc5d6e69
Added mention of NOEXPAND macro argument in manual
lost@l-w.ca
parents:
0
diff
changeset
|
1116 |
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
|
1117 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1119 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1120 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1121 <term>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
|
1122 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1123 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1124 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
|
1125 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
|
1126 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </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
|
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 </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
|
1131 |
2c24602be78f
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 <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
|
1133 <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
|
1134 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1135 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1136 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
|
1137 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
|
1138 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
|
1139 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
|
1140 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
|
1141 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1142 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1143 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1144 <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
|
1145 <varlistentry> |
2c24602be78f
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><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
|
1147 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 |
2c24602be78f
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 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
|
1151 <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
|
1152 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1159 <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
|
1160 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1163 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
|
1164 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 </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
|
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 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1171 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1172 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
|
1173 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
|
1174 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
1177 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
|
1178 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
|
1179 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
|
1180 |
2c24602be78f
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 <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
|
1182 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
|
1183 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
|
1184 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
|
1185 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
|
1186 |
2c24602be78f
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 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
|
1188 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
|
1189 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
|
1190 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
|
1191 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
|
1192 |
2c24602be78f
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 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
|
1194 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
|
1195 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
|
1196 </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
|
1197 |
2c24602be78f
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 <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
|
1199 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
|
1200 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
|
1201 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
|
1202 |
2c24602be78f
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>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
|
1204 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
|
1205 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
|
1206 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
|
1207 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1208 <para>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
|
1209 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
|
1210 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
|
1211 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
|
1212 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
|
1213 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
|
1214 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
|
1215 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
|
1216 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
|
1217 (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
|
1218 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
|
1219 {$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
|
1220 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
|
1221 ($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
|
1222 |
2c24602be78f
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 </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
|
1224 |
2c24602be78f
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 <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
|
1226 <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
|
1227 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1228 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
|
1229 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
|
1230 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
|
1231 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
|
1232 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
|
1233 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
|
1234 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
|
1235 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
|
1236 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
|
1237 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1238 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1239 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1240 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
|
1241 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
|
1242 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
|
1243 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
|
1244 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
|
1245 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
|
1246 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
|
1247 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
|
1248 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
|
1249 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
|
1250 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
|
1251 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
|
1252 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
|
1253 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
|
1254 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1255 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1256 <para> |
2c24602be78f
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 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
|
1258 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
|
1259 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
|
1260 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
|
1261 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
|
1262 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
|
1263 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
|
1264 </para> |
2c24602be78f
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 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1268 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
|
1269 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
|
1270 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
|
1271 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
|
1272 </para> |
2c24602be78f
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 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1276 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
|
1277 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
|
1278 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
|
1279 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
|
1280 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
|
1281 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1282 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1285 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
|
1286 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
|
1287 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
|
1288 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
|
1289 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
|
1290 </para> |
2c24602be78f
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 |
2c24602be78f
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> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1293 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
|
1294 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
|
1295 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
|
1296 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
|
1297 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
|
1298 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
|
1299 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
|
1300 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
|
1301 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
|
1302 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
|
1303 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1304 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1305 <para>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
|
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 <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
|
1308 <varlistentry> |
2c24602be78f
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 <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
|
1310 <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
|
1311 <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
|
1312 <listitem> |
2c24602be78f
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 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
|
1315 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
|
1316 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
|
1317 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
|
1318 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
|
1319 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
|
1320 </para> |
2c24602be78f
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>There is a single flag supported in <parameter>flags</parameter>. 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
|
1322 flag <parameter>bss</parameter> will cause the section to be treated as a BSS |
2c24602be78f
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 section and, thus, no code will be included in the object file nor will 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
|
1324 bytes be permitted to be 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
|
1325 <para> |
2c24602be78f
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 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
|
1327 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
|
1328 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
|
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 <para> |
2c24602be78f
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 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
|
1332 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
|
1333 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
|
1334 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1340 <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
|
1341 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1344 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
|
1345 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
|
1346 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
|
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1352 <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
|
1353 <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
|
1354 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1357 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
|
1358 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
|
1359 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
|
1360 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
|
1361 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
|
1362 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
|
1363 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1364 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1365 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1366 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1367 <varlistentry> |
2c24602be78f
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 <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
|
1369 <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
|
1370 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1371 <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
|
1372 <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
|
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 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1377 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
|
1378 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
|
1379 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1382 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
|
1383 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
|
1384 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1386 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1387 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1388 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1389 <varlistentry> |
2c24602be78f
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 <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
|
1391 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1392 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1393 <para>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
|
1394 <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
|
1395 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
|
1396 |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 </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
|
1400 |
2c24602be78f
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 </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
|
1402 |
2c24602be78f
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 <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
|
1404 <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
|
1405 <para> |
2c24602be78f
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 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
|
1407 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
|
1408 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
|
1409 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
|
1410 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
|
1411 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
|
1412 </para> |
2c24602be78f
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 |
2c24602be78f
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>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
|
1415 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
|
1416 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
|
1417 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
|
1418 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1419 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1420 <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
|
1421 <varlistentry> |
2c24602be78f
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 <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
|
1423 <listitem> |
2c24602be78f
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 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
|
1426 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
|
1427 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
|
1428 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
|
1429 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1435 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1438 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
|
1439 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
|
1440 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
|
1441 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
|
1442 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 </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
|
1446 |
2c24602be78f
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 <para>Each pragma supported has a positive version and a negative 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
|
1448 The positive version enables the pragma while the negative version disables |
2c24602be78f
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 it. The negatitve version is simply the positive version with "no" 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
|
1450 to it. For instance, "pragma" vs. "nopragma". Only the positive version 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
|
1451 listed 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
|
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>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
|
1454 |
2c24602be78f
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 <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
|
1456 <varlistentry> |
2c24602be78f
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 <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
|
1458 <listitem> |
2c24602be78f
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 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
|
1461 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
|
1462 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
|
1463 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
|
1464 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
|
1465 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1471 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1474 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
|
1475 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
|
1476 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
|
1477 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
|
1478 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1484 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1487 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
|
1488 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
|
1489 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
|
1490 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
|
1491 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1492 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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>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
|
1497 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1498 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1499 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
|
1500 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
|
1501 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
|
1502 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
|
1503 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
|
1504 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
|
1505 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1508 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
|
1509 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
|
1510 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
|
1511 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
|
1512 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
|
1513 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
|
1514 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1515 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1516 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
|
1517 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
|
1518 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
|
1519 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1520 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1521 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1525 <listitem> |
2c24602be78f
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 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1527 <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
|
1528 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
|
1529 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
|
1530 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1531 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1532 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1536 <listitem> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
1539 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
|
1540 "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
|
1541 |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1547 <listitem> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
1550 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
|
1551 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
|
1552 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
|
1553 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
|
1554 |
2c24602be78f
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 |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
60
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1559 <varlistentry> |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1560 <term>shadow</term> |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1561 <listitem> |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1562 |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1563 <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
|
1564 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
|
1565 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
|
1566 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
|
1567 |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1568 </listitem> |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1569 </varlistentry> |
9ded7e6fc1b0
Updated documentation to include recently added features
lost@l-w.ca
parents:
51
diff
changeset
|
1570 |
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
|
1571 </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
|
1572 |
2c24602be78f
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 </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
|
1574 |
2c24602be78f
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 </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
|
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 <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
|
1578 <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
|
1579 <para> |
2c24602be78f
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 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
|
1581 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
|
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 |
2c24602be78f
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 <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
|
1585 <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
|
1586 <para> |
2c24602be78f
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 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
|
1588 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
|
1589 </para> |
2c24602be78f
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 <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
|
1591 <varlistentry> |
2c24602be78f
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 <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
|
1593 <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
|
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 <para> |
2c24602be78f
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 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
|
1597 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
1603 <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
|
1604 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1607 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
|
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1614 <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
|
1615 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1618 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
|
1619 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1625 <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
|
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 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
|
1629 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
|
1630 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
|
1631 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1637 <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
|
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 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
|
1641 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
|
1642 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
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 |
2c24602be78f
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 <varlistentry> |
2c24602be78f
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 <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
|
1648 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1649 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1650 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
|
1651 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
|
1652 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1653 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1654 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1655 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1656 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1657 <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
|
1658 <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
|
1659 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1660 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1661 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
|
1662 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1663 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1664 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1665 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1666 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1667 <term><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
|
1668 <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
|
1669 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1670 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1671 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
|
1672 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
|
1673 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1674 </listitem> |
2c24602be78f
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 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1676 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1677 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1678 <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
|
1679 <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
|
1680 <listitem> |
2c24602be78f
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> |
2c24602be78f
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 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
|
1683 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1684 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1685 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1686 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1687 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1688 <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
|
1689 <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
|
1690 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1691 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1692 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
|
1693 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
|
1694 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1695 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1696 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1697 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1698 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1699 <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
|
1700 <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
|
1701 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1702 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1703 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
|
1704 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
|
1705 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1706 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1707 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1708 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1709 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1710 <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
|
1711 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1712 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1713 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
|
1714 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
|
1715 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1716 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1717 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1718 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1719 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1720 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1721 <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
|
1722 <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
|
1723 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1724 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1725 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
|
1726 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1727 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1728 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1729 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1730 </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
|
1731 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1732 <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
|
1733 <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
|
1734 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1735 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1736 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1737 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
|
1738 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
|
1739 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
|
1740 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
|
1741 |
2c24602be78f
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 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
1745 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1748 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
|
1749 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
|
1750 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
|
1751 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 |
2c24602be78f
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 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1757 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
|
1758 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
|
1759 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 |
2c24602be78f
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 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1765 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
|
1766 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
|
1767 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
|
1768 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
|
1769 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
|
1770 </para> |
2c24602be78f
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 </listitem> |
2c24602be78f
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 |
2c24602be78f
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 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1776 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
|
1777 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
|
1778 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
|
1779 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
|
1780 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
|
1781 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
|
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 </listitem> |
2c24602be78f
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 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1785 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1786 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1787 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
|
1788 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
|
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 </listitem> |
2c24602be78f
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 </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
|
1792 |
2c24602be78f
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 </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
|
1794 |
2c24602be78f
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 <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
|
1796 <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
|
1797 <para> |
2c24602be78f
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 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
|
1799 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
|
1800 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
|
1801 </para> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1804 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
|
1805 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
|
1806 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
|
1807 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
|
1808 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1809 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1810 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1811 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
|
1812 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
|
1813 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1814 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1815 <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
|
1816 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
|
1817 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
|
1818 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
|
1819 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
|
1820 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
|
1821 </para> |
2c24602be78f
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 |
2c24602be78f
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 <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
|
1824 <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
|
1825 <varlistentry> |
2c24602be78f
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 <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
|
1827 <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
|
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 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
|
1830 <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
|
1831 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
|
1832 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
|
1833 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
|
1834 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
|
1835 </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
|
1836 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
|
1837 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
|
1838 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
|
1839 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
|
1840 </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
|
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>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
|
1845 <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
|
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 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
|
1848 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
|
1849 </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
|
1850 <varlistentry> |
68
99ce348b0e6b
Fixed error in documentation - linkscripts use "entry" instead of "exec"
lost@l-w.ca
parents:
60
diff
changeset
|
1851 <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
|
1852 <listitem> |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
1855 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
|
1856 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
|
1857 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
|
1858 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
|
1859 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
|
1860 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
|
1861 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
|
1862 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1863 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1864 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1865 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1866 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1867 <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
|
1868 <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
|
1869 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
|
1870 <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
|
1871 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1872 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1873 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1874 </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
|
1875 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1876 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1877 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1878 </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
|
1879 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1880 </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
|
1881 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1882 <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
|
1883 <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
|
1884 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1885 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1886 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
|
1887 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
|
1888 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
|
1889 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
|
1890 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
|
1891 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
|
1892 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
|
1893 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
|
1894 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1895 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1896 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1897 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
|
1898 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1899 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1900 <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
|
1901 <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
|
1902 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1903 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
|
1904 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
|
1905 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
|
1906 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
|
1907 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1908 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1909 <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
|
1910 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1911 <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
|
1912 <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
|
1913 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1914 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1915 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
|
1916 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
|
1917 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
|
1918 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1919 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1920 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1921 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1922 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1923 <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
|
1924 <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
|
1925 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1926 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1927 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
|
1928 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
|
1929 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1930 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1931 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1932 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1933 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1934 <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
|
1935 <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
|
1936 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1937 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1938 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
|
1939 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
|
1940 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
|
1941 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1942 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1943 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1944 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1945 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1946 <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
|
1947 <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
|
1948 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1949 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1950 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
|
1951 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1952 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1953 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1954 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1955 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1956 <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
|
1957 <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
|
1958 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1959 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1960 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
|
1961 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
|
1962 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1963 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1964 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1965 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1966 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1967 <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
|
1968 <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
|
1969 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1970 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1971 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
|
1972 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
|
1973 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1974 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1975 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1976 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1977 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1978 <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
|
1979 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1980 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1981 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
|
1982 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
|
1983 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1984 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1985 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1986 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1987 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1988 <varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1989 <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
|
1990 <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
|
1991 <listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1992 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1993 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
|
1994 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
|
1995 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1996 </listitem> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1997 </varlistentry> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1998 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
1999 </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
|
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
|
2001 </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
|
2002 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2003 <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
|
2004 <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
|
2005 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2006 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
|
2007 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
|
2008 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
|
2009 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
|
2010 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2011 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2012 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2013 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
|
2014 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
|
2015 "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
|
2016 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
|
2017 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2018 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2019 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2020 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
|
2021 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
|
2022 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
|
2023 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2024 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2025 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
|
2026 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
|
2027 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
|
2028 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
|
2029 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2030 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2031 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2032 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
|
2033 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2034 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2035 <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
|
2036 <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
|
2037 <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
|
2038 <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
|
2039 <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
|
2040 <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
|
2041 <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
|
2042 </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
|
2043 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2044 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2045 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
|
2046 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
|
2047 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
|
2048 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
|
2049 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
|
2050 </para> |
2c24602be78f
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 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2052 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2053 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
|
2054 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
|
2055 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2056 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2057 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2058 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
|
2059 (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
|
2060 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
|
2061 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2062 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2063 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2064 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
|
2065 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
|
2066 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
|
2067 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
|
2068 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
|
2069 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
|
2070 </para> |
2c24602be78f
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 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2072 <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
|
2073 <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
|
2074 <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
|
2075 <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
|
2076 <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
|
2077 <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
|
2078 </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
|
2079 </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
|
2080 <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
|
2081 <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
|
2082 <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
|
2083 <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
|
2084 </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
|
2085 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2086 <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
|
2087 <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
|
2088 <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
|
2089 </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
|
2090 <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
|
2091 <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
|
2092 <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
|
2093 </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
|
2094 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2095 <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
|
2096 <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
|
2097 <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
|
2098 </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
|
2099 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2100 <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
|
2101 <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
|
2102 <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
|
2103 </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
|
2104 <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
|
2105 <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
|
2106 <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
|
2107 </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
|
2108 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2109 <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
|
2110 <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
|
2111 <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
|
2112 </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
|
2113 </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
|
2114 </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
|
2115 </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
|
2116 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2117 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2118 <para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2119 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
|
2120 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
|
2121 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
|
2122 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
|
2123 </para> |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2124 |
2c24602be78f
Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff
changeset
|
2125 <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
|
2126 <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
|
2127 <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
|
2128 <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
|
2129 <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
|
2130 <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
|
2131 </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
|
2132 </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
|
2133 <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
|
2134 <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
|
2135 <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
|
2136 <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
|
2137 </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
|
2138 <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
|
2139 <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
|
2140 <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
|
2141 </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
|
2142 <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
|
2143 <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
|
2144 <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
|
2145 </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
|
2146 <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
|
2147 <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
|
2148 <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
|
2149 </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
|
2150 <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
|
2151 <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
|
2152 <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
|
2153 </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
|
2154 <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
|
2155 <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
|
2156 <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
|
2157 </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
|
2158 |
2c24602be78f
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 <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
|
2160 <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
|
2161 <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
|
2162 </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
|
2163 |
2c24602be78f
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 <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
|
2165 <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
|
2166 <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
|
2167 </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
|
2168 |
2c24602be78f
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 <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
|
2170 <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
|
2171 <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
|
2172 </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
|
2173 |
2c24602be78f
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 <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
|
2175 <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
|
2176 <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
|
2177 </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
|
2178 |
2c24602be78f
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 <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
|
2180 <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
|
2181 <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
|
2182 </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
|
2183 |
2c24602be78f
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 <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
|
2185 <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
|
2186 <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
|
2187 </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
|
2188 |
2c24602be78f
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 <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
|
2190 <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
|
2191 <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
|
2192 </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
|
2193 </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
|
2194 </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
|
2195 </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
|
2196 |
2c24602be78f
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 <para> |
2c24602be78f
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 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
|
2199 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
|
2200 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
|
2201 </para> |
2c24602be78f
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 |
2c24602be78f
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 </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
|
2204 </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
|
2205 |