Mercurial > hg > index.cgi

changeset 316:c4853a54b4a1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented new "high" option for link scripts.
author William Astle <lost@l-w.ca>
date Wed, 27 Nov 2013 16:08:02 -0700
parents fcd103148aa6
children 21ecf29b568e
files docs/manual.docbook.sgml docs/manual/c879.html docs/manual/c888.html docs/manual/c941.html docs/manual/c950.html docs/manual/index.html docs/manual/manual.html docs/manual/manual.pdf docs/manual/x37.html docs/manual/x807.html docs/manual/x864.html docs/manual/x873.html
diffstat 12 files changed, 964 insertions(+), 893 deletions(-) [+]
line wrap: on
line diff
--- a/docs/manual.docbook.sgml	Wed Nov 27 16:01:26 2013 -0700
+++ b/docs/manual.docbook.sgml	Wed Nov 27 16:08:02 2013 -0700
@@ -2114,6 +2114,25 @@
 </varlistentry>
 
 <varlistentry>
+<term>section <parameter>name</parameter> high <parameter>addr</parameter></term>
+<listitem><para>
+
+This causes the section <parameter>name</parameter> to load with its end
+address just below <parameter>addr</parameter>.  Subsequent sections are
+loaded at progressively lower addresses.  This may lead to inefficient file
+encoding for some targets.  As of this writing, it will also almost
+certainly do the wrong thing for a raw target.
+
+</para><para>
+
+This is useful for aligning a block of code with high memory.  As an
+example, if the total size of a section is $100 bytes and a high address of
+$FE00 is specified, the section will actually load at $FD00.
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
 <term>section <parameter>name</parameter></term>
 <listitem><para>
 
--- a/docs/manual/c879.html	Wed Nov 27 16:01:26 2013 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,270 +0,0 @@
-<!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="Format Specific Linking Notes"
-HREF="x864.html"><LINK
-REL="NEXT"
-TITLE="Object Files"
-HREF="c941.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="x864.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="c941.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="CHAPTER"
-><H1
-><A
-NAME="AEN879"
-></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="AEN883"
->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 command line option.</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="x864.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="c941.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Format Specific Linking Notes</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
->&nbsp;</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/docs/manual/c888.html	Wed Nov 27 16:08:02 2013 -0700
@@ -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="Format Specific Linking Notes"
+HREF="x873.html"><LINK
+REL="NEXT"
+TITLE="Object Files"
+HREF="c950.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="x873.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="c950.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="CHAPTER"
+><H1
+><A
+NAME="AEN888"
+></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="AEN892"
+>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 command line option.</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="x873.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="c950.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Format Specific Linking Notes</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+>&nbsp;</TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Object Files</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
--- a/docs/manual/c941.html	Wed Nov 27 16:01:26 2013 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,376 +0,0 @@
-<!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="c879.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="c879.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
->&nbsp;</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="AEN966"
-></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
-><TR
-><TD
->FF</TD
-><TD
->This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. Flag 01 indicates an 8 bit relocation. Flag 02 indicates a zero-width relocation (see the EXTDEP pseudo op in LWASM).</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="AEN996"
-></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="c879.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"
->&nbsp;</TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Libraries and LWAR</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
->&nbsp;</TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->&nbsp;</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/manual/c950.html	Wed Nov 27 16:08:02 2013 -0700
@@ -0,0 +1,376 @@
+<!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="c888.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="c888.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+>&nbsp;</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="AEN975"
+></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
+><TR
+><TD
+>FF</TD
+><TD
+>This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. Flag 01 indicates an 8 bit relocation. Flag 02 indicates a zero-width relocation (see the EXTDEP pseudo op in LWASM).</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="AEN1005"
+></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="c888.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"
+>&nbsp;</TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Libraries and LWAR</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+>&nbsp;</TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>&nbsp;</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
--- a/docs/manual/index.html	Wed Nov 27 16:01:26 2013 -0700
+++ b/docs/manual/index.html	Wed Nov 27 16:08:02 2013 -0700
@@ -201,14 +201,14 @@
 ></DT
 ><DT
 >4.4. <A
