Linker Script

The LLVM-MOS linker script format is an extension of the LLD linker script format, which is itself an extension of the GNU ld linker script format.

See the ld manual for a general reference to ld-style linker scripts.

See LLD's linker script implementations notes and policy for LLD's extensions and interpretations of ld's behavior.

This page describes LLVM-MOS's extensions of LLD's behavior.

Custom Output Formats

LLVM-MOS provides an extension to the OUTPUT_FORMAT syntax to allow specifying the precise bytes produced in the output file generated by the linker. This subsumes and extends the functionality provided by ld/LLD's OUTPUT_FORMAT(binary).

The format of the extension is:

OUTPUT_FORMAT
{
  output-format-command
  output-format-command
  ...
}

The command form a script that outputs bytes to the output file, from top to bottom. When this section is present, the usual output file contains these bytes, but an additional file is created with the .elf file extension containing the ELF file.

Each output-format-command can be:

• A byte command: BYTE(expr), SHORT(expr), LONG(expr), QUAD(expr)
• A memory region command: FULL(mem-region), TRIM(mem-region)

Byte commands have the same syntax and semantics as those occurring in output section decriptions; they output the values of the given expressions as little-endian bytes of the corresponding size.

Memory region commands output the loaded contents of the named memory region, as described in MEMORY { } . The contents of the region are the contents of all output sections with LMA (load address) anywhere within the region. The relative locations of each byte are determined by their LMAs. Note that output sections doesn't need to be explictly assigned to the memory region with > or AT> to be included; it just needs to have at least one byte with an LMA that overlaps with the region. Any unreferenced sections of the memory region are filled with zeros.

FULL causes the full output section to be emitted, from its origin through its full length. TRIM causes any trailing unreferenced bytes to be trimmed from the region before it's emitted. The last output byte corresponds to the highest LMA in any output section that overlaps with the region. The purpose of this extension is to allow defining custom file formats without adding code to the linker or llvm-objcopy. The byte commands can be used to construct header bytes based on the final locations of various symbols, and the load addresses can be chosen in such a fashion to provide a unique namespace for each byte that should be included in a binary image to be used by a 6502 target platform. See the SDK for examples of how this can be used.