Mercurial > hg > index.cgi
diff docs/manual/x827.html @ 333:507f442dc71e
Add support for 6800 compatibility instructions.
The occasional program uses the 6800 compatibility instructions since they
are actually specified by Motorola in at least some documentation. They
advertised the 6809 as source compatible with the 6800.
This mode is not enabled by default, however. It is my belief that receiving
an error when using a non-6809 instruction is more useful since it is
unlikely that much 6800 source code is being assembled for the 6809 these
days. Nevertheless, the --6809compat option is present for just those
purposes so one does not have to resort to using macros (which would work
equally well in most cases).
| author | William Astle <lost@l-w.ca> |
|---|---|
| date | Tue, 15 Apr 2014 10:57:34 -0600 |
| parents | b30091890d62 |
| children |
line wrap: on
line diff
--- a/docs/manual/x827.html Mon Apr 14 07:43:43 2014 -0600 +++ b/docs/manual/x827.html Tue Apr 15 10:57:34 2014 -0600 @@ -2,7 +2,7 @@ <HTML ><HEAD ><TITLE ->Linking Scripts</TITLE +>Linker Operation</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK @@ -11,13 +11,13 @@ HREF="index.html"><LINK REL="UP" TITLE="LWLINK" -HREF="c713.html"><LINK +HREF="c727.html"><LINK REL="PREVIOUS" -TITLE="Linker Operation" -HREF="x813.html"><LINK +TITLE="LWLINK" +HREF="c727.html"><LINK REL="NEXT" -TITLE="Format Specific Linking Notes" -HREF="x893.html"></HEAD +TITLE="Linking Scripts" +HREF="x841.html"></HEAD ><BODY CLASS="SECTION" BGCOLOR="#FFFFFF" @@ -45,7 +45,7 @@ ALIGN="left" VALIGN="bottom" ><A -HREF="x813.html" +HREF="c727.html" ACCESSKEY="P" >Prev</A ></TD @@ -59,7 +59,7 @@ ALIGN="right" VALIGN="bottom" ><A -HREF="x893.html" +HREF="x841.html" ACCESSKEY="N" >Next</A ></TD @@ -74,203 +74,55 @@ CLASS="SECTION" ><A NAME="AEN827" ->4.3. Linking Scripts</A +>4.2. Linker Operation</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 +> 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 -><DIV -CLASS="VARIABLELIST" -><DL -><DT ->sectopt <CODE -CLASS="PARAMETER" ->section</CODE -> padafter <CODE -CLASS="PARAMETER" ->byte,...</CODE -></DT -><DD -><P -> This will cause the linker to append the specified list of byte values -(specified in hexadecimal separated by commas) to the end of the named -section. This is done once all instances of the specified section are -collected together. This has no effect if the specified section does not -appear anywhere in any of the objects specified for linking. </P -><P -> If code depends on the presence of this padding somewhere, it is sufficient -to include an empty section of the specified name in the object that depends -on it. </P -></DD -><DT ->define basesympat <CODE -CLASS="PARAMETER" ->string</CODE -></DT -><DD -><P -> This causes the linker to define a symbol for the ultimate base address of -each section using the pattern specified by <CODE -CLASS="PARAMETER" ->string</CODE ->. -In the string, %s can appear exactly once and will be replaced with the -section name. The base address is calculated after all instances of each -section have been collapsed together. </P +><OL +TYPE="1" +><LI ><P -> It should be noted that if none of the objects to be linked contains a -particular section name, there will be no base symbol defined for it, even -if it is listed explicitly in the link script. If code depends on the -presence of these symbols, it is sufficient to include an empty section of -the specified name in the object that depends on it. </P -><P -> If the pattern resolves to the same string for multiple -sections, the results are undefined. </P -></DD -><DT ->define lensympat <CODE -CLASS="PARAMETER" ->string</CODE -></DT -><DD +>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 -> This causes the linker to define a symbol for the ultimate length of each -section using the pattern specified by <CODE -CLASS="PARAMETER" ->string</CODE ->. In -the string, %s can appear exactly once and will be replaced with the section -name. The length is calculated after all instances of a section have been -collapsed together. </P -><P -> It should be noted that if none of the objects to be linked contains a -particular section name, there will be no length symbol defined for it, even -if it is listed explicitly in the link script. If code depends on the -presence of these symbols, it is sufficient to include an empty section of -the specified name in the object that depends on it. </P -><P ->If the pattern resolves to the same string for multiple -sections, the results are undefined. </P -></DD -><DT ->section <CODE -CLASS="PARAMETER" ->name</CODE -> load <CODE -CLASS="PARAMETER" ->addr</CODE -></DT -><DD +>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 -> 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 -> high <CODE -CLASS="PARAMETER" ->addr</CODE -></DT -><DD -><P -> This causes the section <CODE -CLASS="PARAMETER" ->name</CODE -> to load with its end -address just below <CODE -CLASS="PARAMETER" ->addr</CODE ->. Subsequent sections are -loaded at progressively lower addresses. This may lead to inefficient file -encoding for some targets. As of this writing, it will also almost -certainly do the wrong thing for a raw target. </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 -> This is useful for aligning a block of code with high memory. As an -example, if the total size of a section is $100 bytes and a high address of -$FE00 is specified, the section will actually load at $FD00. </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 +>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 ->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 +>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" @@ -288,7 +140,7 @@ ALIGN="left" VALIGN="top" ><A -HREF="x813.html" +HREF="c727.html" ACCESSKEY="P" >Prev</A ></TD @@ -306,7 +158,7 @@ ALIGN="right" VALIGN="top" ><A -HREF="x893.html" +HREF="x841.html" ACCESSKEY="N" >Next</A ></TD @@ -316,13 +168,13 @@ WIDTH="33%" ALIGN="left" VALIGN="top" ->Linker Operation</TD +>LWLINK</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A -HREF="c713.html" +HREF="c727.html" ACCESSKEY="U" >Up</A ></TD @@ -330,7 +182,7 @@ WIDTH="33%" ALIGN="right" VALIGN="top" ->Format Specific Linking Notes</TD +>Linking Scripts</TD ></TR ></TABLE ></DIV