-HREF="x864.html"
+HREF="x873.html"
 >Format Specific Linking Notes</A
 ></DT
 ><DD
 ><DL
 ><DT
 >4.4.1. <A
-HREF="x864.html#AEN867"
+HREF="x873.html#AEN876"
 >OS9 Modules</A
 ></DT
 ></DL
@@ -217,21 +217,21 @@
 ></DD
 ><DT
 >5. <A
-HREF="c879.html"
+HREF="c888.html"
 >Libraries and LWAR</A
 ></DT
 ><DD
 ><DL
 ><DT
 >5.1. <A
-HREF="c879.html#AEN883"
+HREF="c888.html#AEN892"
 >Command Line Options</A
 ></DT
 ></DL
 ></DD
 ><DT
 >6. <A
-HREF="c941.html"
+HREF="c950.html"
 >Object Files</A
 ></DT
 ></DL
@@ -246,12 +246,12 @@
 ></DT
 ><DT
 >6-1. <A
-HREF="c941.html#AEN966"
+HREF="c950.html#AEN975"
 >Object File Term Types</A
 ></DT
 ><DT
 >6-2. <A
-HREF="c941.html#AEN996"
+HREF="c950.html#AEN1005"
 >Object File Operator Numbers</A
 ></DT
 ></DL
--- a/docs/manual/manual.html	Wed Nov 27 16:01:26 2013 -0700
+++ b/docs/manual/manual.html	Wed Nov 27 16:08:02 2013 -0700
@@ -198,14 +198,14 @@
 ></DT
 ><DT
 >4.4. <A
-HREF="#AEN864"
+HREF="#AEN873"
 >Format Specific Linking Notes</A
 ></DT
 ><DD
 ><DL
 ><DT
 >4.4.1. <A
-HREF="#AEN867"
+HREF="#AEN876"
 >OS9 Modules</A
 ></DT
 ></DL
@@ -214,14 +214,14 @@
 ></DD
 ><DT
 >5. <A
-HREF="#AEN879"
+HREF="#AEN888"
 >Libraries and LWAR</A
 ></DT
 ><DD
 ><DL
 ><DT
 >5.1. <A
-HREF="#AEN883"
+HREF="#AEN892"
 >Command Line Options</A
 ></DT
 ></DL
@@ -243,12 +243,12 @@
 ></DT
 ><DT
 >6-1. <A
-HREF="#AEN966"
+HREF="#AEN975"
 >Object File Term Types</A
 ></DT
 ><DT
 >6-2. <A
-HREF="#AEN996"
+HREF="#AEN1005"
 >Object File Operator Numbers</A
 ></DT
 ></DL
@@ -2650,6 +2650,32 @@
 >section <CODE
 CLASS="PARAMETER"
 >name</CODE
+> high <CODE
+CLASS="PARAMETER"
+>addr</CODE
+></DT
+><DD
+><P
+>&#13;This causes the section <CODE
+CLASS="PARAMETER"
+>name</CODE
+> to load with its end
+address just below <CODE
+CLASS="PARAMETER"
+>addr</CODE
+>.  Subsequent sections are
+loaded at progressively lower addresses.  This may lead to inefficient file
+encoding for some targets.  As of this writing, it will also almost
+certainly do the wrong thing for a raw target.&#13;</P
+><P
+>&#13;This is useful for aligning a block of code with high memory.  As an
+example, if the total size of a section is $100 bytes and a high address of
+$FE00 is specified, the section will actually load at $FD00.&#13;</P
+></DD
+><DT
+>section <CODE
+CLASS="PARAMETER"
+>name</CODE
 ></DT
 ><DD
 ><P
@@ -2696,7 +2722,7 @@
 ><HR><H2
 CLASS="SECTION"
 ><A
