Mercurial > hg-old > index.cgi

annotate 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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
107
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
2 <book>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
3 <bookinfo>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
4 <title>LW Tool Chain</title>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
5 <author><firstname>William</firstname><surname>Astle</surname></author>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
6 <copyright><year>2009</year><holder>William Astle</holder></copyright>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
7 </bookinfo>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
8 <chapter>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
9
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
10 <title>Introduction</title>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
11
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
12 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
13 The LW tool chain provides utilities for building binaries for MC6809 and
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
14 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
15 which support several styles of output.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
16 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
17
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
18 <section>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
19 <title>History</title>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
20 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
21 For a long time, I have had an interest in creating an operating system for
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
22 the Coco3. I finally started working on that project around the beginning of
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
23 2006. I had a number of assemblers I could choose from. Eventually, I settled
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
24 on one and started tinkering. After a while, I realized that assembler was not
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
25 going to be sufficient due to lack of macros and issues with forward references.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
26 Then I tried another which handled forward references correctly but still did
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
27 not support macros. I looked around at other assemblers and they all lacked
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
28 one feature or another that I really wanted for creating my operating system.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
29 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
30
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
31 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
32 The solution seemed clear at that point. I am a fair programmer so I figured
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
33 I could write an assembler that would do everything I wanted an assembler to
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
34 do. Thus the LWASM probject was born. After more than two years of on and off
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
35 work, version 1.0 of LWASM was released in October of 2008.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
36 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
37
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
38 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
39 As the aforementioned operating system project progressed further, it became
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
40 clear that while assembling the whole project through a single file was doable,
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
41 it was not practical. When I found myself playing some fancy games with macros
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
42 in a bid to simulate sections, I realized I needed a means of assembling
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
43 source files separately and linking them later. This spawned a major development
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
44 effort to add an object file support to LWASM. It also spawned the LWLINK
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
45 project to provide a means to actually link the files.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
46 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
47
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
48 </section>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
49
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
50 </chapter>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
51
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
52 <chapter>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
53 <title>Output Formats</title>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
54
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
55 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
56 The LW tool chain supports multiple output formats. Each format has its
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
57 advantages and disadvantages. Each format is described below.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
58 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
59
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
60 <section>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
61 <title>Raw Binaries</title>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
62 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
63 A raw binary is simply a string of bytes. There are no headers or other
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
64 niceties. Both lwlink and lwasm support generating raw binaries. ORG directives
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
65 in the source code only serve to set the addresses that will be used for
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
66 symbols but otherwise have no direct impact on the resulting binary.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
67 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
68
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
69 </section>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
70 <section>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
71 <title>DECB Binaries</title>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
72
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
73 <para>A DECB binary is compatible with the LOADM command in Disk Extended
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
74 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
75 Color Basic. These binaries include the load address of the binary as well
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
76 as encoding an execution address. These binaries may contain multiple loadable
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
77 sections, each of which has its own load address.</para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
78
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
79 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
80 Each binary starts with a preamble. Each preamble is five bytes long. The
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
81 first byte is zero. The next two bytes specify the number of bytes to load
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
82 and the last two bytes specify the address to load the bytes at. Then, a
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
83 string of bytes follows. After this string of bytes, there may be another
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
84 preamble or a postamble. A postamble is also five bytes in length. The first
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
85 byte of the postamble is $FF, the next two are zero, and the last two are
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
86 the execution address for the binary.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
87 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
88
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
89 <para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
90 Both lwasm and lwlink can output this format.
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
91 </para>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
92 </section>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
93
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
94
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
95 </chapter>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
96 </book>
69ead2e61763 Added start of a manual and updated maintainer docs to mention generated documentation
lost
parents:
diff changeset
97