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.

For a general reference to ld-style linker scripts, see the ld manual.

For LLD's extensions and interpretations of ld's behavior, see LLD's linker script implementations notes and policy.

This page describes LLVM-MOS's extensions to 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).

Byte commands output the value of the given expression as little-endian bytes of the size corresponding to the command used. They have the same syntax and semantics as those which occur in output section descriptions.

• A memory region command: FULL(mem-region, [start, [length]]), TRIM(mem-region, [start, [length]]).

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 an 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 optional start argument allows specifying the starting position, in bytes, of the output section's data to be emitted. Note that this argument is relative to the beginning of the region, and not an absolute LMA.

The optional length argument allows specifying the maximum number of bytes to be output as part of this memory region command. Note that if the section has fewer than length bytes remaining, the output won't be padded, but rather fewer bytes will be written.

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.