# HG changeset patch # User lost # Date 1233121101 0 # Node ID f21a5593a6617b0fc44c8372125577f1e775babd # Parent bf03d06df1fdc181de687e610aecc2568f38cd4b Updated docs diff -r bf03d06df1fd -r f21a5593a661 doc/main.docbook --- a/doc/main.docbook Wed Jan 28 05:38:15 2009 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,97 +0,0 @@ - - - -LW Tool Chain -WilliamAstle -2009William Astle - - - -Introduction - - -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. - - -
-History - -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. - - - -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. - - - -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. - - -
- - - - -Output Formats - - -The LW tool chain supports multiple output formats. Each format has its -advantages and disadvantages. Each format is described below. - - -
-Raw Binaries - -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. - - -
-
-DECB Binaries - -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. - - -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. - - - -Both lwasm and lwlink can output this format. - -
- - - - - diff -r bf03d06df1fd -r f21a5593a661 doc/manual.docbook.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual.docbook.sgml Wed Jan 28 05:38:21 2009 +0000 @@ -0,0 +1,122 @@ + + + +LW Tool Chain +WilliamAstle +2009William Astle + + + +Introduction + + +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. + + +
+History + +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. + + + +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. + + + +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. + + +
+ + + + +Output Formats + + +The LW tool chain supports multiple output formats. Each format has its +advantages and disadvantages. Each format is described below. + + +
+Raw Binaries + +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. + + +
+
+DECB Binaries + +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. + + +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. + + + +Both LWASM and LWLINK can output this format. + +
+ +
+Object Files +LWASM supports generating a proprietary object file format which is +described in . LWLINK is then used to link these +object files into a final binary in any of LWLINK's supported binary +formats. + +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. + + +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. + +
+ + + + +Object Files + + + +