LWLINK

LW Tool Chain
Prev		Next

LW Tool Chain
Prev		Next

LW Tool Chain
Prev		Next

LW Tool Chain
Prev		Next

LW Tool Chain
Prev

TERMTYPE	Meaning
00	end of expression
01	integer (16 bit in big endian order follows)
02	external symbol reference (NUL terminated symbol name follows)
03	local symbol reference (NUL terminated symbol name follows)
04	operator (1 byte operator number)
05	section base address reference
FF	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).

Number	Operator
01	addition (+)
02	subtraction (-)
03	multiplication (*)
04	division (/)
05	modulus (%)
06	integer division (\) (same as division)
07	bitwise and
08	bitwise or
09	bitwise xor
0A	boolean and
0B	boolean or
0C	unary negation, 2's complement (-)
0D	unary 1's complement (^)

LW Tool Chain
Prev

TERMTYPE	Meaning
00	end of expression
01	integer (16 bit in big endian order follows)
02	external symbol reference (NUL terminated symbol name follows)
03	local symbol reference (NUL terminated symbol name follows)
04	operator (1 byte operator number)
05	section base address reference
FF	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).

Number	Operator
01	addition (+)
02	subtraction (-)
03	multiplication (*)
04	division (/)
05	modulus (%)
06	integer division (\) (same as division)
07	bitwise and
08	bitwise or
09	bitwise xor
0A	boolean and
0B	boolean or
0C	unary negation, 2's complement (-)
0D	unary 1's complement (^)

There is a single flag supported in

flags. The
-flag bss 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.

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

can be used to override this assumption.

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.

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.

3.10. Assembler Modes and Pragmas

Chapter 4. LWLINK

4.1. Command Line Options

4.2. Linker Operation

4.3. Linking Scripts

4.4. Format Specific Linking Notes

4.4.1. OS9 Modules

Chapter 5. Libraries and LWAR

5.1. Command Line Options