-NAME="AEN864"
+NAME="AEN873"
 >4.4. Format Specific Linking Notes</A
 ></H2
 ><P
@@ -2709,7 +2735,7 @@
 ><HR><H3
 CLASS="SECTION"
 ><A
-NAME="AEN867"
+NAME="AEN876"
 >4.4.1. OS9 Modules</A
 ></H3
 ><P
@@ -2785,7 +2811,7 @@
 CLASS="CHAPTER"
 ><HR><H1
 ><A
-NAME="AEN879"
+NAME="AEN888"
 ></A
 >Chapter 5. Libraries and LWAR</H1
 ><P
@@ -2804,7 +2830,7 @@
 ><HR><H2
 CLASS="SECTION"
 ><A
-NAME="AEN883"
+NAME="AEN892"
 >5.1. Command Line Options</A
 ></H2
 ><P
@@ -3005,7 +3031,7 @@
 ><DIV
 CLASS="TABLE"
 ><A
-NAME="AEN966"
+NAME="AEN975"
 ></A
 ><P
 ><B
@@ -3077,7 +3103,7 @@
 ><DIV
 CLASS="TABLE"
 ><A
-NAME="AEN996"
+NAME="AEN1005"
 ></A
 ><P
 ><B
Binary file docs/manual/manual.pdf has changed
--- a/docs/manual/x37.html	Wed Nov 27 16:01:26 2013 -0700
+++ b/docs/manual/x37.html	Wed Nov 27 16:08:02 2013 -0700
@@ -79,7 +79,7 @@
 ><P
 >LWASM supports generating a proprietary object file format which is
 described in <A
-HREF="c941.html"
+HREF="c950.html"
 >Chapter 6</A
 >. LWLINK is then used to link these
 object files into a final binary in any of LWLINK's supported binary
--- a/docs/manual/x807.html	Wed Nov 27 16:01:26 2013 -0700
+++ b/docs/manual/x807.html	Wed Nov 27 16:08:02 2013 -0700
@@ -17,7 +17,7 @@
 HREF="x793.html"><LINK
 REL="NEXT"
 TITLE="Format Specific Linking Notes"
-HREF="x864.html"></HEAD
+HREF="x873.html"></HEAD
 ><BODY
 CLASS="SECTION"
 BGCOLOR="#FFFFFF"
@@ -59,7 +59,7 @@
 ALIGN="right"
 VALIGN="bottom"
 ><A
-HREF="x864.html"
+HREF="x873.html"
 ACCESSKEY="N"
 >Next</A
 ></TD
@@ -205,6 +205,32 @@
 >section <CODE
 CLASS="PARAMETER"
 >name</CODE
+> high <CODE
+CLASS="PARAMETER"
+>addr</CODE
+></DT
+><DD
+><P
+>&#13;This causes the section <CODE
+CLASS="PARAMETER"
+>name</CODE
+> to load with its end
+address just below <CODE
+CLASS="PARAMETER"
+>addr</CODE
+>.  Subsequent sections are
+loaded at progressively lower addresses.  This may lead to inefficient file
+encoding for some targets.  As of this writing, it will also almost
+certainly do the wrong thing for a raw target.&#13;</P
+><P
+>&#13;This is useful for aligning a block of code with high memory.  As an
+example, if the total size of a section is $100 bytes and a high address of
+$FE00 is specified, the section will actually load at $FD00.&#13;</P
+></DD
+><DT
+>section <CODE
+CLASS="PARAMETER"
+>name</CODE
 ></DT
 ><DD
 ><P
@@ -280,7 +306,7 @@
 ALIGN="right"
 VALIGN="top"
 ><A
-HREF="x864.html"
+HREF="x873.html"
 ACCESSKEY="N"
 >Next</A
 ></TD
