Mercurial > hg-old > index.cgi

comparison doc/main.docbook @ 107:69ead2e61763

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added start of a manual and updated maintainer docs to mention generated documentation
author lost
date Wed, 28 Jan 2009 05:02:44 +0000
parents
children
comparison
equal deleted inserted replaced
106:f643e2ff0008 107:69ead2e61763
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
95 </chapter>
96 </book>
97