| ld-layout-file(1) | General Commands Manual | ld-layout-file(1) |
ld-layout-file —
ld Layout file format documentation
ld can specify a file that describes specifications and constraints about the layout of the binary to be emitted. This file is specified at link time with the -layout_file option to ld(1) The file is using a JSON5 file format, where the different keys and values are described below. The main purpose of the description is to have a set of constraints defined by the user depending on the hardware they are trying to target, and make sure that the emitted binary properly conforms to it.
A region is a high level abstract memory description of what is needed for a specific hardware, with addresses and bounds. A region contains segments, which themselves can contain one or multiple sections.
The root node of the file contains the following attribute:
This specifies an array of regions, where each entry is a dictionary that represents a region. Every region entry must specify the following attribute:
The name of the region.
The type of region. The "kind" "dictionary must define the following attributes:
The name of the type of the kind of region. The string can have
any of the following values:
"default" : a regular region, with inputs, symbols, etc.
"empty" : an empty region, were the file backed segment is zeroed.
"raw" : TODO: a region containing the contents of a file on
disk.
The permissions of the region. The string has a value that is
combination of the following characters:
'r' : read
'w' : write
'x' : execute
'-' : no access
Every region entry must specify one of the two following mutually exclusive attributes:
The virtual start address for the region.
The name of the region after which the region should start.
Region entries may specify the following attributes:
The maximum memory size of the region.
The name of the underlying text segment. The default value for the segment follows the format "REGION_T", where "REGION" is the name of the region. The name of the segment can have a most 16 characters.
The name of the underlying data segment. The default value for the segment follows the format "REGION_D", where "REGION" is the name of the region. The name of the segment can have a most 16 characters.
If the permissions of the region are "rwx", the region can specify a single unified underlying segment. The attribute's' usage is mutually exclusive with "textSeg" and "dataSeg", and cannot be used with the "default" region.
Regions of type "default" must specify this attribute. It represents the set of symbols that should be placed in that region by the linker. The entries will be evaluated in the order in which they are declared in the layout file. The linker will try to fill the region in order of priority in which the inputs are listed. So it will first try to add symbols that satisfies all the constraints of the first entry, then try with those for which the second entry is true, and so on. If a symbol satisfies constraints in multiple regions, it will be placed in the region that has the lowest address. This specifies an array of inputs, where each entry must specify the following attribute:
Each entry of the array is a string that represents the name of the symbol to be moved to the region. The name attribute can support some wildcards.
The input section where to find the symbols to be moved to the region. The "sections" dictionary must define the following two attributes:
The name of the section segment. The string can support some wildcards.
The name of the section. The string can support some wildcards.
Input entries may specify the following attribute:
The name of the region where to move the remaining inputs, when the contents of the region exceeds its memory size.
The layout supports a default region, where all symbols will be moved to by default, and which should always be defined in the file. Any symbol or input that is not explicitly specified to be in a custom region will end up inside that default region. The default value for the text segment in the default region is "__TEXT". The default value for the data segment in the default region is "__DATA".
The layout file must specify an entry point for the executable being emitted. The root node of the file contains the following attribute:
The dictionary must define the following attribute:
The name of the symbol to be used as the entry point.
The layout file must specify a version number.
The latest version number of the layout file format is 0.
.Sh ZERO-FILL The layout file might specify custom behaviour for the
zero-fill sections in the executable. The root node of the file contains the
following attribute:
The dictionary might define the following attribute:
The name of the section that all zero-fill sections will be merged into.
.Sh LOGGING The layout file might specify a boolean entry, so that the linker
log how the inputs are assigned. It will print the elements, why they were
assigned to a region, and all the regions that were attempted before
that.
The default value is false.
{
version : 0,
regions : [
{
name : "ROM",
kind : { type : "default", permissions : "r-x" },
vmAddress : 0x2000,
vmSize : 0x4000,
textSeg : "ROMCODE",
inputs : [
{
section : { segName : "__TEXT", sectName : "*" },
symbols : [ "_entry", "_bar*", "_foo" ],
spill : "LAST"
}
]
},
{
name : "LAST",
kind : { type : "default", permissions : "r-x" },
previous : "SINGLE",
vmSize : 0x2000,
inputs : [
{
section : { segName : "__TEXT", sectName : "*" },
symbols : [ "*" ]
}
]
},
{
name : "RAM",
kind : { type : "default", permissions : "rw-" },
vmAddress : 0x8000,
dataSeg : "RAMDATA",
inputs : [
{
section : { segName : "*", sectName : "__data" },
symbols : [ "*" ]
}
]
},
{
name : "SINGLE",
kind : { type : "default", permissions : "rwx" },
previous : "RAM",
vmSize : 0x1000,
segment : "CUSTOMSEG",
inputs : [
{
section : { segName : "__TEXT", sectName : "*" },
symbols : [ "*" ]
}
]
},
{
name : "default",
kind : { type : "default", permissions : "rwx" },
previous : "LAST",
inputs : [
{
section : { segName : "*", sectName : "*" },
symbols : [ "*" ]
}
]
}
],
entry : { name : "_entry" }
}
| November 20, 2024 | Darwin |