LWASM supports generating a proprietary object file format which is described in Chapter 6. LWLINK is then used to link these object files into a final binary in any of LWLINK's supported binary diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x520.html --- 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">Next may only be specified on the first instance of the section.
There is a single flag supported in flags. The -flag bss 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.
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. 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.
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 can be used to override this assumption.
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.
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.
Next -Assembler Modes and Pragmas
LW Tool Chain
Prev Chapter 3. LWASM Next
3.10. Assembler Modes and Pragmas
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.
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.
PRAGMA pragma[,...]
Specifies that the assembler should bring into force all pragmas -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.
*PRAGMA pragma[,...]
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.
*PRAGMAPUSH pragma[,...]
This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.
This directive will not throw any errors for any reason.
*PRAGMAPOP pragma[,...]
This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.
This directive will not throw any errors for any reason.
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.
Pragmas are not case sensitive.
index0tonone
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.
cescapes
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.
importundefexport
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.
undefextern
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.
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.)
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.
dollarlocal
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.
dollarnotlocal
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.
pcaspcr
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.
shadow
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.
nolist
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.
autobranchlength
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.
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.
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.
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.
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.
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.
Prev Home Next
Object Files and Sections Up LWLINK
\ No newline at end of file diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x584.html --- /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 @@ + +Assembler Modes and Pragmas
LW Tool Chain
Prev Chapter 3. LWASM Next
3.10. Assembler Modes and Pragmas
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.
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.
PRAGMA pragma[,...]
Specifies that the assembler should bring into force all pragmas +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.
*PRAGMA pragma[,...]
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.
*PRAGMAPUSH pragma[,...]
This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.
This directive will not throw any errors for any reason.
*PRAGMAPOP pragma[,...]
This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.
This directive will not throw any errors for any reason.
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.
Pragmas are not case sensitive.
index0tonone
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.
cescapes
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.
importundefexport
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.
undefextern
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.
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.)
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.
dollarlocal
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.
dollarnotlocal
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.
pcaspcr
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.
shadow
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.
nolist
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.
autobranchlength
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.
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.
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.
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.
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.
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.
Prev Home Next
Object Files and Sections Up LWLINK
\ No newline at end of file diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x761.html --- 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 @@ - -Linker Operation
LW Tool Chain
Prev Chapter 4. LWLINK Next
4.2. Linker Operation
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.
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.
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.
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.
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.
If all of the above steps are successful, the linker opens the output file -and actually constructs the binary.
Prev Home Next
LWLINK Up Linking Scripts
\ No newline at end of file diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x762.html --- /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 @@ + +Linker Operation
LW Tool Chain
Prev Chapter 4. LWLINK Next
4.2. Linker Operation
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.
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.
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.
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.
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.
If all of the above steps are successful, the linker opens the output file +and actually constructs the binary.
Prev Home Next
LWLINK Up Linking Scripts
\ No newline at end of file diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x775.html --- 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 @@ - -Linking Scripts
LW Tool Chain
Prev Chapter 4. LWLINK Next
4.3. Linking Scripts
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.
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.
All numbers are in linking scripts are specified in hexadecimal. All directives -are case sensitive although the hexadecimal numbers are not.
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.
The following directives are understood in a linker script.
section name load addr
This causes the section name to load at -addr. 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.
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.
section name
This will cause the section name to load after the previously listed -section.
entry addr or sym
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.
pad size
This will cause the output file to be padded with NUL bytes to be exactly -size bytes in length. This only makes sense for a raw target.
Prev Home Next
Linker Operation Up Format Specific Linking Notes
\ No newline at end of file diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x776.html --- /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 @@ + +Linking Scripts
LW Tool Chain
Prev Chapter 4. LWLINK Next
4.3. Linking Scripts
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.
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.
All numbers are in linking scripts are specified in hexadecimal. All directives +are case sensitive although the hexadecimal numbers are not.
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.
The following directives are understood in a linker script.
section name load addr
This causes the section name to load at +addr. 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.
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.
section name
This will cause the section name to load after the previously listed +section.
entry addr or sym
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.
pad size
This will cause the output file to be padded with NUL bytes to be exactly +size bytes in length. This only makes sense for a raw target.
Prev Home Next
Linker Operation Up Format Specific Linking Notes
\ No newline at end of file diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x809.html --- 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 @@ - -Format Specific Linking Notes
LW Tool Chain
Prev Chapter 4. LWLINK Next
4.4. Format Specific Linking Notes
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.
4.4.1. OS9 Modules
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.
The data size is calcuated as the sum of all sections named "bss" or -".bss" in all object files that are linked together.
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.
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.
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.
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.
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.
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.
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.
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.
Prev Home Next
Linking Scripts Up Libraries and LWAR
\ No newline at end of file diff -r 872fa82680e1 -r 1e0a0e6cd918 docs/manual/x810.html --- /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 @@ + +Format Specific Linking Notes
LW Tool Chain
Prev Chapter 4. LWLINK Next
4.4. Format Specific Linking Notes
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.
4.4.1. OS9 Modules
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.
The data size is calcuated as the sum of all sections named "bss" or +".bss" in all object files that are linked together.
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.
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.
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.
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.
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.
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.
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.
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.
Prev Home Next
Linking Scripts Up Libraries and LWAR
\ No newline at end of file

Chapter 4. LWLINK

4.1. Command Line Options

Chapter 4. LWLINK

4.1. Command Line Options

Chapter 5. Libraries and LWAR

5.1. Command Line Options

Chapter 5. Libraries and LWAR

5.1. Command Line Options

Chapter 6. Object Files

Chapter 6. Object Files

3.10. Assembler Modes and Pragmas

Chapter 4. LWLINK

4.1. Command Line Options

4.2. Linker Operation

4.3. Linking Scripts

4.4. Format Specific Linking Notes

4.4.1. OS9 Modules

Chapter 5. Libraries and LWAR

5.1. Command Line Options

3.10. Assembler Modes and Pragmas

3.10. Assembler Modes and Pragmas

4.2. Linker Operation

4.2. Linker Operation

4.3. Linking Scripts

4.3. Linking Scripts

4.4. Format Specific Linking Notes

4.4.1. OS9 Modules

4.4. Format Specific Linking Notes

4.4.1. OS9 Modules