<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
<book>
<bookinfo>
<title>LW Tool Chain</title>
<author><firstname>William</firstname><surname>Astle</surname></author>
<copyright><year>2009</year><holder>William Astle</holder></copyright>
</bookinfo>
<chapter>

<title>Introduction</title>

<para>
The LW tool chain provides utilities for building binaries for MC6809 and
HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
which support several styles of output.
</para>

<section>
<title>History</title>
<para>
For a long time, I have had an interest in creating an operating system for
the Coco3. I finally started working on that project around the beginning of
2006. I had a number of assemblers I could choose from. Eventually, I settled
on one and started tinkering. After a while, I realized that assembler was not
going to be sufficient due to lack of macros and issues with forward references.
Then I tried another which handled forward references correctly but still did
not support macros. I looked around at other assemblers and they all lacked
one feature or another that I really wanted for creating my operating system.
</para>

<para>
The solution seemed clear at that point. I am a fair programmer so I figured
I could write an assembler that would do everything I wanted an assembler to
do. Thus the LWASM probject was born. After more than two years of on and off
work, version 1.0 of LWASM was released in October of 2008.
</para>

<para>
As the aforementioned operating system project progressed further, it became
clear that while assembling the whole project through a single file was doable,
it was not practical. When I found myself playing some fancy games with macros
in a bid to simulate sections, I realized I needed a means of assembling
source files separately and linking them later. This spawned a major development
effort to add an object file support to LWASM. It also spawned the LWLINK
project to provide a means to actually link the files.
</para>

</section>

</chapter>

<chapter>
<title>Output Formats</title>

<para>
The LW tool chain supports multiple output formats. Each format has its
advantages and disadvantages. Each format is described below.
</para>

<section>
<title>Raw Binaries</title>
<para>
A raw binary is simply a string of bytes. There are no headers or other
niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
in the source code only serve to set the addresses that will be used for
symbols but otherwise have no direct impact on the resulting binary.
</para>

</section>
<section>
<title>DECB Binaries</title>

<para>A DECB binary is compatible with the LOADM command in Disk Extended
Color Basic on the CoCo. They are also compatible with CLOADM from Extended
Color Basic. These binaries include the load address of the binary as well
as encoding an execution address. These binaries may contain multiple loadable
sections, each of which has its own load address.</para>

<para>
Each binary starts with a preamble. Each preamble is five bytes long. The
first byte is zero. The next two bytes specify the number of bytes to load
and the last two bytes specify the address to load the bytes at. Then, a
string of bytes follows. After this string of bytes, there may be another
preamble or a postamble. A postamble is also five bytes in length. The first
byte of the postamble is $FF, the next two are zero, and the last two are
the execution address for the binary.
</para>

<para>
Both LWASM and LWLINK can output this format.
</para>
</section>

<section>
<title>Object Files</title>
<para>LWASM supports generating a proprietary object file format which is
described in <xref linkend="objchap">. LWLINK is then used to link these
object files into a final binary in any of LWLINK's supported binary
formats.</para>

<para>Object files are very flexible in that they allow references that are not
known at assembly time to be resolved at link time. However, because the
addresses of such references are not known, there is no way for the assembler
has to use sixteen bit addressing modes for these references. The linker
will always use sixteen bits when resolving a reference which means any
instruction that requires an eight bit operand cannot use external references.
</para>

<para>Object files also support the concept of sections which are not valid
for other output types. This allows related code from each object file
linked to be collapsed together in the final binary.</para> 

</section>

</chapter>

<chapter id="objchap">
<title>Object Files</title>
<para></para>
</chapter>
</book>