Mercurial > hg-old > index.cgi

annotate doc/main.docbook @ 108:bf03d06df1fd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added docs on building the manual
author lost
date Wed, 28 Jan 2009 05:38:15 +0000
parents 69ead2e61763
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