Mercurial > hg-old > index.cgi
changeset 178:fd24bb443925 2.2
Added html docs
| author | lost |
|---|---|
| date | Wed, 04 Mar 2009 03:48:39 +0000 |
| parents | d340e9c8191f |
| children | |
| files | doc/manual/c10.html doc/manual/c18.html doc/manual/c35.html doc/manual/c491.html doc/manual/c613.html doc/manual/c675.html doc/manual/index.html doc/manual/manual.html doc/manual/x121.html doc/manual/x126.html doc/manual/x135.html doc/manual/x139.html doc/manual/x146.html doc/manual/x24.html doc/manual/x29.html doc/manual/x378.html doc/manual/x400.html doc/manual/x458.html doc/manual/x565.html doc/manual/x579.html |
| diffstat | 20 files changed, 7072 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/c10.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,171 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Introduction</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="PREVIOUS" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="NEXT" +TITLE="Output Formats" +HREF="c18.html"></HEAD +><BODY +CLASS="CHAPTER" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="index.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="c18.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="AEN10" +></A +>Chapter 1. Introduction</H1 +><P +>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.</P +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN13" +>1.1. History</A +></H1 +><P +>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.</P +><P +>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.</P +><P +>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.</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="c18.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>LW Tool Chain</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Output Formats</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/c18.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,153 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Output Formats</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="PREVIOUS" +TITLE="Introduction" +HREF="c10.html"><LINK +REL="NEXT" +TITLE="DECB Binaries" +HREF="x24.html"></HEAD +><BODY +CLASS="CHAPTER" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="c10.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x24.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="AEN18" +></A +>Chapter 2. Output Formats</H1 +><P +>The LW tool chain supports multiple output formats. Each format has its +advantages and disadvantages. Each format is described below.</P +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN21" +>2.1. Raw Binaries</A +></H1 +><P +>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.</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="c10.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x24.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Introduction</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>DECB Binaries</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/c35.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,311 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>LWASM</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="PREVIOUS" +TITLE="Object Files" +HREF="x29.html"><LINK +REL="NEXT" +TITLE="Dialects" +HREF="x121.html"></HEAD +><BODY +CLASS="CHAPTER" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x29.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x121.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="AEN35" +></A +>Chapter 3. LWASM</H1 +><P +>The LWTOOLS assembler is called LWASM. This chapter documents the various +features of the assembler. It is not, however, a tutorial on 6x09 assembly +language programming.</P +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN38" +>3.1. Command Line Options</A +></H1 +><P +>The binary for LWASM is called "lwasm". Note that the binary is in lower +case. lwasm takes the following command line arguments.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="OPTION" +>--decb</CODE +>, <CODE +CLASS="OPTION" +>-b</CODE +></DT +><DD +><P +>Select the DECB output format target. Equivalent to <CODE +CLASS="OPTION" +>--format=decb</CODE +>.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--format=type</CODE +>, <CODE +CLASS="OPTION" +>-f type</CODE +></DT +><DD +><P +>Select the output format. Valid values are <CODE +CLASS="OPTION" +>obj</CODE +> for the object +file target, <CODE +CLASS="OPTION" +>decb</CODE +> for the DECB LOADM format, and <CODE +CLASS="OPTION" +>raw</CODE +> +for a raw binary.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--list[=file]</CODE +>, <CODE +CLASS="OPTION" +>-l[file]</CODE +></DT +><DD +><P +>Cause LWASM to generate a listing. If <CODE +CLASS="OPTION" +>file</CODE +> is specified, +the listing will go to that file. Otherwise it will go to the standard output +stream. By default, no listing is generated.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--obj</CODE +></DT +><DD +><P +>Select the proprietary object file format as the output target.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--output=FILE</CODE +>, <CODE +CLASS="OPTION" +>-o FILE</CODE +></DT +><DD +><P +>This option specifies the name of the output file. If not specified, the +default is <CODE +CLASS="OPTION" +>a.out</CODE +>.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--pragma=pragma</CODE +>, <CODE +CLASS="OPTION" +>-p pragma</CODE +></DT +><DD +><P +>Specify assembler pragmas. Multiple pragmas are separated by commas. The +pragmas accepted are the same as for the PRAGMA assembler directive described +below.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--raw</CODE +>, <CODE +CLASS="OPTION" +>-r</CODE +></DT +><DD +><P +>Select raw binary as the output target.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--help</CODE +>, <CODE +CLASS="OPTION" +>-?</CODE +></DT +><DD +><P +>Present a help screen describing the command line options.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--usage</CODE +></DT +><DD +><P +>Provide a summary of the command line options.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--version</CODE +>, <CODE +CLASS="OPTION" +>-V</CODE +></DT +><DD +><P +>Display the software version.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--debug</CODE +>, <CODE +CLASS="OPTION" +>-d</CODE +></DT +><DD +><P +>Increase the debugging level. Only really useful to people hacking on the +LWASM source code itself.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x29.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x121.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Object Files</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Dialects</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/c491.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,290 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>LWLINK</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="PREVIOUS" +TITLE="Assembler Modes and Pragmas" +HREF="x458.html"><LINK +REL="NEXT" +TITLE="Linker Operation" +HREF="x565.html"></HEAD +><BODY +CLASS="CHAPTER" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x458.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x565.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="AEN491" +></A +>Chapter 4. LWLINK</H1 +><P +>The LWTOOLS linker is called LWLINK. This chapter documents the various features +of the linker.</P +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN494" +>4.1. Command Line Options</A +></H1 +><P +>The binary for LWLINK is called "lwlink". Note that the binary is in lower +case. lwlink takes the following command line arguments.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="OPTION" +>--decb</CODE +>, <CODE +CLASS="OPTION" +>-b</CODE +></DT +><DD +><P +>Selects the DECB output format target. This is equivalent to <CODE +CLASS="OPTION" +>--format=decb</CODE +></P +></DD +><DT +><CODE +CLASS="OPTION" +>--output=FILE</CODE +>, <CODE +CLASS="OPTION" +>-o FILE</CODE +></DT +><DD +><P +>This option specifies the name of the output file. If not specified, the +default is <CODE +CLASS="OPTION" +>a.out</CODE +>.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--format=TYPE</CODE +>, <CODE +CLASS="OPTION" +>-f TYPE</CODE +></DT +><DD +><P +>This option specifies the output format. Valid values are <CODE +CLASS="OPTION" +>decb</CODE +> +and <CODE +CLASS="OPTION" +>raw</CODE +></P +></DD +><DT +><CODE +CLASS="OPTION" +>--raw</CODE +>, <CODE +CLASS="OPTION" +>-r</CODE +></DT +><DD +><P +>This option specifies the raw output format. +It is equivalent to <CODE +CLASS="OPTION" +>--format=raw</CODE +>. +and <CODE +CLASS="OPTION" +>raw</CODE +></P +></DD +><DT +><CODE +CLASS="OPTION" +>--script=FILE</CODE +>, <CODE +CLASS="OPTION" +>-s</CODE +></DT +><DD +><P +>This option allows specifying a linking script to override the linker's +built in defaults.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--debug</CODE +>, <CODE +CLASS="OPTION" +>-d</CODE +></DT +><DD +><P +>This option increases the debugging level. It is only useful for LWTOOLS +developers.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--help</CODE +>, <CODE +CLASS="OPTION" +>-?</CODE +></DT +><DD +><P +>This provides a listing of command line options and a brief description +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--usage</CODE +></DT +><DD +><P +>This will display a usage summary. +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--version</CODE +>, <CODE +CLASS="OPTION" +>-V</CODE +></DT +><DD +><P +>This will display the version of LWLINK. +of each.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x458.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x565.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Assembler Modes and Pragmas</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Linker Operation</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/c613.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,270 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Libraries and LWAR</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="PREVIOUS" +TITLE="Linking Scripts" +HREF="x579.html"><LINK +REL="NEXT" +TITLE="Object Files" +HREF="c675.html"></HEAD +><BODY +CLASS="CHAPTER" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x579.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="c675.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="AEN613" +></A +>Chapter 5. Libraries and LWAR</H1 +><P +>LWTOOLS also includes a tool for managing libraries. These are analogous to +the static libraries created with the "ar" tool on POSIX systems. Each library +file contains one or more object files. The linker will treat the object +files within a library as though they had been specified individually on +the command line except when resolving external references. External references +are looked up first within the object files within the library and then, if +not found, the usual lookup based on the order the files are specified on +the command line occurs.</P +><P +>The tool for creating these libary files is called LWAR.</P +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN617" +>5.1. Command Line Options</A +></H1 +><P +>The binary for LWAR is called "lwar". Note that the binary is in lower +case. The options lwar understands are listed below. For archive manipulation +options, the first non-option argument is the name of the archive. All other +non-option arguments are the names of files to operate on.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="OPTION" +>--add</CODE +>, <CODE +CLASS="OPTION" +>-a</CODE +></DT +><DD +><P +>This option specifies that an archive is going to have files added to it. +If the archive does not already exist, it is created. New files are added +to the end of the archive.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--create</CODE +>, <CODE +CLASS="OPTION" +>-c</CODE +></DT +><DD +><P +>This option specifies that an archive is going to be created and have files +added to it. If the archive already exists, it is truncated.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--merge</CODE +>, <CODE +CLASS="OPTION" +>-m</CODE +></DT +><DD +><P +>If specified, any files specified to be added to an archive will be checked +to see if they are archives themselves. If so, their constituent members are +added to the archive. This is useful for avoiding archives containing archives.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--list</CODE +>, <CODE +CLASS="OPTION" +>-l</CODE +></DT +><DD +><P +>This will display a list of the files contained in the archive.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--debug</CODE +>, <CODE +CLASS="OPTION" +>-d</CODE +></DT +><DD +><P +>This option increases the debugging level. It is only useful for LWTOOLS +developers.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--help</CODE +>, <CODE +CLASS="OPTION" +>-?</CODE +></DT +><DD +><P +>This provides a listing of command line options and a brief description +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--usage</CODE +></DT +><DD +><P +>This will display a usage summary. +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--version</CODE +>, <CODE +CLASS="OPTION" +>-V</CODE +></DT +><DD +><P +>This will display the version of LWLINK. +of each.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x579.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="c675.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Linking Scripts</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Object Files</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/c675.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,370 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Object Files</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="PREVIOUS" +TITLE="Libraries and LWAR" +HREF="c613.html"></HEAD +><BODY +CLASS="CHAPTER" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="c613.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +> </TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="OBJCHAP" +></A +>Chapter 6. Object Files</H1 +><P +>LWTOOLS uses a proprietary object file format. It is proprietary in the sense +that it is specific to LWTOOLS, not that it is a hidden format. It would be +hard to keep it hidden in an open source tool chain anyway. This chapter +documents the object file format.</P +><P +>An object file consists of a series of sections each of which contains a +list of exported symbols, a list of incomplete references, and a list of +"local" symbols which may be used in calculating incomplete references. Each +section will obviously also contain the object code.</P +><P +>Exported symbols must be completely resolved to an address within the +section it is exported from. That is, an exported symbol must be a constant +rather than defined in terms of other symbols.</P +><P +>Each object file starts with a magic number and version number. The magic +number is the string "LWOBJ16" for this 16 bit object file format. The only +defined version number is currently 0. Thus, the first 8 bytes of the object +file are <FONT +COLOR="RED" +>4C574F424A313600</FONT +></P +><P +>Each section has the following items in order:</P +><P +></P +><UL +><LI +><P +>section name</P +></LI +><LI +><P +>flags</P +></LI +><LI +><P +>list of local symbols (and addresses within the section)</P +></LI +><LI +><P +>list of exported symbols (and addresses within the section)</P +></LI +><LI +><P +>list of incomplete references along with the expressions to calculate them</P +></LI +><LI +><P +>the actual object code (for non-BSS sections)</P +></LI +></UL +><P +>The section starts with the name of the section with a NUL termination +followed by a series of flag bytes terminated by NUL. There are only two +flag bytes defined. A NUL (0) indicates no more flags and a value of 1 +indicates the section is a BSS section. For a BSS section, no actual +code is included in the object file.</P +><P +>Either a NULL section name or end of file indicate the presence of no more +sections.</P +><P +>Each entry in the exported and local symbols table consists of the symbol +(NUL terminated) followed by two bytes which contain the value in big endian +order. The end of a symbol table is indicated by a NULL symbol name.</P +><P +>Each entry in the incomplete references table consists of an expression +followed by a 16 bit offset where the reference goes. Expressions are +defined as a series of terms up to an "end of expression" term. Each term +consists of a single byte which identifies the type of term (see below) +followed by any data required by the term. Then end of the list is flagged +by a NULL expression (only an end of expression term).</P +><DIV +CLASS="TABLE" +><A +NAME="AEN700" +></A +><P +><B +>Table 6-1. Object File Term Types</B +></P +><TABLE +BORDER="1" +FRAME="border" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>TERMTYPE</TH +><TH +>Meaning</TH +></TR +></THEAD +><TBODY +><TR +><TD +>00</TD +><TD +>end of expression</TD +></TR +><TR +><TD +>01</TD +><TD +>integer (16 bit in big endian order follows)</TD +></TR +><TR +><TD +>02</TD +><TD +> external symbol reference (NUL terminated symbol name follows)</TD +></TR +><TR +><TD +>03</TD +><TD +>local symbol reference (NUL terminated symbol name follows)</TD +></TR +><TR +><TD +>04</TD +><TD +>operator (1 byte operator number)</TD +></TR +><TR +><TD +>05</TD +><TD +>section base address reference</TD +></TR +></TBODY +></TABLE +></DIV +><P +>External references are resolved using other object files while local +references are resolved using the local symbol table(s) from this file. This +allows local symbols that are not exported to have the same names as +exported symbols or external references.</P +><DIV +CLASS="TABLE" +><A +NAME="AEN727" +></A +><P +><B +>Table 6-2. Object File Operator Numbers</B +></P +><TABLE +BORDER="1" +FRAME="border" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>Number</TH +><TH +>Operator</TH +></TR +></THEAD +><TBODY +><TR +><TD +>01</TD +><TD +>addition (+)</TD +></TR +><TR +><TD +>02</TD +><TD +>subtraction (-)</TD +></TR +><TR +><TD +>03</TD +><TD +>multiplication (*)</TD +></TR +><TR +><TD +>04</TD +><TD +>division (/)</TD +></TR +><TR +><TD +>05</TD +><TD +>modulus (%)</TD +></TR +><TR +><TD +>06</TD +><TD +>integer division (\) (same as division)</TD +></TR +><TR +><TD +>07</TD +><TD +>bitwise and</TD +></TR +><TR +><TD +>08</TD +><TD +>bitwise or</TD +></TR +><TR +><TD +>09</TD +><TD +>bitwise xor</TD +></TR +><TR +><TD +>0A</TD +><TD +>boolean and</TD +></TR +><TR +><TD +>0B</TD +><TD +>boolean or</TD +></TR +><TR +><TD +>0C</TD +><TD +>unary negation, 2's complement (-)</TD +></TR +><TR +><TD +>0D</TD +><TD +>unary 1's complement (^)</TD +></TR +></TBODY +></TABLE +></DIV +><P +>An expression is represented in a postfix manner with both operands for +binary operators preceding the operator and the single operand for unary +operators preceding the operator.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="c613.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +> </TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Libraries and LWAR</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +> </TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/index.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,283 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>LW Tool Chain</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="NEXT" +TITLE="Introduction" +HREF="c10.html"></HEAD +><BODY +CLASS="BOOK" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="BOOK" +><A +NAME="AEN1" +></A +><DIV +CLASS="TITLEPAGE" +><H1 +CLASS="TITLE" +><A +NAME="AEN2" +>LW Tool Chain</A +></H1 +><H3 +CLASS="AUTHOR" +><A +NAME="AEN4" +></A +>William Astle</H3 +><P +CLASS="COPYRIGHT" +>Copyright © 2009 William Astle</P +><HR></DIV +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +>1. <A +HREF="c10.html" +>Introduction</A +></DT +><DD +><DL +><DT +>1.1. <A +HREF="c10.html#AEN13" +>History</A +></DT +></DL +></DD +><DT +>2. <A +HREF="c18.html" +>Output Formats</A +></DT +><DD +><DL +><DT +>2.1. <A +HREF="c18.html#AEN21" +>Raw Binaries</A +></DT +><DT +>2.2. <A +HREF="x24.html" +>DECB Binaries</A +></DT +><DT +>2.3. <A +HREF="x29.html" +>Object Files</A +></DT +></DL +></DD +><DT +>3. <A +HREF="c35.html" +>LWASM</A +></DT +><DD +><DL +><DT +>3.1. <A +HREF="c35.html#AEN38" +>Command Line Options</A +></DT +><DT +>3.2. <A +HREF="x121.html" +>Dialects</A +></DT +><DT +>3.3. <A +HREF="x126.html" +>Source Format</A +></DT +><DT +>3.4. <A +HREF="x135.html" +>Symbols</A +></DT +><DT +>3.5. <A +HREF="x139.html" +>Numbers and Expressions</A +></DT +><DT +>3.6. <A +HREF="x146.html" +>Assembler Directives</A +></DT +><DD +><DL +><DT +>3.6.1. <A +HREF="x146.html#AEN149" +>Data Directives</A +></DT +><DT +>3.6.2. <A +HREF="x146.html#AEN243" +>Address Definition</A +></DT +><DT +>3.6.3. <A +HREF="x146.html#AEN285" +>Conditional Assembly</A +></DT +><DT +>3.6.4. <A +HREF="x146.html#AEN349" +>Miscelaneous Directives</A +></DT +></DL +></DD +><DT +>3.7. <A +HREF="x378.html" +>Macros</A +></DT +><DT +>3.8. <A +HREF="x400.html" +>Object Files and Sections</A +></DT +><DT +>3.9. <A +HREF="x458.html" +>Assembler Modes and Pragmas</A +></DT +></DL +></DD +><DT +>4. <A +HREF="c491.html" +>LWLINK</A +></DT +><DD +><DL +><DT +>4.1. <A +HREF="c491.html#AEN494" +>Command Line Options</A +></DT +><DT +>4.2. <A +HREF="x565.html" +>Linker Operation</A +></DT +><DT +>4.3. <A +HREF="x579.html" +>Linking Scripts</A +></DT +></DL +></DD +><DT +>5. <A +HREF="c613.html" +>Libraries and LWAR</A +></DT +><DD +><DL +><DT +>5.1. <A +HREF="c613.html#AEN617" +>Command Line Options</A +></DT +></DL +></DD +><DT +>6. <A +HREF="c675.html" +>Object Files</A +></DT +></DL +></DIV +><DIV +CLASS="LOT" +><DL +CLASS="LOT" +><DT +><B +>List of Tables</B +></DT +><DT +>6-1. <A +HREF="c675.html#AEN700" +>Object File Term Types</A +></DT +><DT +>6-2. <A +HREF="c675.html#AEN727" +>Object File Operator Numbers</A +></DT +></DL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +> </TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="c10.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +> </TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Introduction</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/manual.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,2321 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>LW Tool Chain</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD +><BODY +CLASS="BOOK" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="BOOK" +><A +NAME="AEN1" +></A +><DIV +CLASS="TITLEPAGE" +><H1 +CLASS="TITLE" +><A +NAME="AEN2" +>LW Tool Chain</A +></H1 +><H3 +CLASS="AUTHOR" +><A +NAME="AEN4" +></A +>William Astle</H3 +><P +CLASS="COPYRIGHT" +>Copyright © 2009 William Astle</P +><HR></DIV +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +>1. <A +HREF="#AEN10" +>Introduction</A +></DT +><DD +><DL +><DT +>1.1. <A +HREF="#AEN13" +>History</A +></DT +></DL +></DD +><DT +>2. <A +HREF="#AEN18" +>Output Formats</A +></DT +><DD +><DL +><DT +>2.1. <A +HREF="#AEN21" +>Raw Binaries</A +></DT +><DT +>2.2. <A +HREF="#AEN24" +>DECB Binaries</A +></DT +><DT +>2.3. <A +HREF="#AEN29" +>Object Files</A +></DT +></DL +></DD +><DT +>3. <A +HREF="#AEN35" +>LWASM</A +></DT +><DD +><DL +><DT +>3.1. <A +HREF="#AEN38" +>Command Line Options</A +></DT +><DT +>3.2. <A +HREF="#AEN121" +>Dialects</A +></DT +><DT +>3.3. <A +HREF="#AEN126" +>Source Format</A +></DT +><DT +>3.4. <A +HREF="#AEN135" +>Symbols</A +></DT +><DT +>3.5. <A +HREF="#AEN139" +>Numbers and Expressions</A +></DT +><DT +>3.6. <A +HREF="#AEN146" +>Assembler Directives</A +></DT +><DD +><DL +><DT +>3.6.1. <A +HREF="#AEN149" +>Data Directives</A +></DT +><DT +>3.6.2. <A +HREF="#AEN243" +>Address Definition</A +></DT +><DT +>3.6.3. <A +HREF="#AEN285" +>Conditional Assembly</A +></DT +><DT +>3.6.4. <A +HREF="#AEN349" +>Miscelaneous Directives</A +></DT +></DL +></DD +><DT +>3.7. <A +HREF="#AEN378" +>Macros</A +></DT +><DT +>3.8. <A +HREF="#AEN400" +>Object Files and Sections</A +></DT +><DT +>3.9. <A +HREF="#AEN458" +>Assembler Modes and Pragmas</A +></DT +></DL +></DD +><DT +>4. <A +HREF="#AEN491" +>LWLINK</A +></DT +><DD +><DL +><DT +>4.1. <A +HREF="#AEN494" +>Command Line Options</A +></DT +><DT +>4.2. <A +HREF="#AEN565" +>Linker Operation</A +></DT +><DT +>4.3. <A +HREF="#AEN579" +>Linking Scripts</A +></DT +></DL +></DD +><DT +>5. <A +HREF="#AEN613" +>Libraries and LWAR</A +></DT +><DD +><DL +><DT +>5.1. <A +HREF="#AEN617" +>Command Line Options</A +></DT +></DL +></DD +><DT +>6. <A +HREF="#OBJCHAP" +>Object Files</A +></DT +></DL +></DIV +><DIV +CLASS="LOT" +><DL +CLASS="LOT" +><DT +><B +>List of Tables</B +></DT +><DT +>6-1. <A +HREF="#AEN700" +>Object File Term Types</A +></DT +><DT +>6-2. <A +HREF="#AEN727" +>Object File Operator Numbers</A +></DT +></DL +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="AEN10" +></A +>Chapter 1. Introduction</H1 +><P +>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.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN13" +>1.1. History</A +></H2 +><P +>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.</P +><P +>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.</P +><P +>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.</P +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="AEN18" +></A +>Chapter 2. Output Formats</H1 +><P +>The LW tool chain supports multiple output formats. Each format has its +advantages and disadvantages. Each format is described below.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN21" +>2.1. Raw Binaries</A +></H2 +><P +>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.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN24" +>2.2. DECB Binaries</A +></H2 +><P +>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.</P +><P +>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.</P +><P +>Both LWASM and LWLINK can output this format.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN29" +>2.3. Object Files</A +></H2 +><P +>LWASM supports generating a proprietary object file format which is +described in <A +HREF="#OBJCHAP" +>Chapter 6</A +>. LWLINK is then used to link these +object files into a final binary in any of LWLINK's supported binary +formats.</P +><P +>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.</P +><P +>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.</P +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="AEN35" +></A +>Chapter 3. LWASM</H1 +><P +>The LWTOOLS assembler is called LWASM. This chapter documents the various +features of the assembler. It is not, however, a tutorial on 6x09 assembly +language programming.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN38" +>3.1. Command Line Options</A +></H2 +><P +>The binary for LWASM is called "lwasm". Note that the binary is in lower +case. lwasm takes the following command line arguments.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="OPTION" +>--decb</CODE +>, <CODE +CLASS="OPTION" +>-b</CODE +></DT +><DD +><P +>Select the DECB output format target. Equivalent to <CODE +CLASS="OPTION" +>--format=decb</CODE +>.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--format=type</CODE +>, <CODE +CLASS="OPTION" +>-f type</CODE +></DT +><DD +><P +>Select the output format. Valid values are <CODE +CLASS="OPTION" +>obj</CODE +> for the object +file target, <CODE +CLASS="OPTION" +>decb</CODE +> for the DECB LOADM format, and <CODE +CLASS="OPTION" +>raw</CODE +> +for a raw binary.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--list[=file]</CODE +>, <CODE +CLASS="OPTION" +>-l[file]</CODE +></DT +><DD +><P +>Cause LWASM to generate a listing. If <CODE +CLASS="OPTION" +>file</CODE +> is specified, +the listing will go to that file. Otherwise it will go to the standard output +stream. By default, no listing is generated.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--obj</CODE +></DT +><DD +><P +>Select the proprietary object file format as the output target.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--output=FILE</CODE +>, <CODE +CLASS="OPTION" +>-o FILE</CODE +></DT +><DD +><P +>This option specifies the name of the output file. If not specified, the +default is <CODE +CLASS="OPTION" +>a.out</CODE +>.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--pragma=pragma</CODE +>, <CODE +CLASS="OPTION" +>-p pragma</CODE +></DT +><DD +><P +>Specify assembler pragmas. Multiple pragmas are separated by commas. The +pragmas accepted are the same as for the PRAGMA assembler directive described +below.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--raw</CODE +>, <CODE +CLASS="OPTION" +>-r</CODE +></DT +><DD +><P +>Select raw binary as the output target.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--help</CODE +>, <CODE +CLASS="OPTION" +>-?</CODE +></DT +><DD +><P +>Present a help screen describing the command line options.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--usage</CODE +></DT +><DD +><P +>Provide a summary of the command line options.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--version</CODE +>, <CODE +CLASS="OPTION" +>-V</CODE +></DT +><DD +><P +>Display the software version.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--debug</CODE +>, <CODE +CLASS="OPTION" +>-d</CODE +></DT +><DD +><P +>Increase the debugging level. Only really useful to people hacking on the +LWASM source code itself.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN121" +>3.2. Dialects</A +></H2 +><P +>LWASM supports all documented MC6809 instructions as defined by Motorola. +It also supports all known HD6309 instructions. There is some variation, +however, in the pneumonics used for the block transfer instructions. LWASM +uses TFM for all four of them as do several other assemblers. Others, such +as CCASM, use four separate opcodes for it (compare: copy+, copy-, implode, +and explode). There are advantages to both methods. However, it seems like +TFM has the most traction and thus, this is what LWASM supports. Support +for such variations may be added in the future.</P +><P +>The standard addressing mode specifiers are supported. These are the +hash sign ("#") for immediate mode, the less than sign ("<") for forced +eight bit modes, and the greater than sign (">") for forced sixteen bit modes.</P +><P +>Additionally, LWASM supports using the asterisk ("*") to indicate +base page addressing. This should not be used in hand-written source code, +however, because it is non-standard and may or may not be present in future +versions of LWASM.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN126" +>3.3. Source Format</A +></H2 +><P +>LWASM accepts plain text files in a relatively free form. It can handle +lines terminated with CR, LF, CRLF, or LFCR which means it should be able +to assemble files on any platform on which it compiles.</P +><P +>Each line may start with a symbol. If a symbol is present, there must not +be any whitespace preceding it. It is legal for a line to contain nothing +but a symbol.</P +><P +>The op code is separated from the symbol by whitespace. If there is +no symbol, there must be at least one white space character preceding it. +If applicable, the operand follows separated by whitespace. Following the +opcode and operand is an optional comment.</P +><P +>A comment can also be introduced with a * or a ;. The comment character is +optional for end of statement comments. However, if a symbol is the only +thing present on the line other than the comment, the comment character is +mandatory to prevent the assembler from interpreting the comment as an opcode.</P +><P +>For compatibility with the output generated by some C preprocessors, LWASM +will also ignore lines that begin with a #. This should not be used as a general +comment character, however.</P +><P +>The opcode is not treated case sensitively. Neither are register names in +the operand fields. Symbols, however, are case sensitive.</P +><P +>LWASM does not support line numbers in the file.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN135" +>3.4. Symbols</A +></H2 +><P +>Symbols have no length restriction. They may contain letters, numbers, dots, +dollar signs, and underscores. They must start with a letter, dot, or +underscore.</P +><P +>LWASM also supports the concept of a local symbol. A local symbol is one +which contains either a "?" or a "@", which can appear anywhere in the symbol. +The scope of a local symbol is determined by a number of factors. First, +each included file gets its own local symbol scope. A blank line will also +be considered a local scope barrier. Macros each have their own local symbol +scope as well (which has a side effect that you cannot use a local symbol +as an argument to a macro). There are other factors as well. In general, +a local symbol is restricted to the block of code it is defined within.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN139" +>3.5. Numbers and Expressions</A +></H2 +><P +> Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary +numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B". +Octal numbers may be prefixed with "@" or suffixed with "Q", "q", "O", or +"o". Hexadecimal numbers may be prefixed with "$", "0x" or "0X", or suffixed +with "H". No prefix or suffix is required for decimal numbers but they can +be prefixed with "&" if desired. Any constant which begins with a letter +must be expressed with the correct prefix base identifier or be prefixed +with a 0. Thus hexadecimal FF would have to be written either 0FFH or $FF. +Numbers are not case sensitive. </P +><P +> A symbol may appear at any point where a number is acceptable. The +special symbol "*" can be used to represent the starting address of the +current source line within expressions. </P +><P +>The ASCII value of a character can be included by prefixing it with a +single quote ('). The ASCII values of two characters can be included by +prefixing the characters with a quote (").</P +><P +>LWASM supports the following basic binary operators: +, -, *, /, and %. +These represent addition, subtraction, multiplication, division, and modulus. +It also supports unary negation and unary 1's complement (- and ^ respectively). +For completeness, a unary positive (+) is supported though it is a no-op.</P +><P +>Operator precedence follows the usual rules. multiplication, division, +and modulus take precedence over addition and subtraction. Unary operators +take precedence over binary operators. To force a specific order of evaluation, +parentheses can be used in the usual manner.</P +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN146" +>3.6. Assembler Directives</A +></H2 +><P +>Various directives can be used to control the behaviour of the +assembler or to include non-code/data in the resulting output. Those directives +that are not described in detail in other sections of this document are +described below.</P +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN149" +>3.6.1. Data Directives</A +></H3 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>FCB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .DB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .BYTE <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +></DT +><DD +><P +>Include one or more constant bytes (separated by commas) in the output.</P +></DD +><DT +>FDB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .DW <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .WORD <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +></DT +><DD +><P +>Include one or more words (separated by commas) in the output.</P +></DD +><DT +>FQB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .QUAD <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .4BYTE <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +></DT +><DD +><P +>Include one or more double words (separated by commas) in the output.</P +></DD +><DT +>FCC <CODE +CLASS="PARAMETER" +>string</CODE +>, .ASCII <CODE +CLASS="PARAMETER" +>string</CODE +>, .STR <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Include a string of text in the output. The first character of the operand +is the delimiter which must appear as the last character and cannot appear +within the string. The string is included with no modifications></P +></DD +><DT +>FCN <CODE +CLASS="PARAMETER" +>string</CODE +>, .ASCIZ <CODE +CLASS="PARAMETER" +>string</CODE +>, .STRZ <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Include a NUL terminated string of text in the output. The first character of +the operand is the delimiter which must appear as the last character and +cannot appear within the string. A NUL byte is automatically appended to +the string.</P +></DD +><DT +>FCS <CODE +CLASS="PARAMETER" +>string</CODE +>, .ASCIS <CODE +CLASS="PARAMETER" +>string</CODE +>, .STRS <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Include a string of text in the output with bit 7 of the final byte set. The +first character of the operand is the delimiter which must appear as the last +character and cannot appear within the string.</P +></DD +><DT +>ZMB <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Include a number of NUL bytes in the output. The number must be fully resolvable +during pass 1 of assembly so no forward or external references are permitted.</P +></DD +><DT +>ZMD <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Include a number of zero words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted.</P +></DD +><DT +>ZMQ <CODE +CLASS="PARAMETER" +>expr<CODE +CLASS="PARAMETER" +></CODE +></CODE +></DT +><DD +><P +>Include a number of zero double-words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted.</P +></DD +><DT +>RMB <CODE +CLASS="PARAMETER" +>expr</CODE +>, .BLKB <CODE +CLASS="PARAMETER" +>expr</CODE +>, .DS <CODE +CLASS="PARAMETER" +>expr</CODE +>, .RS <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Reserve a number of bytes in the output. The number must be fully resolvable +during pass 1 of assembly so no forward or external references are permitted. +The value of the bytes is undefined.</P +></DD +><DT +>RMD <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Reserve a number of words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted. The value of the words is undefined.</P +></DD +><DT +>RMQ <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Reserve a number of double-words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted. The value of the double-words is undefined.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN243" +>3.6.2. Address Definition</A +></H3 +><P +>The directives in this section all control the addresses of symbols +or the assembly process itself.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>ORG <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Set the assembly address. The address must be fully resolvable on the +first pass so no external or forward references are permitted. ORG is not +permitted within sections when outputting to object files. For the DECB +target, each ORG directive after which output is generated will cause +a new preamble to be output. ORG is only used to determine the addresses +of symbols when the raw target is used.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> EQU <CODE +CLASS="PARAMETER" +>expr</CODE +>, <CODE +CLASS="PARAMETER" +>sym</CODE +> = <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Define the value of <CODE +CLASS="PARAMETER" +>sym</CODE +> to be <CODE +CLASS="PARAMETER" +>expr</CODE +>.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> SET <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Define the value of <CODE +CLASS="PARAMETER" +>sym</CODE +> to be <CODE +CLASS="PARAMETER" +>expr</CODE +>. +Unlike EQU, SET permits symbols to be defined multiple times as long as SET +is used for all instances. Use of the symbol before the first SET statement +that sets its value is undefined.</P +></DD +><DT +>SETDP <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Inform the assembler that it can assume the DP register contains +<CODE +CLASS="PARAMETER" +>expr</CODE +>. This directive is only advice to the assembler +to determine whether an address is in the direct page and has no effect +on the contents of the DP register. The value must be fully resolved during +the first assembly pass because it affects the sizes of subsequent instructions.</P +><P +>This directive has no effect in the object file target.</P +></DD +><DT +>ALIGN <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Force the current assembly address to be a multiple of <CODE +CLASS="PARAMETER" +>expr</CODE +>. +A series of NUL bytes is output to force the alignment, if required. The +alignment value must be fully resolved on the first pass because it affects +the addresses of subsquent instructions.</P +><P +>This directive is not suitable for inclusion in the middle of actual +code. It is intended to appear where the bytes output will not be executed.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN285" +>3.6.3. Conditional Assembly</A +></H3 +><P +>Portions of the source code can be excluded or included based on conditions +known at assembly time. Conditionals can be nested arbitrarily deeply. The +directives associated with conditional assembly are described in this section.</P +><P +>All conditionals must be fully bracketed. That is, every conditional +statement must eventually be followed by an ENDC at the same level of nesting.</P +><P +>Conditional expressions are only evaluated on the first assembly pass. +It is not possible to game the assembly process by having a conditional +change its value between assembly passes. Thus there is not and never will +be any equivalent of IFP1 or IFP2 as provided by other assemblers.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>IFEQ <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to zero, the conditional +will be considered true.</P +></DD +><DT +>IFNE <CODE +CLASS="PARAMETER" +>expr</CODE +>, IF <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a non-zero value, the conditional +will be considered true.</P +></DD +><DT +>IFGT <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value greater than zero, the conditional +will be considered true.</P +></DD +><DT +>IFGE <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value greater than or equal to zero, the conditional +will be considered true.</P +></DD +><DT +>IFLT <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value less than zero, the conditional +will be considered true.</P +></DD +><DT +>IFLE <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value less than or equal to zero , the conditional +will be considered true.</P +></DD +><DT +>IFDEF <CODE +CLASS="PARAMETER" +>sym</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>sym</CODE +> is defined at this point in the assembly +process, the conditional +will be considered true.</P +></DD +><DT +>IFNDEF <CODE +CLASS="PARAMETER" +>sym</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>sym</CODE +> is not defined at this point in the assembly +process, the conditional +will be considered true.</P +></DD +><DT +>ELSE</DT +><DD +><P +>If the preceding conditional at the same level of nesting was false, the +statements following will be assembled. If the preceding conditional at +the same level was true, the statements following will not be assembled. +Note that the preceding conditional might have been another ELSE statement +although this behaviour is not guaranteed to be supported in future versions +of LWASM.</P +></DD +><DT +>ENDC</DT +><DD +><P +>This directive marks the end of a conditional construct. Every conditional +construct must end with an ENDC directive.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H3 +CLASS="SECTION" +><A +NAME="AEN349" +>3.6.4. Miscelaneous Directives</A +></H3 +><P +>This section includes directives that do not fit into the other +categories.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>INCLUDE <CODE +CLASS="PARAMETER" +>filename</CODE +></DT +><DD +><P +>Include the contents of <CODE +CLASS="PARAMETER" +>filename</CODE +> at this point in +the assembly as though it were a part of the file currently being processed. +Note that whitespace cannot appear in the name of the file.</P +></DD +><DT +>END <CODE +CLASS="PARAMETER" +>[expr]</CODE +></DT +><DD +><P +>This directive causes the assembler to stop assembling immediately as though +it ran out of input. For the DECB target only, <CODE +CLASS="PARAMETER" +>expr</CODE +> +can be used to set the execution address of the resulting binary. For all +other targets, specifying <CODE +CLASS="PARAMETER" +>expr</CODE +> will cause an error.</P +></DD +><DT +>ERROR <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Causes a custom error message to be printed at this line. This will cause +assembly to fail. This directive is most useful inside conditional constructs +to cause assembly to fail if some condition that is known bad happens.</P +></DD +><DT +>.MODULE <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>This directive is ignored for most output targets. If the output target +supports encoding a module name into it, <CODE +CLASS="PARAMETER" +>string</CODE +> +will be used as the module name.</P +><P +>As of version 2.2, no supported output targets support this directive.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN378" +>3.7. Macros</A +></H2 +><P +>LWASM is a macro assembler. A macro is simply a name that stands in for a +series of instructions. Once a macro is defined, it is used like any other +assembler directive. Defining a macro can be considered equivalent to adding +additional assembler directives.</P +><P +>Macros my accept parameters. These parameters are referenced within +a macro by the a backslash ("\") followed by a digit 1 through 9 for the first +through ninth parameters. They may also be referenced by enclosing the +decimal parameter number in braces ("{num}"). These parameter references +are replaced with the verbatim text of the parameter passed to the macro. A +reference to a non-existent parameter will be replaced by an empty string. +Macro parameters are expanded everywhere on each source line. That means +the parameter to a macro could be used as a symbol or it could even appear +in a comment or could cause an entire source line to be commented out +when the macro is expanded.</P +><P +>Parameters passed to a macro are separated by commas and the parameter list +is terminated by any whitespace. This means that neither a comma nor whitespace +may be included in a macro parameter.</P +><P +>Macro expansion is done recursively. That is, within a macro, macros are +expanded. This can lead to infinite loops in macro expansion. If the assembler +hangs for a long time while assembling a file that uses macros, this may be +the reason.</P +><P +>Each macro expansion receives its own local symbol context which is not +inherited by any macros called by it nor is it inherited from the context +the macro was instantiated in. That means it is possible to use local symbols +within macros without having them collide with symbols in other macros or +outside the macro itself. However, this also means that using a local symbol +as a parameter to a macro, while legal, will not do what it would seem to do +as it will result in looking up the local symbol in the macro's symbol context +rather than the enclosing context where it came from, likely yielding either +an undefined symbol error or bizarre assembly results.</P +><P +>Note that there is no way to define a macro as local to a symbol context. All +macros are part of the global macro namespace. However, macros have a separate +namespace from symbols so it is possible to have a symbol with the same name +as a macro.</P +><P +>Macros are defined only during the first pass. Macro expansion also +only occurs during the first pass. On the second pass, the macro +definition is simply ignored. Macros must be defined before they are used.</P +><P +>The following directives are used when defining macros.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="PARAMETER" +>macroname</CODE +> MACRO</DT +><DD +><P +>This directive is used to being the definition of a macro called +<CODE +CLASS="PARAMETER" +>macroname</CODE +>. If <CODE +CLASS="PARAMETER" +>macroname</CODE +> already +exists, it is considered an error. Attempting to define a macro within a +macro is undefined. It may work and it may not so the behaviour should not +be relied upon.</P +></DD +><DT +>ENDM</DT +><DD +><P +>This directive indicates the end of the macro currently being defined. It +causes the assembler to resume interpreting source lines as normal.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN400" +>3.8. Object Files and Sections</A +></H2 +><P +>The object file target is very useful for large project because it allows +multiple files to be assembled independently and then linked into the final +binary at a later time. It allows only the small portion of the project +that was modified to be re-assembled rather than requiring the entire set +of source code to be available to the assembler in a single assembly process. +This can be particularly important if there are a large number of macros, +symbol definitions, or other metadata that uses resources at assembly time. +By far the largest benefit, however, is keeping the source files small enough +for a mere mortal to find things in them.</P +><P +>With multi-file projects, there needs to be a means of resolving references to +symbols in other source files. These are known as external references. The +addresses of these symbols cannot be known until the linker joins all the +object files into a single binary. This means that the assembler must be +able to output the object code without knowing the value of the symbol. This +places some restrictions on the code generated by the assembler. For +example, the assembler cannot generate direct page addressing for instructions +that reference external symbols because the address of the symbol may not +be in the direct page. Similarly, relative branches and PC relative addressing +cannot be used in their eight bit forms. Everything that must be resolved +by the linker must be assembled to use the largest address size possible to +allow the linker to fill in the correct value at link time. Note that the +same problem applies to absolute address references as well, even those in +the same source file, because the address is not known until link time.</P +><P +>It is often desired in multi-file projects to have code of various types grouped +together in the final binary generated by the linker as well. The same applies +to data. In order for the linker to do that, the bits that are to be grouped +must be tagged in some manner. This is where the concept of sections comes in. +Each chunk of code or data is part of a section in the object file. Then, +when the linker reads all the object files, it coalesces all sections of the +same name into a single section and then considers it as a unit.</P +><P +>The existence of sections, however, raises a problem for symbols even +within the same source file. Thus, the assembler must treat symbols from +different sections within the same source file in the same manner as external +symbols. That is, it must leave them for the linker to resolve at link time, +with all the limitations that entails.</P +><P +>In the object file target mode, LWASM requires all source lines that +cause bytes to be output to be inside a section. Any directives that do +not cause any bytes to be output can appear outside of a section. This includes +such things as EQU or RMB. Even ORG can appear outside a section. ORG, however, +makes no sense within a section because it is the linker that determines +the starting address of the section's code, not the assembler.</P +><P +>All symbols defined globally in the assembly process are local to the +source file and cannot be exported. All symbols defined within a section are +considered local to the source file unless otherwise explicitly exported. +Symbols referenced from external source files must be declared external, +either explicitly or by asking the assembler to assume that all undefined +symbols are external.</P +><P +>It is often handy to define a number of memory addresses that will be +used for data at run-time but which need not be included in the binary file. +These memory addresses are not initialized until run-time, either by the +program itself or by the program loader, depending on the operating environment. +Such sections are often known as BSS sections. LWASM supports generating +sections with a BSS attribute set which causes the section definition including +symbols exported from that section and those symbols required to resolve +references from the local file, but with no actual code in the object file. +It is illegal for any source lines within a BSS flagged section to cause any +bytes to be output.</P +><P +>The following directives apply to section handling.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>SECTION <CODE +CLASS="PARAMETER" +>name[,flags]</CODE +>, SECT <CODE +CLASS="PARAMETER" +>name[,flags]</CODE +>, .AREA <CODE +CLASS="PARAMETER" +>name[,flags]</CODE +></DT +><DD +><P +>Instructs the assembler that the code following this directive is to be +considered part of the section <CODE +CLASS="PARAMETER" +>name</CODE +>. A section name +may appear multiple times in which case it is as though all the code from +all the instances of that section appeared adjacent within the source file. +However, <CODE +CLASS="PARAMETER" +>flags</CODE +> may only be specified on the first +instance of the section.</P +><P +>There is a single flag supported in <CODE +CLASS="PARAMETER" +>flags</CODE +>. The +flag <CODE +CLASS="PARAMETER" +>bss</CODE +> will cause the section to be treated as a BSS +section and, thus, no code will be included in the object file nor will any +bytes be permitted to be output.</P +><P +>If the section name is "bss" or ".bss" in any combination of upper and +lower case, the section is assumed to be a BSS section. In that case, +the flag <CODE +CLASS="PARAMETER" +>!bss</CODE +> can be used to override this assumption.</P +><P +>If assembly is already happening within a section, the section is implicitly +ended and the new section started. This is not considered an error although +it is recommended that all sections be explicitly closed.</P +></DD +><DT +>ENDSECTION, ENDSECT, ENDS</DT +><DD +><P +>This directive ends the current section. This puts assembly outside of any +sections until the next SECTION directive.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> EXTERN, <CODE +CLASS="PARAMETER" +>sym</CODE +> EXTERNAL, <CODE +CLASS="PARAMETER" +>sym</CODE +> IMPORT</DT +><DD +><P +>This directive defines <CODE +CLASS="PARAMETER" +>sym</CODE +> as an external symbol. +This directive may occur at any point in the source code. EXTERN definitions +are resolved on the first pass so an EXTERN definition anywhere in the +source file is valid for the entire file. The use of this directive is +optional when the assembler is instructed to assume that all undefined +symbols are external. In fact, in that mode, if the symbol is referenced +before the EXTERN directive, an error will occur.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> EXPORT, <CODE +CLASS="PARAMETER" +>sym</CODE +> .GLOBL, EXPORT <CODE +CLASS="PARAMETER" +>sym</CODE +>, .GLOBL <CODE +CLASS="PARAMETER" +>sym</CODE +></DT +><DD +><P +>This directive defines <CODE +CLASS="PARAMETER" +>sym</CODE +> as an exported symbol. +This directive may occur at any point in the source code, even before the +definition of the exported symbol.</P +><P +>Note that <CODE +CLASS="PARAMETER" +>sym</CODE +> may appear as the operand or as the +statement's symbol. If there is a symbol on the statement, that will +take precedence over any operand that is present.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN458" +>3.9. Assembler Modes and Pragmas</A +></H2 +><P +>There are a number of options that affect the way assembly is performed. +Some of these options can only be specified on the command line because +they determine something absolute about the assembly process. These include +such things as the output target. Other things may be switchable during +the assembly process. These are known as pragmas and are, by definition, +not portable between assemblers.</P +><P +>LWASM supports a number of pragmas that affect code generation or +otherwise affect the behaviour of the assembler. These may be specified by +way of a command line option or by assembler directives. The directives +are as follows.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>PRAGMA <CODE +CLASS="PARAMETER" +>pragma[,...]</CODE +></DT +><DD +><P +>Specifies that the assembler should bring into force all <CODE +CLASS="PARAMETER" +>pragma</CODE +>s +specified. Any unrecognized pragma will cause an assembly error. The new +pragmas will take effect immediately. This directive should be used when +the program will assemble incorrectly if the pragma is ignored or not supported.</P +></DD +><DT +>*PRAGMA <CODE +CLASS="PARAMETER" +>pragma[,...]</CODE +></DT +><DD +><P +>This is identical to the PRAGMA directive except no error will occur with +unrecognized or unsupported pragmas. This directive, by virtue of starting +with a comment character, will also be ignored by assemblers that do not +support this directive. Use this variation if the pragma is not required +for correct functioning of the code.</P +></DD +></DL +></DIV +><P +>Each pragma supported has a positive version and a negative version. +The positive version enables the pragma while the negative version disables +it. The negatitve version is simply the positive version with "no" prefixed +to it. For instance, "pragma" vs. "nopragma". Only the positive version is +listed below.</P +><P +>Pragmas are not case sensitive.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>index0tonone</DT +><DD +><P +>When in force, this pragma enables an optimization affecting indexed addressing +modes. When the offset expression in an indexed mode evaluates to zero but is +not explicity written as 0, this will replace the operand with the equivalent +no offset mode, thus creating slightly faster code. Because of the advantages +of this optimization, it is enabled by default.</P +></DD +><DT +>cescapes</DT +><DD +><P +>This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to +have C-style escape sequences interpreted. The one departure from the official +spec is that unrecognized escape sequences will return either the character +immediately following the backslash or some undefined value. Do not rely +on the behaviour of undefined escape sequences.</P +></DD +><DT +>undefextern</DT +><DD +><P +>This pragma is only valid for targets that support external references. When in +force, if the assembler sees an undefined symbol on the second pass, it will +automatically define it as an external symbol. This automatic definition will +apply for the remainder of the assembly process, even if the pragma is +subsequently turned off. Because this behaviour would be potentially surprising, +this pragma defaults to off.</P +><P +>The primary use for this pragma is for projects that share a large number of +symbols between source files. In such cases, it is impractical to enumerate +all the external references in every source file. This allows the assembler +and linker to do the heavy lifting while not preventing a particular source +module from defining a local symbol of the same name as an external symbol +if it does not need the external symbol. (This pragma will not cause an +automatic external definition if there is already a locally defined symbol.)</P +><P +>This pragma will often be specified on the command line for large projects. +However, depending on the specific dynamics of the project, it may be sufficient +for one or two files to use this pragma internally.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="AEN491" +></A +>Chapter 4. LWLINK</H1 +><P +>The LWTOOLS linker is called LWLINK. This chapter documents the various features +of the linker.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN494" +>4.1. Command Line Options</A +></H2 +><P +>The binary for LWLINK is called "lwlink". Note that the binary is in lower +case. lwlink takes the following command line arguments.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="OPTION" +>--decb</CODE +>, <CODE +CLASS="OPTION" +>-b</CODE +></DT +><DD +><P +>Selects the DECB output format target. This is equivalent to <CODE +CLASS="OPTION" +>--format=decb</CODE +></P +></DD +><DT +><CODE +CLASS="OPTION" +>--output=FILE</CODE +>, <CODE +CLASS="OPTION" +>-o FILE</CODE +></DT +><DD +><P +>This option specifies the name of the output file. If not specified, the +default is <CODE +CLASS="OPTION" +>a.out</CODE +>.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--format=TYPE</CODE +>, <CODE +CLASS="OPTION" +>-f TYPE</CODE +></DT +><DD +><P +>This option specifies the output format. Valid values are <CODE +CLASS="OPTION" +>decb</CODE +> +and <CODE +CLASS="OPTION" +>raw</CODE +></P +></DD +><DT +><CODE +CLASS="OPTION" +>--raw</CODE +>, <CODE +CLASS="OPTION" +>-r</CODE +></DT +><DD +><P +>This option specifies the raw output format. +It is equivalent to <CODE +CLASS="OPTION" +>--format=raw</CODE +>. +and <CODE +CLASS="OPTION" +>raw</CODE +></P +></DD +><DT +><CODE +CLASS="OPTION" +>--script=FILE</CODE +>, <CODE +CLASS="OPTION" +>-s</CODE +></DT +><DD +><P +>This option allows specifying a linking script to override the linker's +built in defaults.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--debug</CODE +>, <CODE +CLASS="OPTION" +>-d</CODE +></DT +><DD +><P +>This option increases the debugging level. It is only useful for LWTOOLS +developers.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--help</CODE +>, <CODE +CLASS="OPTION" +>-?</CODE +></DT +><DD +><P +>This provides a listing of command line options and a brief description +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--usage</CODE +></DT +><DD +><P +>This will display a usage summary. +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--version</CODE +>, <CODE +CLASS="OPTION" +>-V</CODE +></DT +><DD +><P +>This will display the version of LWLINK. +of each.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN565" +>4.2. Linker Operation</A +></H2 +><P +> LWLINK takes one or more files in supported input formats and links them +into a single binary. Currently supported formats are the LWTOOLS object +file format and the archive format used by LWAR. While the precise method is +slightly different, linking can be conceptualized as the following steps. </P +><P +></P +><OL +TYPE="1" +><LI +><P +>First, the linker loads a linking script. If no script is specified, it +loads a built-in default script based on the output format selected. This +script tells the linker how to lay out the various sections in the final +binary.</P +></LI +><LI +><P +>Next, the linker reads all the input files into memory. At this time, it +flags any format errors in those files. It constructs a table of symbols +for each object at this time.</P +></LI +><LI +><P +>The linker then proceeds with organizing the sections loaded from each file +according to the linking script. As it does so, it is able to assign addresses +to each symbol defined in each object file. At this time, the linker may +also collapse different instances of the same section name into a single +section by appending the data from each subsequent instance of the section +to the first instance of the section.</P +></LI +><LI +><P +>Next, the linker looks through every object file for every incomplete reference. +It then attempts to fully resolve that reference. If it cannot do so, it +throws an error. Once a reference is resolved, the value is placed into +the binary code at the specified section. It should be noted that an +incomplete reference can reference either a symbol internal to the object +file or an external symbol which is in the export list of another object +file.</P +></LI +><LI +><P +>If all of the above steps are successful, the linker opens the output file +and actually constructs the binary.</P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN579" +>4.3. Linking Scripts</A +></H2 +><P +>A linker script is used to instruct the linker about how to assemble the +various sections into a completed binary. It consists of a series of +directives which are considered in the order they are encountered.</P +><P +>The sections will appear in the resulting binary in the order they are +specified in the script file. If a referenced section is not found, the linker will behave as though the +section did exist but had a zero size, no relocations, and no exports. +A section should only be referenced once. Any subsequent references will have +an undefined effect.</P +><P +>All numbers are in linking scripts are specified in hexadecimal. All directives +are case sensitive although the hexadecimal numbers are not.</P +><P +>A section name can be specified as a "*", then any section not +already matched by the script will be matched. The "*" can be followed +by a comma and a flag to narrow the section down slightly, also. +If the flag is "!bss", then any section that is not flagged as a bss section +will be matched. If the flag is "bss", then any section that is flagged as +bss will be matched.</P +><P +>The following directives are understood in a linker script.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>section <CODE +CLASS="PARAMETER" +>name</CODE +> load <CODE +CLASS="PARAMETER" +>addr</CODE +></DT +><DD +><P +> This causes the section <CODE +CLASS="PARAMETER" +>name</CODE +> to load at +<CODE +CLASS="PARAMETER" +>addr</CODE +>. For the raw target, only one "load at" entry is +allowed for non-bss sections and it must be the first one. For raw targets, +it affects the addresses the linker assigns to symbols but has no other +affect on the output. bss sections may all have separate load addresses but +since they will not appear in the binary anyway, this is okay.</P +><P +>For the decb target, each "load" entry will cause a new "block" to be +output to the binary which will contain the load address. It is legal for +sections to overlap in this manner - the linker assumes the loader will sort +everything out.</P +></DD +><DT +>section <CODE +CLASS="PARAMETER" +>name</CODE +></DT +><DD +><P +> This will cause the section <CODE +CLASS="PARAMETER" +>name</CODE +> to load after the previously listed +section.</P +></DD +><DT +>exec <CODE +CLASS="PARAMETER" +>addr or sym</CODE +></DT +><DD +><P +>This will cause the execution address (entry point) to be the address +specified (in hex) or the specified symbol name. The symbol name must +match a symbol that is exported by one of the object files being linked. +This has no effect for targets that do not encode the entry point into the +resulting file. If not specified, the entry point is assumed to be address 0 +which is probably not what you want. The default link scripts for targets +that support this directive automatically starts at the beginning of the +first section (usually "init" or "code") that is emitted in the binary.</P +></DD +><DT +>pad <CODE +CLASS="PARAMETER" +>size</CODE +></DT +><DD +><P +>This will cause the output file to be padded with NUL bytes to be exactly +<CODE +CLASS="PARAMETER" +>size</CODE +> bytes in length. This only makes sense for a raw target.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="AEN613" +></A +>Chapter 5. Libraries and LWAR</H1 +><P +>LWTOOLS also includes a tool for managing libraries. These are analogous to +the static libraries created with the "ar" tool on POSIX systems. Each library +file contains one or more object files. The linker will treat the object +files within a library as though they had been specified individually on +the command line except when resolving external references. External references +are looked up first within the object files within the library and then, if +not found, the usual lookup based on the order the files are specified on +the command line occurs.</P +><P +>The tool for creating these libary files is called LWAR.</P +><DIV +CLASS="SECTION" +><HR><H2 +CLASS="SECTION" +><A +NAME="AEN617" +>5.1. Command Line Options</A +></H2 +><P +>The binary for LWAR is called "lwar". Note that the binary is in lower +case. The options lwar understands are listed below. For archive manipulation +options, the first non-option argument is the name of the archive. All other +non-option arguments are the names of files to operate on.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="OPTION" +>--add</CODE +>, <CODE +CLASS="OPTION" +>-a</CODE +></DT +><DD +><P +>This option specifies that an archive is going to have files added to it. +If the archive does not already exist, it is created. New files are added +to the end of the archive.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--create</CODE +>, <CODE +CLASS="OPTION" +>-c</CODE +></DT +><DD +><P +>This option specifies that an archive is going to be created and have files +added to it. If the archive already exists, it is truncated.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--merge</CODE +>, <CODE +CLASS="OPTION" +>-m</CODE +></DT +><DD +><P +>If specified, any files specified to be added to an archive will be checked +to see if they are archives themselves. If so, their constituent members are +added to the archive. This is useful for avoiding archives containing archives.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--list</CODE +>, <CODE +CLASS="OPTION" +>-l</CODE +></DT +><DD +><P +>This will display a list of the files contained in the archive.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--debug</CODE +>, <CODE +CLASS="OPTION" +>-d</CODE +></DT +><DD +><P +>This option increases the debugging level. It is only useful for LWTOOLS +developers.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--help</CODE +>, <CODE +CLASS="OPTION" +>-?</CODE +></DT +><DD +><P +>This provides a listing of command line options and a brief description +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--usage</CODE +></DT +><DD +><P +>This will display a usage summary. +of each.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--version</CODE +>, <CODE +CLASS="OPTION" +>-V</CODE +></DT +><DD +><P +>This will display the version of LWLINK. +of each.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="OBJCHAP" +></A +>Chapter 6. Object Files</H1 +><P +>LWTOOLS uses a proprietary object file format. It is proprietary in the sense +that it is specific to LWTOOLS, not that it is a hidden format. It would be +hard to keep it hidden in an open source tool chain anyway. This chapter +documents the object file format.</P +><P +>An object file consists of a series of sections each of which contains a +list of exported symbols, a list of incomplete references, and a list of +"local" symbols which may be used in calculating incomplete references. Each +section will obviously also contain the object code.</P +><P +>Exported symbols must be completely resolved to an address within the +section it is exported from. That is, an exported symbol must be a constant +rather than defined in terms of other symbols.</P +><P +>Each object file starts with a magic number and version number. The magic +number is the string "LWOBJ16" for this 16 bit object file format. The only +defined version number is currently 0. Thus, the first 8 bytes of the object +file are <FONT +COLOR="RED" +>4C574F424A313600</FONT +></P +><P +>Each section has the following items in order:</P +><P +></P +><UL +><LI +><P +>section name</P +></LI +><LI +><P +>flags</P +></LI +><LI +><P +>list of local symbols (and addresses within the section)</P +></LI +><LI +><P +>list of exported symbols (and addresses within the section)</P +></LI +><LI +><P +>list of incomplete references along with the expressions to calculate them</P +></LI +><LI +><P +>the actual object code (for non-BSS sections)</P +></LI +></UL +><P +>The section starts with the name of the section with a NUL termination +followed by a series of flag bytes terminated by NUL. There are only two +flag bytes defined. A NUL (0) indicates no more flags and a value of 1 +indicates the section is a BSS section. For a BSS section, no actual +code is included in the object file.</P +><P +>Either a NULL section name or end of file indicate the presence of no more +sections.</P +><P +>Each entry in the exported and local symbols table consists of the symbol +(NUL terminated) followed by two bytes which contain the value in big endian +order. The end of a symbol table is indicated by a NULL symbol name.</P +><P +>Each entry in the incomplete references table consists of an expression +followed by a 16 bit offset where the reference goes. Expressions are +defined as a series of terms up to an "end of expression" term. Each term +consists of a single byte which identifies the type of term (see below) +followed by any data required by the term. Then end of the list is flagged +by a NULL expression (only an end of expression term).</P +><DIV +CLASS="TABLE" +><A +NAME="AEN700" +></A +><P +><B +>Table 6-1. Object File Term Types</B +></P +><TABLE +BORDER="1" +FRAME="border" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>TERMTYPE</TH +><TH +>Meaning</TH +></TR +></THEAD +><TBODY +><TR +><TD +>00</TD +><TD +>end of expression</TD +></TR +><TR +><TD +>01</TD +><TD +>integer (16 bit in big endian order follows)</TD +></TR +><TR +><TD +>02</TD +><TD +> external symbol reference (NUL terminated symbol name follows)</TD +></TR +><TR +><TD +>03</TD +><TD +>local symbol reference (NUL terminated symbol name follows)</TD +></TR +><TR +><TD +>04</TD +><TD +>operator (1 byte operator number)</TD +></TR +><TR +><TD +>05</TD +><TD +>section base address reference</TD +></TR +></TBODY +></TABLE +></DIV +><P +>External references are resolved using other object files while local +references are resolved using the local symbol table(s) from this file. This +allows local symbols that are not exported to have the same names as +exported symbols or external references.</P +><DIV +CLASS="TABLE" +><A +NAME="AEN727" +></A +><P +><B +>Table 6-2. Object File Operator Numbers</B +></P +><TABLE +BORDER="1" +FRAME="border" +CLASS="CALSTABLE" +><COL><COL><THEAD +><TR +><TH +>Number</TH +><TH +>Operator</TH +></TR +></THEAD +><TBODY +><TR +><TD +>01</TD +><TD +>addition (+)</TD +></TR +><TR +><TD +>02</TD +><TD +>subtraction (-)</TD +></TR +><TR +><TD +>03</TD +><TD +>multiplication (*)</TD +></TR +><TR +><TD +>04</TD +><TD +>division (/)</TD +></TR +><TR +><TD +>05</TD +><TD +>modulus (%)</TD +></TR +><TR +><TD +>06</TD +><TD +>integer division (\) (same as division)</TD +></TR +><TR +><TD +>07</TD +><TD +>bitwise and</TD +></TR +><TR +><TD +>08</TD +><TD +>bitwise or</TD +></TR +><TR +><TD +>09</TD +><TD +>bitwise xor</TD +></TR +><TR +><TD +>0A</TD +><TD +>boolean and</TD +></TR +><TR +><TD +>0B</TD +><TD +>boolean or</TD +></TR +><TR +><TD +>0C</TD +><TD +>unary negation, 2's complement (-)</TD +></TR +><TR +><TD +>0D</TD +><TD +>unary 1's complement (^)</TD +></TR +></TBODY +></TABLE +></DIV +><P +>An expression is represented in a postfix manner with both operands for +binary operators preceding the operator and the single operand for unary +operators preceding the operator.</P +></DIV +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x121.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,162 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Dialects</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="NEXT" +TITLE="Source Format" +HREF="x126.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="c35.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x126.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN121" +>3.2. Dialects</A +></H1 +><P +>LWASM supports all documented MC6809 instructions as defined by Motorola. +It also supports all known HD6309 instructions. There is some variation, +however, in the pneumonics used for the block transfer instructions. LWASM +uses TFM for all four of them as do several other assemblers. Others, such +as CCASM, use four separate opcodes for it (compare: copy+, copy-, implode, +and explode). There are advantages to both methods. However, it seems like +TFM has the most traction and thus, this is what LWASM supports. Support +for such variations may be added in the future.</P +><P +>The standard addressing mode specifiers are supported. These are the +hash sign ("#") for immediate mode, the less than sign ("<") for forced +eight bit modes, and the greater than sign (">") for forced sixteen bit modes.</P +><P +>Additionally, LWASM supports using the asterisk ("*") to indicate +base page addressing. This should not be used in hand-written source code, +however, because it is non-standard and may or may not be present in future +versions of LWASM.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x126.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>LWASM</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Source Format</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x126.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,171 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Source Format</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="Dialects" +HREF="x121.html"><LINK +REL="NEXT" +TITLE="Symbols" +HREF="x135.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x121.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x135.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN126" +>3.3. Source Format</A +></H1 +><P +>LWASM accepts plain text files in a relatively free form. It can handle +lines terminated with CR, LF, CRLF, or LFCR which means it should be able +to assemble files on any platform on which it compiles.</P +><P +>Each line may start with a symbol. If a symbol is present, there must not +be any whitespace preceding it. It is legal for a line to contain nothing +but a symbol.</P +><P +>The op code is separated from the symbol by whitespace. If there is +no symbol, there must be at least one white space character preceding it. +If applicable, the operand follows separated by whitespace. Following the +opcode and operand is an optional comment.</P +><P +>A comment can also be introduced with a * or a ;. The comment character is +optional for end of statement comments. However, if a symbol is the only +thing present on the line other than the comment, the comment character is +mandatory to prevent the assembler from interpreting the comment as an opcode.</P +><P +>For compatibility with the output generated by some C preprocessors, LWASM +will also ignore lines that begin with a #. This should not be used as a general +comment character, however.</P +><P +>The opcode is not treated case sensitively. Neither are register names in +the operand fields. Symbols, however, are case sensitive.</P +><P +>LWASM does not support line numbers in the file.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x121.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x135.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Dialects</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Symbols</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x135.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,157 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Symbols</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="Source Format" +HREF="x126.html"><LINK +REL="NEXT" +TITLE="Numbers and Expressions" +HREF="x139.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x126.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x139.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN135" +>3.4. Symbols</A +></H1 +><P +>Symbols have no length restriction. They may contain letters, numbers, dots, +dollar signs, and underscores. They must start with a letter, dot, or +underscore.</P +><P +>LWASM also supports the concept of a local symbol. A local symbol is one +which contains either a "?" or a "@", which can appear anywhere in the symbol. +The scope of a local symbol is determined by a number of factors. First, +each included file gets its own local symbol scope. A blank line will also +be considered a local scope barrier. Macros each have their own local symbol +scope as well (which has a side effect that you cannot use a local symbol +as an argument to a macro). There are other factors as well. In general, +a local symbol is restricted to the block of code it is defined within.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x126.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x139.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Source Format</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Numbers and Expressions</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x139.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,172 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Numbers and Expressions</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="Symbols" +HREF="x135.html"><LINK +REL="NEXT" +TITLE="Assembler Directives" +HREF="x146.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x135.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x146.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN139" +>3.5. Numbers and Expressions</A +></H1 +><P +> Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary +numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B". +Octal numbers may be prefixed with "@" or suffixed with "Q", "q", "O", or +"o". Hexadecimal numbers may be prefixed with "$", "0x" or "0X", or suffixed +with "H". No prefix or suffix is required for decimal numbers but they can +be prefixed with "&" if desired. Any constant which begins with a letter +must be expressed with the correct prefix base identifier or be prefixed +with a 0. Thus hexadecimal FF would have to be written either 0FFH or $FF. +Numbers are not case sensitive. </P +><P +> A symbol may appear at any point where a number is acceptable. The +special symbol "*" can be used to represent the starting address of the +current source line within expressions. </P +><P +>The ASCII value of a character can be included by prefixing it with a +single quote ('). The ASCII values of two characters can be included by +prefixing the characters with a quote (").</P +><P +>LWASM supports the following basic binary operators: +, -, *, /, and %. +These represent addition, subtraction, multiplication, division, and modulus. +It also supports unary negation and unary 1's complement (- and ^ respectively). +For completeness, a unary positive (+) is supported though it is a no-op.</P +><P +>Operator precedence follows the usual rules. multiplication, division, +and modulus take precedence over addition and subtraction. Unary operators +take precedence over binary operators. To force a specific order of evaluation, +parentheses can be used in the usual manner.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x135.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x146.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Symbols</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Assembler Directives</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x146.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,686 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Assembler Directives</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="Numbers and Expressions" +HREF="x139.html"><LINK +REL="NEXT" +TITLE="Macros" +HREF="x378.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x139.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x378.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN146" +>3.6. Assembler Directives</A +></H1 +><P +>Various directives can be used to control the behaviour of the +assembler or to include non-code/data in the resulting output. Those directives +that are not described in detail in other sections of this document are +described below.</P +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN149" +>3.6.1. Data Directives</A +></H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>FCB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .DB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .BYTE <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +></DT +><DD +><P +>Include one or more constant bytes (separated by commas) in the output.</P +></DD +><DT +>FDB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .DW <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .WORD <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +></DT +><DD +><P +>Include one or more words (separated by commas) in the output.</P +></DD +><DT +>FQB <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .QUAD <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +>, .4BYTE <CODE +CLASS="PARAMETER" +>expr[,...]</CODE +></DT +><DD +><P +>Include one or more double words (separated by commas) in the output.</P +></DD +><DT +>FCC <CODE +CLASS="PARAMETER" +>string</CODE +>, .ASCII <CODE +CLASS="PARAMETER" +>string</CODE +>, .STR <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Include a string of text in the output. The first character of the operand +is the delimiter which must appear as the last character and cannot appear +within the string. The string is included with no modifications></P +></DD +><DT +>FCN <CODE +CLASS="PARAMETER" +>string</CODE +>, .ASCIZ <CODE +CLASS="PARAMETER" +>string</CODE +>, .STRZ <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Include a NUL terminated string of text in the output. The first character of +the operand is the delimiter which must appear as the last character and +cannot appear within the string. A NUL byte is automatically appended to +the string.</P +></DD +><DT +>FCS <CODE +CLASS="PARAMETER" +>string</CODE +>, .ASCIS <CODE +CLASS="PARAMETER" +>string</CODE +>, .STRS <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Include a string of text in the output with bit 7 of the final byte set. The +first character of the operand is the delimiter which must appear as the last +character and cannot appear within the string.</P +></DD +><DT +>ZMB <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Include a number of NUL bytes in the output. The number must be fully resolvable +during pass 1 of assembly so no forward or external references are permitted.</P +></DD +><DT +>ZMD <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Include a number of zero words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted.</P +></DD +><DT +>ZMQ <CODE +CLASS="PARAMETER" +>expr<CODE +CLASS="PARAMETER" +></CODE +></CODE +></DT +><DD +><P +>Include a number of zero double-words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted.</P +></DD +><DT +>RMB <CODE +CLASS="PARAMETER" +>expr</CODE +>, .BLKB <CODE +CLASS="PARAMETER" +>expr</CODE +>, .DS <CODE +CLASS="PARAMETER" +>expr</CODE +>, .RS <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Reserve a number of bytes in the output. The number must be fully resolvable +during pass 1 of assembly so no forward or external references are permitted. +The value of the bytes is undefined.</P +></DD +><DT +>RMD <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Reserve a number of words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted. The value of the words is undefined.</P +></DD +><DT +>RMQ <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Reserve a number of double-words in the output. The number must be fully +resolvable during pass 1 of assembly so no forward or external references are +permitted. The value of the double-words is undefined.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN243" +>3.6.2. Address Definition</A +></H2 +><P +>The directives in this section all control the addresses of symbols +or the assembly process itself.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>ORG <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Set the assembly address. The address must be fully resolvable on the +first pass so no external or forward references are permitted. ORG is not +permitted within sections when outputting to object files. For the DECB +target, each ORG directive after which output is generated will cause +a new preamble to be output. ORG is only used to determine the addresses +of symbols when the raw target is used.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> EQU <CODE +CLASS="PARAMETER" +>expr</CODE +>, <CODE +CLASS="PARAMETER" +>sym</CODE +> = <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Define the value of <CODE +CLASS="PARAMETER" +>sym</CODE +> to be <CODE +CLASS="PARAMETER" +>expr</CODE +>.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> SET <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Define the value of <CODE +CLASS="PARAMETER" +>sym</CODE +> to be <CODE +CLASS="PARAMETER" +>expr</CODE +>. +Unlike EQU, SET permits symbols to be defined multiple times as long as SET +is used for all instances. Use of the symbol before the first SET statement +that sets its value is undefined.</P +></DD +><DT +>SETDP <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Inform the assembler that it can assume the DP register contains +<CODE +CLASS="PARAMETER" +>expr</CODE +>. This directive is only advice to the assembler +to determine whether an address is in the direct page and has no effect +on the contents of the DP register. The value must be fully resolved during +the first assembly pass because it affects the sizes of subsequent instructions.</P +><P +>This directive has no effect in the object file target.</P +></DD +><DT +>ALIGN <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>Force the current assembly address to be a multiple of <CODE +CLASS="PARAMETER" +>expr</CODE +>. +A series of NUL bytes is output to force the alignment, if required. The +alignment value must be fully resolved on the first pass because it affects +the addresses of subsquent instructions.</P +><P +>This directive is not suitable for inclusion in the middle of actual +code. It is intended to appear where the bytes output will not be executed.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN285" +>3.6.3. Conditional Assembly</A +></H2 +><P +>Portions of the source code can be excluded or included based on conditions +known at assembly time. Conditionals can be nested arbitrarily deeply. The +directives associated with conditional assembly are described in this section.</P +><P +>All conditionals must be fully bracketed. That is, every conditional +statement must eventually be followed by an ENDC at the same level of nesting.</P +><P +>Conditional expressions are only evaluated on the first assembly pass. +It is not possible to game the assembly process by having a conditional +change its value between assembly passes. Thus there is not and never will +be any equivalent of IFP1 or IFP2 as provided by other assemblers.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>IFEQ <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to zero, the conditional +will be considered true.</P +></DD +><DT +>IFNE <CODE +CLASS="PARAMETER" +>expr</CODE +>, IF <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a non-zero value, the conditional +will be considered true.</P +></DD +><DT +>IFGT <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value greater than zero, the conditional +will be considered true.</P +></DD +><DT +>IFGE <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value greater than or equal to zero, the conditional +will be considered true.</P +></DD +><DT +>IFLT <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value less than zero, the conditional +will be considered true.</P +></DD +><DT +>IFLE <CODE +CLASS="PARAMETER" +>expr</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>expr</CODE +> evaluates to a value less than or equal to zero , the conditional +will be considered true.</P +></DD +><DT +>IFDEF <CODE +CLASS="PARAMETER" +>sym</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>sym</CODE +> is defined at this point in the assembly +process, the conditional +will be considered true.</P +></DD +><DT +>IFNDEF <CODE +CLASS="PARAMETER" +>sym</CODE +></DT +><DD +><P +>If <CODE +CLASS="PARAMETER" +>sym</CODE +> is not defined at this point in the assembly +process, the conditional +will be considered true.</P +></DD +><DT +>ELSE</DT +><DD +><P +>If the preceding conditional at the same level of nesting was false, the +statements following will be assembled. If the preceding conditional at +the same level was true, the statements following will not be assembled. +Note that the preceding conditional might have been another ELSE statement +although this behaviour is not guaranteed to be supported in future versions +of LWASM.</P +></DD +><DT +>ENDC</DT +><DD +><P +>This directive marks the end of a conditional construct. Every conditional +construct must end with an ENDC directive.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN349" +>3.6.4. Miscelaneous Directives</A +></H2 +><P +>This section includes directives that do not fit into the other +categories.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>INCLUDE <CODE +CLASS="PARAMETER" +>filename</CODE +></DT +><DD +><P +>Include the contents of <CODE +CLASS="PARAMETER" +>filename</CODE +> at this point in +the assembly as though it were a part of the file currently being processed. +Note that whitespace cannot appear in the name of the file.</P +></DD +><DT +>END <CODE +CLASS="PARAMETER" +>[expr]</CODE +></DT +><DD +><P +>This directive causes the assembler to stop assembling immediately as though +it ran out of input. For the DECB target only, <CODE +CLASS="PARAMETER" +>expr</CODE +> +can be used to set the execution address of the resulting binary. For all +other targets, specifying <CODE +CLASS="PARAMETER" +>expr</CODE +> will cause an error.</P +></DD +><DT +>ERROR <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>Causes a custom error message to be printed at this line. This will cause +assembly to fail. This directive is most useful inside conditional constructs +to cause assembly to fail if some condition that is known bad happens.</P +></DD +><DT +>.MODULE <CODE +CLASS="PARAMETER" +>string</CODE +></DT +><DD +><P +>This directive is ignored for most output targets. If the output target +supports encoding a module name into it, <CODE +CLASS="PARAMETER" +>string</CODE +> +will be used as the module name.</P +><P +>As of version 2.2, no supported output targets support this directive.</P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x139.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x378.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Numbers and Expressions</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Macros</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x24.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,160 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>DECB Binaries</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="Output Formats" +HREF="c18.html"><LINK +REL="PREVIOUS" +TITLE="Output Formats" +HREF="c18.html"><LINK +REL="NEXT" +TITLE="Object Files" +HREF="x29.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="c18.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 2. Output Formats</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x29.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN24" +>2.2. DECB Binaries</A +></H1 +><P +>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.</P +><P +>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.</P +><P +>Both LWASM and LWLINK can output this format.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="c18.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x29.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Output Formats</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c18.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Object Files</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x29.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,163 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Object Files</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="Output Formats" +HREF="c18.html"><LINK +REL="PREVIOUS" +TITLE="DECB Binaries" +HREF="x24.html"><LINK +REL="NEXT" +TITLE="LWASM" +HREF="c35.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x24.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 2. Output Formats</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="c35.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN29" +>2.3. Object Files</A +></H1 +><P +>LWASM supports generating a proprietary object file format which is +described in <A +HREF="c675.html" +>Chapter 6</A +>. LWLINK is then used to link these +object files into a final binary in any of LWLINK's supported binary +formats.</P +><P +>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.</P +><P +>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.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x24.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>DECB Binaries</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c18.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>LWASM</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x378.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,223 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Macros</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="Assembler Directives" +HREF="x146.html"><LINK +REL="NEXT" +TITLE="Object Files and Sections" +HREF="x400.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x146.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x400.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN378" +>3.7. Macros</A +></H1 +><P +>LWASM is a macro assembler. A macro is simply a name that stands in for a +series of instructions. Once a macro is defined, it is used like any other +assembler directive. Defining a macro can be considered equivalent to adding +additional assembler directives.</P +><P +>Macros my accept parameters. These parameters are referenced within +a macro by the a backslash ("\") followed by a digit 1 through 9 for the first +through ninth parameters. They may also be referenced by enclosing the +decimal parameter number in braces ("{num}"). These parameter references +are replaced with the verbatim text of the parameter passed to the macro. A +reference to a non-existent parameter will be replaced by an empty string. +Macro parameters are expanded everywhere on each source line. That means +the parameter to a macro could be used as a symbol or it could even appear +in a comment or could cause an entire source line to be commented out +when the macro is expanded.</P +><P +>Parameters passed to a macro are separated by commas and the parameter list +is terminated by any whitespace. This means that neither a comma nor whitespace +may be included in a macro parameter.</P +><P +>Macro expansion is done recursively. That is, within a macro, macros are +expanded. This can lead to infinite loops in macro expansion. If the assembler +hangs for a long time while assembling a file that uses macros, this may be +the reason.</P +><P +>Each macro expansion receives its own local symbol context which is not +inherited by any macros called by it nor is it inherited from the context +the macro was instantiated in. That means it is possible to use local symbols +within macros without having them collide with symbols in other macros or +outside the macro itself. However, this also means that using a local symbol +as a parameter to a macro, while legal, will not do what it would seem to do +as it will result in looking up the local symbol in the macro's symbol context +rather than the enclosing context where it came from, likely yielding either +an undefined symbol error or bizarre assembly results.</P +><P +>Note that there is no way to define a macro as local to a symbol context. All +macros are part of the global macro namespace. However, macros have a separate +namespace from symbols so it is possible to have a symbol with the same name +as a macro.</P +><P +>Macros are defined only during the first pass. Macro expansion also +only occurs during the first pass. On the second pass, the macro +definition is simply ignored. Macros must be defined before they are used.</P +><P +>The following directives are used when defining macros.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="PARAMETER" +>macroname</CODE +> MACRO</DT +><DD +><P +>This directive is used to being the definition of a macro called +<CODE +CLASS="PARAMETER" +>macroname</CODE +>. If <CODE +CLASS="PARAMETER" +>macroname</CODE +> already +exists, it is considered an error. Attempting to define a macro within a +macro is undefined. It may work and it may not so the behaviour should not +be relied upon.</P +></DD +><DT +>ENDM</DT +><DD +><P +>This directive indicates the end of the macro currently being defined. It +causes the assembler to resume interpreting source lines as normal.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x146.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x400.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Assembler Directives</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Object Files and Sections</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x400.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,326 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Object Files and Sections</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="Macros" +HREF="x378.html"><LINK +REL="NEXT" +TITLE="Assembler Modes and Pragmas" +HREF="x458.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x378.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x458.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN400" +>3.8. Object Files and Sections</A +></H1 +><P +>The object file target is very useful for large project because it allows +multiple files to be assembled independently and then linked into the final +binary at a later time. It allows only the small portion of the project +that was modified to be re-assembled rather than requiring the entire set +of source code to be available to the assembler in a single assembly process. +This can be particularly important if there are a large number of macros, +symbol definitions, or other metadata that uses resources at assembly time. +By far the largest benefit, however, is keeping the source files small enough +for a mere mortal to find things in them.</P +><P +>With multi-file projects, there needs to be a means of resolving references to +symbols in other source files. These are known as external references. The +addresses of these symbols cannot be known until the linker joins all the +object files into a single binary. This means that the assembler must be +able to output the object code without knowing the value of the symbol. This +places some restrictions on the code generated by the assembler. For +example, the assembler cannot generate direct page addressing for instructions +that reference external symbols because the address of the symbol may not +be in the direct page. Similarly, relative branches and PC relative addressing +cannot be used in their eight bit forms. Everything that must be resolved +by the linker must be assembled to use the largest address size possible to +allow the linker to fill in the correct value at link time. Note that the +same problem applies to absolute address references as well, even those in +the same source file, because the address is not known until link time.</P +><P +>It is often desired in multi-file projects to have code of various types grouped +together in the final binary generated by the linker as well. The same applies +to data. In order for the linker to do that, the bits that are to be grouped +must be tagged in some manner. This is where the concept of sections comes in. +Each chunk of code or data is part of a section in the object file. Then, +when the linker reads all the object files, it coalesces all sections of the +same name into a single section and then considers it as a unit.</P +><P +>The existence of sections, however, raises a problem for symbols even +within the same source file. Thus, the assembler must treat symbols from +different sections within the same source file in the same manner as external +symbols. That is, it must leave them for the linker to resolve at link time, +with all the limitations that entails.</P +><P +>In the object file target mode, LWASM requires all source lines that +cause bytes to be output to be inside a section. Any directives that do +not cause any bytes to be output can appear outside of a section. This includes +such things as EQU or RMB. Even ORG can appear outside a section. ORG, however, +makes no sense within a section because it is the linker that determines +the starting address of the section's code, not the assembler.</P +><P +>All symbols defined globally in the assembly process are local to the +source file and cannot be exported. All symbols defined within a section are +considered local to the source file unless otherwise explicitly exported. +Symbols referenced from external source files must be declared external, +either explicitly or by asking the assembler to assume that all undefined +symbols are external.</P +><P +>It is often handy to define a number of memory addresses that will be +used for data at run-time but which need not be included in the binary file. +These memory addresses are not initialized until run-time, either by the +program itself or by the program loader, depending on the operating environment. +Such sections are often known as BSS sections. LWASM supports generating +sections with a BSS attribute set which causes the section definition including +symbols exported from that section and those symbols required to resolve +references from the local file, but with no actual code in the object file. +It is illegal for any source lines within a BSS flagged section to cause any +bytes to be output.</P +><P +>The following directives apply to section handling.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>SECTION <CODE +CLASS="PARAMETER" +>name[,flags]</CODE +>, SECT <CODE +CLASS="PARAMETER" +>name[,flags]</CODE +>, .AREA <CODE +CLASS="PARAMETER" +>name[,flags]</CODE +></DT +><DD +><P +>Instructs the assembler that the code following this directive is to be +considered part of the section <CODE +CLASS="PARAMETER" +>name</CODE +>. A section name +may appear multiple times in which case it is as though all the code from +all the instances of that section appeared adjacent within the source file. +However, <CODE +CLASS="PARAMETER" +>flags</CODE +> may only be specified on the first +instance of the section.</P +><P +>There is a single flag supported in <CODE +CLASS="PARAMETER" +>flags</CODE +>. The +flag <CODE +CLASS="PARAMETER" +>bss</CODE +> will cause the section to be treated as a BSS +section and, thus, no code will be included in the object file nor will any +bytes be permitted to be output.</P +><P +>If the section name is "bss" or ".bss" in any combination of upper and +lower case, the section is assumed to be a BSS section. In that case, +the flag <CODE +CLASS="PARAMETER" +>!bss</CODE +> can be used to override this assumption.</P +><P +>If assembly is already happening within a section, the section is implicitly +ended and the new section started. This is not considered an error although +it is recommended that all sections be explicitly closed.</P +></DD +><DT +>ENDSECTION, ENDSECT, ENDS</DT +><DD +><P +>This directive ends the current section. This puts assembly outside of any +sections until the next SECTION directive.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> EXTERN, <CODE +CLASS="PARAMETER" +>sym</CODE +> EXTERNAL, <CODE +CLASS="PARAMETER" +>sym</CODE +> IMPORT</DT +><DD +><P +>This directive defines <CODE +CLASS="PARAMETER" +>sym</CODE +> as an external symbol. +This directive may occur at any point in the source code. EXTERN definitions +are resolved on the first pass so an EXTERN definition anywhere in the +source file is valid for the entire file. The use of this directive is +optional when the assembler is instructed to assume that all undefined +symbols are external. In fact, in that mode, if the symbol is referenced +before the EXTERN directive, an error will occur.</P +></DD +><DT +><CODE +CLASS="PARAMETER" +>sym</CODE +> EXPORT, <CODE +CLASS="PARAMETER" +>sym</CODE +> .GLOBL, EXPORT <CODE +CLASS="PARAMETER" +>sym</CODE +>, .GLOBL <CODE +CLASS="PARAMETER" +>sym</CODE +></DT +><DD +><P +>This directive defines <CODE +CLASS="PARAMETER" +>sym</CODE +> as an exported symbol. +This directive may occur at any point in the source code, even before the +definition of the exported symbol.</P +><P +>Note that <CODE +CLASS="PARAMETER" +>sym</CODE +> may appear as the operand or as the +statement's symbol. If there is a symbol on the statement, that will +take precedence over any operand that is present.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x378.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x458.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Macros</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Assembler Modes and Pragmas</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x458.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,249 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Assembler Modes and Pragmas</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWASM" +HREF="c35.html"><LINK +REL="PREVIOUS" +TITLE="Object Files and Sections" +HREF="x400.html"><LINK +REL="NEXT" +TITLE="LWLINK" +HREF="c491.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x400.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. LWASM</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="c491.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN458" +>3.9. Assembler Modes and Pragmas</A +></H1 +><P +>There are a number of options that affect the way assembly is performed. +Some of these options can only be specified on the command line because +they determine something absolute about the assembly process. These include +such things as the output target. Other things may be switchable during +the assembly process. These are known as pragmas and are, by definition, +not portable between assemblers.</P +><P +>LWASM supports a number of pragmas that affect code generation or +otherwise affect the behaviour of the assembler. These may be specified by +way of a command line option or by assembler directives. The directives +are as follows.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>PRAGMA <CODE +CLASS="PARAMETER" +>pragma[,...]</CODE +></DT +><DD +><P +>Specifies that the assembler should bring into force all <CODE +CLASS="PARAMETER" +>pragma</CODE +>s +specified. Any unrecognized pragma will cause an assembly error. The new +pragmas will take effect immediately. This directive should be used when +the program will assemble incorrectly if the pragma is ignored or not supported.</P +></DD +><DT +>*PRAGMA <CODE +CLASS="PARAMETER" +>pragma[,...]</CODE +></DT +><DD +><P +>This is identical to the PRAGMA directive except no error will occur with +unrecognized or unsupported pragmas. This directive, by virtue of starting +with a comment character, will also be ignored by assemblers that do not +support this directive. Use this variation if the pragma is not required +for correct functioning of the code.</P +></DD +></DL +></DIV +><P +>Each pragma supported has a positive version and a negative version. +The positive version enables the pragma while the negative version disables +it. The negatitve version is simply the positive version with "no" prefixed +to it. For instance, "pragma" vs. "nopragma". Only the positive version is +listed below.</P +><P +>Pragmas are not case sensitive.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>index0tonone</DT +><DD +><P +>When in force, this pragma enables an optimization affecting indexed addressing +modes. When the offset expression in an indexed mode evaluates to zero but is +not explicity written as 0, this will replace the operand with the equivalent +no offset mode, thus creating slightly faster code. Because of the advantages +of this optimization, it is enabled by default.</P +></DD +><DT +>cescapes</DT +><DD +><P +>This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to +have C-style escape sequences interpreted. The one departure from the official +spec is that unrecognized escape sequences will return either the character +immediately following the backslash or some undefined value. Do not rely +on the behaviour of undefined escape sequences.</P +></DD +><DT +>undefextern</DT +><DD +><P +>This pragma is only valid for targets that support external references. When in +force, if the assembler sees an undefined symbol on the second pass, it will +automatically define it as an external symbol. This automatic definition will +apply for the remainder of the assembly process, even if the pragma is +subsequently turned off. Because this behaviour would be potentially surprising, +this pragma defaults to off.</P +><P +>The primary use for this pragma is for projects that share a large number of +symbols between source files. In such cases, it is impractical to enumerate +all the external references in every source file. This allows the assembler +and linker to do the heavy lifting while not preventing a particular source +module from defining a local symbol of the same name as an external symbol +if it does not need the external symbol. (This pragma will not cause an +automatic external definition if there is already a locally defined symbol.)</P +><P +>This pragma will often be specified on the command line for large projects. +However, depending on the specific dynamics of the project, it may be sufficient +for one or two files to use this pragma internally.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x400.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="c491.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Object Files and Sections</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c35.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>LWLINK</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x565.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,191 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Linker Operation</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWLINK" +HREF="c491.html"><LINK +REL="PREVIOUS" +TITLE="LWLINK" +HREF="c491.html"><LINK +REL="NEXT" +TITLE="Linking Scripts" +HREF="x579.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="c491.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. LWLINK</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x579.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN565" +>4.2. Linker Operation</A +></H1 +><P +> LWLINK takes one or more files in supported input formats and links them +into a single binary. Currently supported formats are the LWTOOLS object +file format and the archive format used by LWAR. While the precise method is +slightly different, linking can be conceptualized as the following steps. </P +><P +></P +><OL +TYPE="1" +><LI +><P +>First, the linker loads a linking script. If no script is specified, it +loads a built-in default script based on the output format selected. This +script tells the linker how to lay out the various sections in the final +binary.</P +></LI +><LI +><P +>Next, the linker reads all the input files into memory. At this time, it +flags any format errors in those files. It constructs a table of symbols +for each object at this time.</P +></LI +><LI +><P +>The linker then proceeds with organizing the sections loaded from each file +according to the linking script. As it does so, it is able to assign addresses +to each symbol defined in each object file. At this time, the linker may +also collapse different instances of the same section name into a single +section by appending the data from each subsequent instance of the section +to the first instance of the section.</P +></LI +><LI +><P +>Next, the linker looks through every object file for every incomplete reference. +It then attempts to fully resolve that reference. If it cannot do so, it +throws an error. Once a reference is resolved, the value is placed into +the binary code at the specified section. It should be noted that an +incomplete reference can reference either a symbol internal to the object +file or an external symbol which is in the export list of another object +file.</P +></LI +><LI +><P +>If all of the above steps are successful, the linker opens the output file +and actually constructs the binary.</P +></LI +></OL +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="c491.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="x579.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>LWLINK</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c491.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Linking Scripts</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/x579.html Wed Mar 04 03:48:39 2009 +0000 @@ -0,0 +1,243 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> +<HTML +><HEAD +><TITLE +>Linking Scripts</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK +REL="HOME" +TITLE="LW Tool Chain" +HREF="index.html"><LINK +REL="UP" +TITLE="LWLINK" +HREF="c491.html"><LINK +REL="PREVIOUS" +TITLE="Linker Operation" +HREF="x565.html"><LINK +REL="NEXT" +TITLE="Libraries and LWAR" +HREF="c613.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>LW Tool Chain</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="x565.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. LWLINK</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="c613.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN579" +>4.3. Linking Scripts</A +></H1 +><P +>A linker script is used to instruct the linker about how to assemble the +various sections into a completed binary. It consists of a series of +directives which are considered in the order they are encountered.</P +><P +>The sections will appear in the resulting binary in the order they are +specified in the script file. If a referenced section is not found, the linker will behave as though the +section did exist but had a zero size, no relocations, and no exports. +A section should only be referenced once. Any subsequent references will have +an undefined effect.</P +><P +>All numbers are in linking scripts are specified in hexadecimal. All directives +are case sensitive although the hexadecimal numbers are not.</P +><P +>A section name can be specified as a "*", then any section not +already matched by the script will be matched. The "*" can be followed +by a comma and a flag to narrow the section down slightly, also. +If the flag is "!bss", then any section that is not flagged as a bss section +will be matched. If the flag is "bss", then any section that is flagged as +bss will be matched.</P +><P +>The following directives are understood in a linker script.</P +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +>section <CODE +CLASS="PARAMETER" +>name</CODE +> load <CODE +CLASS="PARAMETER" +>addr</CODE +></DT +><DD +><P +> This causes the section <CODE +CLASS="PARAMETER" +>name</CODE +> to load at +<CODE +CLASS="PARAMETER" +>addr</CODE +>. For the raw target, only one "load at" entry is +allowed for non-bss sections and it must be the first one. For raw targets, +it affects the addresses the linker assigns to symbols but has no other +affect on the output. bss sections may all have separate load addresses but +since they will not appear in the binary anyway, this is okay.</P +><P +>For the decb target, each "load" entry will cause a new "block" to be +output to the binary which will contain the load address. It is legal for +sections to overlap in this manner - the linker assumes the loader will sort +everything out.</P +></DD +><DT +>section <CODE +CLASS="PARAMETER" +>name</CODE +></DT +><DD +><P +> This will cause the section <CODE +CLASS="PARAMETER" +>name</CODE +> to load after the previously listed +section.</P +></DD +><DT +>exec <CODE +CLASS="PARAMETER" +>addr or sym</CODE +></DT +><DD +><P +>This will cause the execution address (entry point) to be the address +specified (in hex) or the specified symbol name. The symbol name must +match a symbol that is exported by one of the object files being linked. +This has no effect for targets that do not encode the entry point into the +resulting file. If not specified, the entry point is assumed to be address 0 +which is probably not what you want. The default link scripts for targets +that support this directive automatically starts at the beginning of the +first section (usually "init" or "code") that is emitted in the binary.</P +></DD +><DT +>pad <CODE +CLASS="PARAMETER" +>size</CODE +></DT +><DD +><P +>This will cause the output file to be padded with NUL bytes to be exactly +<CODE +CLASS="PARAMETER" +>size</CODE +> bytes in length. This only makes sense for a raw target.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="x565.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="c613.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Linker Operation</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="c491.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Libraries and LWAR</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file