symbol_assignments.md

Symbols assignments

A "symbol assignment" entry describes extra symbol assignments to define on the generated linker script.

These are usually used for defining "undefined symbols", but this system also allows for more complex expressions.

Symbols defined in this way do not have a corresponding elf section assigned to them, in other words they look like *ABS* symbols on the linked elf.

Every attribute listed is optional unless explicitly stated.

Table of contents

• Symbols assignments
  • Table of contents
  • name
    • Example
    • Valid values
  • value
    • Example
    • Valid values
  • provide
    • Valid values
    • Default value
  • hidden
    • Valid values
    • Default value
  • include_if_any, include_if_all, exclude_if_any and exclude_if_all

name

This field is required.

The name of the corresponding symbol to be declared.

Example

symbol_assignments:
  - name: osMemSize
    value: 0x80000318

Valid values

Non empty string.

TODO: Impose rules for valid names?

value

This field is required.

The value or expression to assign to this symbol.

Usually raw addresses are used as values for a given symbol, but more complex expressions are allowed too. See the GNU LD documentation for Expressions in Linker Scripts for documentation on what is allowed on those expressions.

Example

symbol_assignments:
  - name: _gp
    value: boot_SCOMMON_START + 0x7FF0

Valid values

Non empty string.

provide

If provide is enabled for an entry then this symbol assignment will only be applied if the given symbol is referenced but is not defined in any object included in the link.

See GNU LD documentation for PROVIDE.

This option can be combined with hidden. For more info see the GNU LD documentation for PROVIDE_HIDDEN.

Valid values

Bool.

Default value

False

hidden

Defines the symbol but hides it, so it won't be exported.

On a more technical sense, the binding of the generated symbol on the elf will be marked as LOCAL instead of GLOBAL.

See GNU LD documentation for HIDDEN.

This option can be combined with provide. For more info see the GNU LD documentation for PROVIDE_HIDDEN.

Valid values

Bool.

Default value

False

include_if_any, include_if_all, exclude_if_any and exclude_if_all

These fields allow to conditionally include or exclude a given segment depending on the current custom options.

Their syntax is the same as their file counterparts.