Mercurial > hg-old > index.cgi

comparison doc/manual.docbook.sgml @ 109:f21a5593a661

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs
author lost
date Wed, 28 Jan 2009 05:38:21 +0000
parents
children afe30454382f
comparison
equal deleted inserted replaced
108:bf03d06df1fd 109:f21a5593a661
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
2 <book>
3 <bookinfo>
4 <title>LW Tool Chain</title>
5 <author><firstname>William</firstname><surname>Astle</surname></author>
6 <copyright><year>2009</year><holder>William Astle</holder></copyright>
7 </bookinfo>
8 <chapter>
9
10 <title>Introduction</title>
11
12 <para>
13 The LW tool chain provides utilities for building binaries for MC6809 and
14 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
15 which support several styles of output.
16 </para>
17
18 <section>
19 <title>History</title>
20 <para>
21 For a long time, I have had an interest in creating an operating system for
22 the Coco3. I finally started working on that project around the beginning of
23 2006. I had a number of assemblers I could choose from. Eventually, I settled
24 on one and started tinkering. After a while, I realized that assembler was not
25 going to be sufficient due to lack of macros and issues with forward references.
26 Then I tried another which handled forward references correctly but still did
27 not support macros. I looked around at other assemblers and they all lacked
28 one feature or another that I really wanted for creating my operating system.
29 </para>
30
31 <para>
32 The solution seemed clear at that point. I am a fair programmer so I figured
33 I could write an assembler that would do everything I wanted an assembler to
34 do. Thus the LWASM probject was born. After more than two years of on and off
35 work, version 1.0 of LWASM was released in October of 2008.
36 </para>
37
38 <para>
39 As the aforementioned operating system project progressed further, it became
40 clear that while assembling the whole project through a single file was doable,
41 it was not practical. When I found myself playing some fancy games with macros
42 in a bid to simulate sections, I realized I needed a means of assembling
43 source files separately and linking them later. This spawned a major development
44 effort to add an object file support to LWASM. It also spawned the LWLINK
45 project to provide a means to actually link the files.
46 </para>
47
48 </section>
49
50 </chapter>
51
52 <chapter>
53 <title>Output Formats</title>
54
55 <para>
56 The LW tool chain supports multiple output formats. Each format has its
57 advantages and disadvantages. Each format is described below.
58 </para>
59
60 <section>
61 <title>Raw Binaries</title>
62 <para>
63 A raw binary is simply a string of bytes. There are no headers or other
64 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
65 in the source code only serve to set the addresses that will be used for
66 symbols but otherwise have no direct impact on the resulting binary.
67 </para>
68
69 </section>
70 <section>
71 <title>DECB Binaries</title>
72
73 <para>A DECB binary is compatible with the LOADM command in Disk Extended
74 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
75 Color Basic. These binaries include the load address of the binary as well
76 as encoding an execution address. These binaries may contain multiple loadable
77 sections, each of which has its own load address.</para>
78
79 <para>
80 Each binary starts with a preamble. Each preamble is five bytes long. The
81 first byte is zero. The next two bytes specify the number of bytes to load
82 and the last two bytes specify the address to load the bytes at. Then, a
83 string of bytes follows. After this string of bytes, there may be another
84 preamble or a postamble. A postamble is also five bytes in length. The first
85 byte of the postamble is $FF, the next two are zero, and the last two are
86 the execution address for the binary.
87 </para>
88
89 <para>
90 Both LWASM and LWLINK can output this format.
91 </para>
92 </section>
93
94 <section>
95 <title>Object Files</title>
96 <para>LWASM supports generating a proprietary object file format which is
97 described in <xref linkend="objchap">. LWLINK is then used to link these
98 object files into a final binary in any of LWLINK's supported binary
99 formats.</para>
100
101 <para>Object files are very flexible in that they allow references that are not
102 known at assembly time to be resolved at link time. However, because the
103 addresses of such references are not known, there is no way for the assembler
104 has to use sixteen bit addressing modes for these references. The linker
105 will always use sixteen bits when resolving a reference which means any
106 instruction that requires an eight bit operand cannot use external references.
107 </para>
108
109 <para>Object files also support the concept of sections which are not valid
110 for other output types. This allows related code from each object file
111 linked to be collapsed together in the final binary.</para>
112
113 </section>
114
115 </chapter>
116
117 <chapter id="objchap">
118 <title>Object Files</title>
119 <para></para>
120 </chapter>
121 </book>
122