--- a/docs/manual/x864.html	Wed Nov 27 16:01:26 2013 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,224 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
-<HTML
-><HEAD
-><TITLE
->Format Specific Linking Notes</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="c693.html"><LINK
-REL="PREVIOUS"
-TITLE="Linking Scripts"
-HREF="x807.html"><LINK
-REL="NEXT"
-TITLE="Libraries and LWAR"
-HREF="c879.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="x807.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="c879.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="SECTION"
-><H1
-CLASS="SECTION"
-><A
-NAME="AEN864"
->4.4. Format Specific Linking Notes</A
-></H1
-><P
->Some formats require special information to be able to generate actual
-binaries.  If the specific format you are interested in is not listed in
-this section, then there is nothing special you need to know about to create
-a final binary.</P
-><DIV
-CLASS="SECTION"
-><H2
-CLASS="SECTION"
-><A
-NAME="AEN867"
->4.4.1. OS9 Modules</A
-></H2
-><P
->OS9 modules need to embed several items into the module header. These
-items are the type of module, the langauge of the module, the module
-attributes, the module revision number, the data size (bss), and the
-execution offset.  These are all either calculated or default to reasonable
-values.</P
-><P
->The data size is calcuated as the sum of all sections named "bss" or
-".bss" in all object files that are linked together.</P
-><P
->The execution offset is calculated from the address of the special
-symbol "__start" which must be an exported (external) symbol in one of the
-objects to be linked.</P
-><P
->The type defaults to "Prgrm" or "Program module". The language
-defaults to "Objct" or "6809 object code".  Attributes default to enabling
-the re-entrant flag.  And finally, the revision defaults to zero.</P
-><P
->The embedded module name is the output filename. If the output
-filename includes more than just the filename, this will probably not be
-what you want.</P
-><P
->The type, language, attributes, revision, and module name can all be
-overridden by providing a special section in exactly one of the object files
-to be linked.  This section is called "__os9" (note the two underscores). 
-To override the type, language, attributes, or revision values, define a
-non-exported symbol in this section called "type", "lang", "attr", or "rev"
-respectively.  Any other symbols defined are ignored.  To override the
-module name, include as the only actual code in the section a NUL terminated
-string (the FCN directive is useful for this).  If there is no code in the
-section or it beings with a NUL, the default name will be used.  Any of the
-preceeding that are not defined in the special section will retain their
-default values.</P
-><P
->The built-in link script for OS9 modules will place the following
-sections, in order, in the module: "code", ".text", "data", ".data".  It
-will merge all sections with the name "bss" or ".bss" into the "data"
-section.  All other section names are ignored.  What this means is that you
-must define your data variables in the a section called "bss" or ".bss" even
-though you will be refencing them all as offsets from U.  This does have the
-unpleasant side effect that all BSS references will end up being 16 bit
-offsets because the assembler cannot know what the offset will be once the
-linker is finished its work.  Thus, if the tightest possible code is
-required, having LWASM directly output the module is a better choice.</P
-><P
->While the built-in link script is probably sufficient for most
-purposes, you can provide your own script.  If you provide a custom link
-script, you must start your code and data sections at location 000D to
-accommodate the module header.  Otherwise, you will have an incorrect
-location for the execution offset.  You must use the ENTRY directive in the
-script to define the entry point for the module.</P
-><P
->It should also be obvious from the above that you cannot mix the bss
-(rmb) definitions with the module code when linking separately.  Those
-familiar with typical module creation will probably find this an unpleasant
-difference but it is unavoidable.</P
-><P
->It should also be noted that direct page references should also be
-avoided because you cannot know ahead of time whether the linker is going to
-end up putting a particular variable in the first 256 bytes of the module's
-data space.  If, however, you know for certain you will have less than 256
-bytes of defined data space across all of the object files that will be
-linked, you can instead use forced DP addressing for your data addresses
-instead of the ,u notation.  When linking with 3rd party libraries, this
-practice should be avoided.  Also, when creating libraries, always use the
-offset from U technique.</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="x807.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="c879.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"
-><A
-HREF="c693.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
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/manual/x873.html	Wed Nov 27 16:08:02 2013 -0700
@@ -0,0 +1,224 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<HTML
+><HEAD
+><TITLE
+>Format Specific Linking Notes</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="c693.html"><LINK
+REL="PREVIOUS"
+TITLE="Linking Scripts"
+HREF="x807.html"><LINK
+REL="NEXT"
+TITLE="Libraries and LWAR"
+HREF="c888.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="x807.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="c888.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECTION"
+><H1
+CLASS="SECTION"
+><A
+NAME="AEN873"
+>4.4. Format Specific Linking Notes</A
+></H1
+><P
+>Some formats require special information to be able to generate actual
+binaries.  If the specific format you are interested in is not listed in
+this section, then there is nothing special you need to know about to create
+a final binary.</P
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN876"
+>4.4.1. OS9 Modules</A
+></H2
+><P
+>OS9 modules need to embed several items into the module header. These
+items are the type of module, the langauge of the module, the module
+attributes, the module revision number, the data size (bss), and the
+execution offset.  These are all either calculated or default to reasonable
+values.</P
+><P
+>The data size is calcuated as the sum of all sections named "bss" or
+".bss" in all object files that are linked together.</P
+><P
+>The execution offset is calculated from the address of the special
+symbol "__start" which must be an exported (external) symbol in one of the
+objects to be linked.</P
+><P
+>The type defaults to "Prgrm" or "Program module". The language
+defaults to "Objct" or "6809 object code".  Attributes default to enabling
+the re-entrant flag.  And finally, the revision defaults to zero.</P
+><P
+>The embedded module name is the output filename. If the output
+filename includes more than just the filename, this will probably not be
+what you want.</P
+><P
+>The type, language, attributes, revision, and module name can all be
+overridden by providing a special section in exactly one of the object files
+to be linked.  This section is called "__os9" (note the two underscores). 
+To override the type, language, attributes, or revision values, define a
+non-exported symbol in this section called "type", "lang", "attr", or "rev"
+respectively.  Any other symbols defined are ignored.  To override the
+module name, include as the only actual code in the section a NUL terminated
+string (the FCN directive is useful for this).  If there is no code in the
+section or it beings with a NUL, the default name will be used.  Any of the
+preceeding that are not defined in the special section will retain their
+default values.</P
+><P
+>The built-in link script for OS9 modules will place the following
+sections, in order, in the module: "code", ".text", "data", ".data".  It
+will merge all sections with the name "bss" or ".bss" into the "data"
+section.  All other section names are ignored.  What this means is that you
+must define your data variables in the a section called "bss" or ".bss" even
+though you will be refencing them all as offsets from U.  This does have the
+unpleasant side effect that all BSS references will end up being 16 bit
+offsets because the assembler cannot know what the offset will be once the
+linker is finished its work.  Thus, if the tightest possible code is
+required, having LWASM directly output the module is a better choice.</P
+><P
+>While the built-in link script is probably sufficient for most
+purposes, you can provide your own script.  If you provide a custom link
+script, you must start your code and data sections at location 000D to
+accommodate the module header.  Otherwise, you will have an incorrect
+location for the execution offset.  You must use the ENTRY directive in the
+script to define the entry point for the module.</P
+><P
+>It should also be obvious from the above that you cannot mix the bss
+(rmb) definitions with the module code when linking separately.  Those
+familiar with typical module creation will probably find this an unpleasant
+difference but it is unavoidable.</P
+><P
+>It should also be noted that direct page references should also be
+avoided because you cannot know ahead of time whether the linker is going to
+end up putting a particular variable in the first 256 bytes of the module's
+data space.  If, however, you know for certain you will have less than 256
+bytes of defined data space across all of the object files that will be
+linked, you can instead use forced DP addressing for your data addresses
+instead of the ,u notation.  When linking with 3rd party libraries, this
+practice should be avoided.  Also, when creating libraries, always use the
+offset from U technique.</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="x807.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="c888.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"
+><A
+HREF="c693.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