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 padafter byte,...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.
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.
string
This causes the linker to define a symbol for the ultimate base address of
each section using the pattern specified by string.
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.
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.
If the pattern resolves to the same string for multiple sections, the results are undefined.
string
This causes the linker to define a symbol for the ultimate length of each
section using the pattern specified by string. 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.
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.
If the pattern resolves to the same string for multiple sections, the results are undefined.
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.
name high addr
This causes the section name to load with its end
address just below addr. 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.
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.
name
This will cause the section name to load after the previously listed
section.
addr or symThis 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.
Note that if you use a numeric value here, you will need to ensure it starts with a digit. That may mean adding a leading zero.
sizeThis 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.