Mercurial > hg > index.cgi
changeset 168:1e0a0e6cd918
Documentation updates
| author | lost@l-w.ca |
|---|---|
| date | Mon, 29 Aug 2011 19:15:50 -0600 |
| parents | 872fa82680e1 |
| children | eb7d220465fb |
| files | docs/manual.docbook.sgml docs/manual/README docs/manual/c661.html docs/manual/c662.html docs/manual/c824.html docs/manual/c825.html docs/manual/c886.html docs/manual/c887.html docs/manual/index.html docs/manual/manual.html docs/manual/manual.pdf docs/manual/x37.html docs/manual/x520.html docs/manual/x583.html docs/manual/x584.html docs/manual/x761.html docs/manual/x762.html docs/manual/x775.html docs/manual/x776.html docs/manual/x809.html docs/manual/x810.html |
| diffstat | 21 files changed, 2102 insertions(+), 2069 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/manual.docbook.sgml Mon Aug 29 19:05:18 2011 -0600 +++ b/docs/manual.docbook.sgml Mon Aug 29 19:15:50 2011 -0600 @@ -1330,15 +1330,31 @@ However, <parameter>flags</parameter> may only be specified on the first instance of the section. </para> -<para>There is a single flag supported in <parameter>flags</parameter>. The -flag <parameter>bss</parameter> 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.</para> + +<para><parameter>flags</parameter> is a comma separated list of flags. If a +flag is "bss", the section will be treated as a BSS section and no +statements that generate output are permitted.</para> + +<para>If the flag is "constant", +the same restrictions apply as for BSS sections. Additionally, all symbols +defined in a constant section define absolute values and will not be +adjusted by the linker at link time. Constant sections cannot define +complex expressions for symbols; the value must be fully defined at assembly +time. Additionally, multiple instances of a constant section do not +coalesce into a single addressing unit; each instance starts again at offset +0.</para> + <para> 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 <parameter>!bss</parameter> can be used to override this assumption. </para> + +<para> If the section name is "_constants" or "_constant", in any +combination of upper and lower case, the section is assumed to be a constant +section. This assumption can be overridden with the "!constant" +flag.</para> + <para> 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
--- a/docs/manual/README Mon Aug 29 19:05:18 2011 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,3 +0,0 @@ -This folder contains the manual in various forms which may or may -not be present unless this is an actual release. Even then, they may -or may not be present.
--- a/docs/manual/c661.html Mon Aug 29 19:05:18 2011 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,336 +0,0 @@ -<!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="x583.html"><LINK -REL="NEXT" -TITLE="Linker Operation" -HREF="x761.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="x583.html" -ACCESSKEY="P" ->Prev</A -></TD -><TD -WIDTH="80%" -ALIGN="center" -VALIGN="bottom" -></TD -><TD -WIDTH="10%" -ALIGN="right" -VALIGN="bottom" -><A -HREF="x761.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -></TABLE -><HR -ALIGN="LEFT" -WIDTH="100%"></DIV -><DIV -CLASS="CHAPTER" -><H1 -><A -NAME="AEN661" -></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="AEN664" ->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" ->-f 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" ->--section-base=SECT=BASE</CODE -></DT -><DD -><P ->Cause section SECT to load at base address BASE. This will be prepended -to the built-in link script. It is ignored if a link script is provided.</P -></DD -><DT -><CODE -CLASS="OPTION" ->--map=FILE</CODE ->, <CODE -CLASS="OPTION" ->-m FILE</CODE -></DT -><DD -><P ->This will output a description of the link result to FILE.</P -></DD -><DT -><CODE -CLASS="OPTION" ->--library=LIBSPEC</CODE ->, <CODE -CLASS="OPTION" ->-l LIBSPEC</CODE -></DT -><DD -><P ->Load a library using the library search path. LIBSPEC will have "lib" prepended -and ".a" appended.</P -></DD -><DT -><CODE -CLASS="OPTION" ->--library-path=DIR</CODE ->, <CODE -CLASS="OPTION" ->-L DIR</CODE -></DT -><DD -><P ->Add DIR to the library search path.</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.</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="x583.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="x761.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/docs/manual/c662.html Mon Aug 29 19:15:50 2011 -0600 @@ -0,0 +1,336 @@ +<!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="x584.html"><LINK +REL="NEXT" +TITLE="Linker Operation" +HREF="x762.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="x584.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="x762.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="AEN662" +></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="AEN665" +>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" +>-f 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" +>--section-base=SECT=BASE</CODE +></DT +><DD +><P +>Cause section SECT to load at base address BASE. This will be prepended +to the built-in link script. It is ignored if a link script is provided.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--map=FILE</CODE +>, <CODE +CLASS="OPTION" +>-m FILE</CODE +></DT +><DD +><P +>This will output a description of the link result to FILE.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--library=LIBSPEC</CODE +>, <CODE +CLASS="OPTION" +>-l LIBSPEC</CODE +></DT +><DD +><P +>Load a library using the library search path. LIBSPEC will have "lib" prepended +and ".a" appended.</P +></DD +><DT +><CODE +CLASS="OPTION" +>--library-path=DIR</CODE +>, <CODE +CLASS="OPTION" +>-L DIR</CODE +></DT +><DD +><P +>Add DIR to the library search path.</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.</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="x584.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="x762.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
--- a/docs/manual/c824.html Mon Aug 29 19:05:18 2011 -0600 +++ /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="x809.html"><LINK -REL="NEXT" -TITLE="Object Files" -HREF="c886.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="x809.html" -ACCESSKEY="P" ->Prev</A -></TD -><TD -WIDTH="80%" -ALIGN="center" -VALIGN="bottom" -></TD -><TD -WIDTH="10%" -ALIGN="right" -VALIGN="bottom" -><A -HREF="c886.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -></TABLE -><HR -ALIGN="LEFT" -WIDTH="100%"></DIV -><DIV -CLASS="CHAPTER" -><H1 -><A -NAME="AEN824" -></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="AEN828" ->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="x809.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="c886.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" -> </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/c825.html Mon Aug 29 19:15:50 2011 -0600 @@ -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="x810.html"><LINK +REL="NEXT" +TITLE="Object Files" +HREF="c887.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="x810.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="c887.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="AEN825" +></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="AEN829" +>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="x810.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="c887.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" +> </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/c886.html Mon Aug 29 19:05:18 2011 -0600 +++ /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="c824.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="c824.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="AEN911" -></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="AEN941" -></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="c824.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/docs/manual/c887.html Mon Aug 29 19:15:50 2011 -0600 @@ -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="c825.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="c825.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="AEN912" +></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="AEN942" +></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="c825.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
--- a/docs/manual/index.html Mon Aug 29 19:05:18 2011 -0600 +++ b/docs/manual/index.html Mon Aug 29 19:15:50 2011 -0600 @@ -172,43 +172,43 @@ ></DT ><DT >3.10. <A -HREF="x583.html" +HREF="x584.html" >Assembler Modes and Pragmas</A ></DT ></DL ></DD ><DT >4. <A -HREF="c661.html" +HREF="c662.html" >LWLINK</A ></DT ><DD ><DL ><DT >4.1. <A -HREF="c661.html#AEN664" +HREF="c662.html#AEN665" >Command Line Options</A ></DT ><DT >4.2. <A -HREF="x761.html" +HREF="x762.html" >Linker Operation</A ></DT ><DT >4.3. <A -HREF="x775.html" +HREF="x776.html" >Linking Scripts</A ></DT ><DT >4.4. <A -HREF="x809.html" +HREF="x810.html" >Format Specific Linking Notes</A ></DT ><DD ><DL ><DT >4.4.1. <A -HREF="x809.html#AEN812" +HREF="x810.html#AEN813" >OS9 Modules</A ></DT ></DL @@ -217,21 +217,21 @@ ></DD ><DT >5. <A -HREF="c824.html" +HREF="c825.html" >Libraries and LWAR</A ></DT ><DD ><DL ><DT >5.1. <A -HREF="c824.html#AEN828" +HREF="c825.html#AEN829" >Command Line Options</A ></DT ></DL ></DD ><DT >6. <A -HREF="c886.html" +HREF="c887.html" >Object Files</A ></DT ></DL @@ -246,12 +246,12 @@ ></DT ><DT >6-1. <A -HREF="c886.html#AEN911" +HREF="c887.html#AEN912" >Object File Term Types</A ></DT ><DT >6-2. <A -HREF="c886.html#AEN941" +HREF="c887.html#AEN942" >Object File Operator Numbers</A ></DT ></DL
--- a/docs/manual/manual.html Mon Aug 29 19:05:18 2011 -0600 +++ b/docs/manual/manual.html Mon Aug 29 19:15:50 2011 -0600 @@ -169,43 +169,43 @@ ></DT ><DT >3.10. <A -HREF="#AEN583" +HREF="#AEN584" >Assembler Modes and Pragmas</A ></DT ></DL ></DD ><DT >4. <A -HREF="#AEN661" +HREF="#AEN662" >LWLINK</A ></DT ><DD ><DL ><DT >4.1. <A -HREF="#AEN664" +HREF="#AEN665" >Command Line Options</A ></DT ><DT >4.2. <A -HREF="#AEN761" +HREF="#AEN762" >Linker Operation</A ></DT ><DT >4.3. <A -HREF="#AEN775" +HREF="#AEN776" >Linking Scripts</A ></DT ><DT >4.4. <A -HREF="#AEN809" +HREF="#AEN810" >Format Specific Linking Notes</A ></DT ><DD ><DL ><DT >4.4.1. <A -HREF="#AEN812" +HREF="#AEN813" >OS9 Modules</A ></DT ></DL @@ -214,14 +214,14 @@ ></DD ><DT >5. <A -HREF="#AEN824" +HREF="#AEN825" >Libraries and LWAR</A ></DT ><DD ><DL ><DT >5.1. <A -HREF="#AEN828" +HREF="#AEN829" >Command Line Options</A ></DT ></DL @@ -243,12 +243,12 @@ ></DT ><DT >6-1. <A -HREF="#AEN911" +HREF="#AEN912" >Object File Term Types</A ></DT ><DT >6-2. <A -HREF="#AEN941" +HREF="#AEN942" >Object File Operator Numbers</A ></DT ></DL @@ -1828,16 +1828,21 @@ > may only be specified on the first instance of the section.</P ><P ->There is a single flag supported in <CODE +><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 +> is a comma separated list of flags. If a +flag is "bss", the section will be treated as a BSS section and no +statements that generate output are permitted.</P +><P +>If the flag is "constant", +the same restrictions apply as for BSS sections. Additionally, all symbols +defined in a constant section define absolute values and will not be +adjusted by the linker at link time. Constant sections cannot define +complex expressions for symbols; the value must be fully defined at assembly +time. Additionally, multiple instances of a constant section do not +coalesce into a single addressing unit; each instance starts again at offset +0.</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, @@ -1846,6 +1851,11 @@ >!bss</CODE > can be used to override this assumption.</P ><P +> If the section name is "_constants" or "_constant", in any +combination of upper and lower case, the section is assumed to be a constant +section. This assumption can be overridden with the "!constant" +flag.</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 @@ -1935,7 +1945,7 @@ ><HR><H2 CLASS="SECTION" ><A -NAME="AEN583" +NAME="AEN584" >3.10. Assembler Modes and Pragmas</A ></H2 ><P @@ -2168,7 +2178,7 @@ CLASS="CHAPTER" ><HR><H1 ><A -NAME="AEN661" +NAME="AEN662" ></A >Chapter 4. LWLINK</H1 ><P @@ -2179,7 +2189,7 @@ ><HR><H2 CLASS="SECTION" ><A -NAME="AEN664" +NAME="AEN665" >4.1. Command Line Options</A ></H2 ><P @@ -2376,7 +2386,7 @@ ><HR><H2 CLASS="SECTION" ><A -NAME="AEN761" +NAME="AEN762" >4.2. Linker Operation</A ></H2 ><P @@ -2432,7 +2442,7 @@ ><HR><H2 CLASS="SECTION" ><A -NAME="AEN775" +NAME="AEN776" >4.3. Linking Scripts</A ></H2 ><P @@ -2540,7 +2550,7 @@ ><HR><H2 CLASS="SECTION" ><A -NAME="AEN809" +NAME="AEN810" >4.4. Format Specific Linking Notes</A ></H2 ><P @@ -2553,7 +2563,7 @@ ><HR><H3 CLASS="SECTION" ><A -NAME="AEN812" +NAME="AEN813" >4.4.1. OS9 Modules</A ></H3 ><P @@ -2629,7 +2639,7 @@ CLASS="CHAPTER" ><HR><H1 ><A -NAME="AEN824" +NAME="AEN825" ></A >Chapter 5. Libraries and LWAR</H1 ><P @@ -2648,7 +2658,7 @@ ><HR><H2 CLASS="SECTION" ><A -NAME="AEN828" +NAME="AEN829" >5.1. Command Line Options</A ></H2 ><P @@ -2849,7 +2859,7 @@ ><DIV CLASS="TABLE" ><A -NAME="AEN911" +NAME="AEN912" ></A ><P ><B @@ -2921,7 +2931,7 @@ ><DIV CLASS="TABLE" ><A -NAME="AEN941" +NAME="AEN942" ></A ><P ><B
--- a/docs/manual/x37.html Mon Aug 29 19:05:18 2011 -0600 +++ b/docs/manual/x37.html Mon Aug 29 19:15:50 2011 -0600 @@ -79,7 +79,7 @@ ><P >LWASM supports generating a proprietary object file format which is described in <A -HREF="c886.html" +HREF="c887.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/x520.html Mon Aug 29 19:05:18 2011 -0600 +++ b/docs/manual/x520.html Mon Aug 29 19:15:50 2011 -0600 @@ -17,7 +17,7 @@ HREF="x499.html"><LINK REL="NEXT" TITLE="Assembler Modes and Pragmas" -HREF="x583.html"></HEAD +HREF="x584.html"></HEAD ><BODY CLASS="SECTION" BGCOLOR="#FFFFFF" @@ -59,7 +59,7 @@ ALIGN="right" VALIGN="bottom" ><A -HREF="x583.html" +HREF="x584.html" ACCESSKEY="N" >Next</A ></TD @@ -173,16 +173,21 @@ > may only be specified on the first instance of the section.</P ><P ->There is a single flag supported in <CODE +><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 +> is a comma separated list of flags. If a +flag is "bss", the section will be treated as a BSS section and no +statements that generate output are permitted.</P +><P +>If the flag is "constant", +the same restrictions apply as for BSS sections. Additionally, all symbols +defined in a constant section define absolute values and will not be +adjusted by the linker at link time. Constant sections cannot define +complex expressions for symbols; the value must be fully defined at assembly +time. Additionally, multiple instances of a constant section do not +coalesce into a single addressing unit; each instance starts again at offset +0.</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, @@ -191,6 +196,11 @@ >!bss</CODE > can be used to override this assumption.</P ><P +> If the section name is "_constants" or "_constant", in any +combination of upper and lower case, the section is assumed to be a constant +section. This assumption can be overridden with the "!constant" +flag.</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 @@ -309,7 +319,7 @@ ALIGN="right" VALIGN="top" ><A -HREF="x583.html" +HREF="x584.html" ACCESSKEY="N" >Next</A ></TD
--- a/docs/manual/x583.html Mon Aug 29 19:05:18 2011 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,368 +0,0 @@ -<!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="c45.html"><LINK -REL="PREVIOUS" -TITLE="Object Files and Sections" -HREF="x520.html"><LINK -REL="NEXT" -TITLE="LWLINK" -HREF="c661.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="x520.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="c661.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -></TABLE -><HR -ALIGN="LEFT" -WIDTH="100%"></DIV -><DIV -CLASS="SECTION" -><H1 -CLASS="SECTION" -><A -NAME="AEN583" ->3.10. 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 -><DT ->*PRAGMAPUSH <CODE -CLASS="PARAMETER" ->pragma[,...]</CODE -></DT -><DD -><P ->This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.</P -><P ->This directive will not throw any errors for any reason.</P -></DD -><DT ->*PRAGMAPOP <CODE -CLASS="PARAMETER" ->pragma[,...]</CODE -></DT -><DD -><P ->This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.</P -><P ->This directive will not throw any errors for any reason.</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 ->importundefexport</DT -><DD -><P ->This pragma is only valid for targets that support external references. When -in force, it will cause the EXPORT directive to act as IMPORT if the symbol -to be exported is not defined. This is provided for compatibility with the -output of gcc6809 and should not be used in hand written code. Because of -the confusion this pragma can cause, it is disabled by default.</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 -><DT ->dollarlocal</DT -><DD -><P ->When set, a "$" in a symbol makes it local. When not set, "$" does not -cause a symbol to be local. It is set by default except when using the OS9 -target.</P -></DD -><DT ->dollarnotlocal</DT -><DD -><P -> This is the same as the "dollarlocal" pragma except its sense is -reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and -"nodollarlocal" and "dollarnotlocal" are equivalent. </P -></DD -><DT ->pcaspcr</DT -><DD -><P -> Normally, LWASM makes a distinction between PC and PCR in program -counter relative addressing. In particular, the use of PC means an absolute -offset from PC while PCR causes the assembler to calculate the offset to the -specified operand and use that as the offset from PC. By setting this -pragma, you can have PC treated the same as PCR. </P -></DD -><DT ->shadow</DT -><DD -><P ->When this pragma is in effect, it becomes possible to define a macro -that matches an internal operation code. Thus, it makes it possible to -redefine either CPU instructions or pseudo operations. Because this feature -is of dubious utility, it is disabled by default.</P -></DD -><DT ->nolist</DT -><DD -><P ->Lines where this pragma is in effect will not appear in the assembly -listing. Also, any symbols defined under this pragma will not show up in -the symbol list. This is most useful in include files to avoid spamming the -assembly listing with dozens, hundreds, or thousands of irrelevant -symbols.</P -></DD -><DT ->autobranchlength</DT -><DD -><P ->One of the perennial annoyances for 6809 programmers is that the -mneumonics for the short and long branch instructions are different (bxx vs. -lbxx), which is at odds with the rest of the instruction set. This pragma -is a solution to those annoying byte overflow errors that short branch -instructions tend to aquire.</P -><P ->When this pragma is in effect, which is not the default, whenever any -relative branch instruction is used, its size will be automatically -determined based on the actual distance to the destination. In other words, -one can write code with long or short branches everywhere and the assembler -will choose a size for the branch.</P -><P ->Also, while this pragma is in effect, the > and < symbols can be used -to force the branch size, analogous to their use for other instructions with -< forcing 8 bit offsets and > forcing 16 bit offets.</P -><P ->Because this pragma leads to source that is incompatible with other -assemblers, it is strongly recommended that it be invoked using the PRAGMA -directive within the source code rather than on the command line or via the -*PRAGMA directive. This way, an error will be raised if someone tries to -* assemble the code under a different assembler.</P -></DD -></DL -></DIV -><P ->As a convenience, each input file has a pragma state stack. This -allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a -pragma state and then restore it to the precise state it had previously. -If, at the end of an input file, all pragma states have not been popped, -they will be removed from the stack. Thus, it is critical to employ -*PRAGMAPOP correctly. Because each input file has its own pragma stack, -using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not -work.</P -><P ->Pragma stacks are more useful in include files, in particular in -conjunction with the nolist pragma. One can push the state of the nolist -pragma, engage the nolist pragma, and then pop the state of the nolist -pragma at the end of the include file. This will cause the entire include -file to operate under the nolist pragma. However, if the file is included -while nolist is already engaged, it will not undo that state.</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="x520.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="c661.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="c45.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/docs/manual/x584.html Mon Aug 29 19:15:50 2011 -0600 @@ -0,0 +1,368 @@ +<!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="c45.html"><LINK +REL="PREVIOUS" +TITLE="Object Files and Sections" +HREF="x520.html"><LINK +REL="NEXT" +TITLE="LWLINK" +HREF="c662.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="x520.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="c662.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN584" +>3.10. 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 +><DT +>*PRAGMAPUSH <CODE +CLASS="PARAMETER" +>pragma[,...]</CODE +></DT +><DD +><P +>This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.</P +><P +>This directive will not throw any errors for any reason.</P +></DD +><DT +>*PRAGMAPOP <CODE +CLASS="PARAMETER" +>pragma[,...]</CODE +></DT +><DD +><P +>This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.</P +><P +>This directive will not throw any errors for any reason.</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 +>importundefexport</DT +><DD +><P +>This pragma is only valid for targets that support external references. When +in force, it will cause the EXPORT directive to act as IMPORT if the symbol +to be exported is not defined. This is provided for compatibility with the +output of gcc6809 and should not be used in hand written code. Because of +the confusion this pragma can cause, it is disabled by default.</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 +><DT +>dollarlocal</DT +><DD +><P +>When set, a "$" in a symbol makes it local. When not set, "$" does not +cause a symbol to be local. It is set by default except when using the OS9 +target.</P +></DD +><DT +>dollarnotlocal</DT +><DD +><P +> This is the same as the "dollarlocal" pragma except its sense is +reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and +"nodollarlocal" and "dollarnotlocal" are equivalent. </P +></DD +><DT +>pcaspcr</DT +><DD +><P +> Normally, LWASM makes a distinction between PC and PCR in program +counter relative addressing. In particular, the use of PC means an absolute +offset from PC while PCR causes the assembler to calculate the offset to the +specified operand and use that as the offset from PC. By setting this +pragma, you can have PC treated the same as PCR. </P +></DD +><DT +>shadow</DT +><DD +><P +>When this pragma is in effect, it becomes possible to define a macro +that matches an internal operation code. Thus, it makes it possible to +redefine either CPU instructions or pseudo operations. Because this feature +is of dubious utility, it is disabled by default.</P +></DD +><DT +>nolist</DT +><DD +><P +>Lines where this pragma is in effect will not appear in the assembly +listing. Also, any symbols defined under this pragma will not show up in +the symbol list. This is most useful in include files to avoid spamming the +assembly listing with dozens, hundreds, or thousands of irrelevant +symbols.</P +></DD +><DT +>autobranchlength</DT +><DD +><P +>One of the perennial annoyances for 6809 programmers is that the +mneumonics for the short and long branch instructions are different (bxx vs. +lbxx), which is at odds with the rest of the instruction set. This pragma +is a solution to those annoying byte overflow errors that short branch +instructions tend to aquire.</P +><P +>When this pragma is in effect, which is not the default, whenever any +relative branch instruction is used, its size will be automatically +determined based on the actual distance to the destination. In other words, +one can write code with long or short branches everywhere and the assembler +will choose a size for the branch.</P +><P +>Also, while this pragma is in effect, the > and < symbols can be used +to force the branch size, analogous to their use for other instructions with +< forcing 8 bit offsets and > forcing 16 bit offets.</P +><P +>Because this pragma leads to source that is incompatible with other +assemblers, it is strongly recommended that it be invoked using the PRAGMA +directive within the source code rather than on the command line or via the +*PRAGMA directive. This way, an error will be raised if someone tries to +* assemble the code under a different assembler.</P +></DD +></DL +></DIV +><P +>As a convenience, each input file has a pragma state stack. This +allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a +pragma state and then restore it to the precise state it had previously. +If, at the end of an input file, all pragma states have not been popped, +they will be removed from the stack. Thus, it is critical to employ +*PRAGMAPOP correctly. Because each input file has its own pragma stack, +using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not +work.</P +><P +>Pragma stacks are more useful in include files, in particular in +conjunction with the nolist pragma. One can push the state of the nolist +pragma, engage the nolist pragma, and then pop the state of the nolist +pragma at the end of the include file. This will cause the entire include +file to operate under the nolist pragma. However, if the file is included +while nolist is already engaged, it will not undo that state.</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="x520.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="c662.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="c45.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
--- a/docs/manual/x761.html Mon Aug 29 19:05:18 2011 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,191 +0,0 @@ -<!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="c661.html"><LINK -REL="PREVIOUS" -TITLE="LWLINK" -HREF="c661.html"><LINK -REL="NEXT" -TITLE="Linking Scripts" -HREF="x775.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="c661.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="x775.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -></TABLE -><HR -ALIGN="LEFT" -WIDTH="100%"></DIV -><DIV -CLASS="SECTION" -><H1 -CLASS="SECTION" -><A -NAME="AEN761" ->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="c661.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="x775.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="c661.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/docs/manual/x762.html Mon Aug 29 19:15:50 2011 -0600 @@ -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="c662.html"><LINK +REL="PREVIOUS" +TITLE="LWLINK" +HREF="c662.html"><LINK +REL="NEXT" +TITLE="Linking Scripts" +HREF="x776.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="c662.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="x776.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN762" +>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="c662.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="x776.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="c662.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
--- a/docs/manual/x775.html Mon Aug 29 19:05:18 2011 -0600 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,243 +0,0 @@ -<!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="c661.html"><LINK -REL="PREVIOUS" -TITLE="Linker Operation" -HREF="x761.html"><LINK -REL="NEXT" -TITLE="Format Specific Linking Notes" -HREF="x809.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="x761.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="x809.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -></TABLE -><HR -ALIGN="LEFT" -WIDTH="100%"></DIV -><DIV -CLASS="SECTION" -><H1 -CLASS="SECTION" -><A -NAME="AEN775" ->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 ->entry <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="x761.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="x809.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="c661.html" -ACCESSKEY="U" ->Up</A -></TD -><TD -WIDTH="33%" -ALIGN="right" -VALIGN="top" ->Format Specific Linking Notes</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/x776.html Mon Aug 29 19:15:50 2011 -0600 @@ -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="c662.html"><LINK +REL="PREVIOUS" +TITLE="Linker Operation" +HREF="x762.html"><LINK +REL="NEXT" +TITLE="Format Specific Linking Notes" +HREF="x810.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="x762.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="x810.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN776" +>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 +>entry <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="x762.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="x810.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="c662.html" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Format Specific Linking Notes</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file
--- a/docs/manual/x809.html Mon Aug 29 19:05:18 2011 -0600 +++ /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="c661.html"><LINK -REL="PREVIOUS" -TITLE="Linking Scripts" -HREF="x775.html"><LINK -REL="NEXT" -TITLE="Libraries and LWAR" -HREF="c824.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="x775.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="c824.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -></TABLE -><HR -ALIGN="LEFT" -WIDTH="100%"></DIV -><DIV -CLASS="SECTION" -><H1 -CLASS="SECTION" -><A -NAME="AEN809" ->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="AEN812" ->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="x775.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="c824.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="c661.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/x810.html Mon Aug 29 19:15:50 2011 -0600 @@ -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="c662.html"><LINK +REL="PREVIOUS" +TITLE="Linking Scripts" +HREF="x776.html"><LINK +REL="NEXT" +TITLE="Libraries and LWAR" +HREF="c825.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="x776.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="c825.html" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="AEN810" +>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="AEN813" +>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="x776.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="c825.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="c662.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