ELSPEC(5)ELSPEC(5)NAMEELSPEC - ELF Layout specification
TOPIC
This manpage describes the ELF Layout Specification language implemented
by ld(1) which allows users to exactly specify layout of object files,
programs, and shared objects.
INTRODUCTION
It is often desirable to specify the exact layout of an executable file.
Some of the uses of this might be embedded systems, thread-local data
layout, reducing cache conflicts, reducing false sharing, reducing memory
utilization. The current linker allows exact specification of layout via
the ELF Layout Specification language.
Invoking Layout Specification
An elspec file is specified to the linker using
cc -Wl,-elspec,<filename> ...
or
ld -elspec <filename> ...
You may get a sample elspec file for the default link using:
cc -Wl,-elsmap ...
or
ld -elsmap ...
Basic Building Blocks
The basic units that the linker manipulates are called input sections.
Each object file may have several of these, with familiar names such as
`.text', `.data', `.bss', and so on. The correctness of compiled code
may depend on the exact layout of a section, but never depends on the
relative layout between sections. For that reason, the linker will never
rearrange or change the contents of any individual input section in any
way.
The one exception to this are COMMON variables, for which space is
allocated by the linker, and as such, are not allocated to any input
section. These can be manipulated freely, but not split into pieces by
ELF Layout Specification. You get a COMMON variable by using a FORTRAN
COMMON, or from C data variables declared at file scope in files which
have been compiled with either -cckr or -common.
Segments
Input sections are linked together more or less contiguously into output
sections. Output sections are organized in and ELF file into loadable
segments which are specified in the program header. See elf(5). Segments
Page 1
ELSPEC(5)ELSPEC(5)
represent a contiguous portion of the file which is to be loaded into
memory as-is, with possibly the addition of extra memory at the end.
Placement Rules
ELF Layout Specification works by allowing the user to specify the
placement of input sections within output sections, and the output
sections within segments. In order to avoid requiring the user to
specify every input file, we give rules for the default placement of an
input section in an output section and the placement of output sections
within segments.
A section from an input file will be placed in the output file according
to these rules:
1. If the section (and object and archive) are mentioned explicitly,
place it there.
2. If there is a section specified in the map with the same name,
which has "default" as one of its contents, and which has matching
attributes, place it there. The input section will maintain
its layout position relative to other listed contents. If there
is more than one default-placed input section, they will be
allocated space in the order encountered. If the attributes of the
input section do not match those specified in the map, it is an error.
3. If there is a segment specified in the map with matching attributes
which has specified "default" as one of its contents,
the input section will be placed in an output section with the same
name and attributes. The input section will maintain
its layout position relative to other listed contents. If there
is more than one default-placed input section, they will be
allocated space in the order encountered. If the attributes of the
input section do not match those specified in the map or those of
another default input section, it is an error.
4. If an input object is listed as a segment content
without mention of specific input sections, all sections with
appropriate attributes are merged by name and laid out in the order
encountered.
5. File layout will be managed by the linker in any fashion it sees
fit. We can provide a flag -ignorevce to allow tighter packing.
6. Specifying "headers" as contents of a segment allows (but does not
require) the inclusion of headers such as the ELF header and the
program header into that segment. Specifying "default" has this
effect as well. Specifying "noheaders" will forbid the inclusion
of headers into that segment
7. Loader-generated sections will be placed in to a segment with matching
attributes which has specified "ldgen" as its segment contents.
Page 2
ELSPEC(5)ELSPEC(5)
Specific loader-generated sections may be placed by using $ldobj as
the object name. When a non-optional loader-generated section has
no place to be loaded, an error is generated, unless the global switch
"$ignoreldgen" has the value "true".
8. Should user-specified alignment result in R4000 alignment problems,
ld will report these to the user, and produce output anyway. If
"$r4kbugfix" is set to false (or -allow_jump_at_eop specfied on the
linkline), no checking will be performed.
9. In general, command line options take precedence over
specifications here.
10.Overlaps in virtual space or physical space will be reported
unless at least one of the segment descriptions has specified an
overlap with the other, or unless "$ignoreoverlaps" is true.
11.The name, type, and flags of an output section uniquely determines
that section. Specifying more than one such section in the file
will yield unpredictable results.
12.Sections with flags SHF_ALLOC and SHF_READ but not SHF_WRITE, will be
placed in the first segment which has PF_R but not PF_W set.
SYNTAX
This section describes the actual syntax of an ELSPEC file. There are
some examples at the end.
Overview
There are three main parts to the layout specification (lspec) file. In
order expected, they are: a list of global variable settings, a list of
symbols attribute specifications, and a list of segment specifications.
<layoutspec> ::= <globals> <symlist> <seglist>;
Segments
Segments are the basic runtime building blocks. They are necessarily
contiguous, both in memory and in the file. They have a uniform set of
protections associated.
<segdef> ::= beginseg <segname> <segattr>
<segspecial> contents <segcontents> endseg;
<segname> ::= /* empty */ | name <idstring>;
<segattr> ::= /* empty */
| <segattr> segtype <segtype>
| <segattr> vaddr <address>
| <segattr> paddr <address>
| <segattr> segflags <segflags>
Page 3
ELSPEC(5)ELSPEC(5)
| <segattr> segalign <number>
;
<segtype> ::= noload /* include in output segment */
| <number>
| LOAD /* this is the default */
| REL
;
<segflags> ::= /* empty, default settings are RWX */
| <segflags> R /* Set the PF_R flag */
| <segflags> W /* Set the PF_W flag */
| <segflags> X /* Set the PF_X flag */
| <segflags> L;/* Set the PF_MIPS_LOCAL flag */
For programs under the IRIX 5.3 and above, segments with the
PF_MIPS_LOCAL flag set will be thread-local and not shared in the event
of an sproc(2) system call. For other applications, the meaning of this
bit is undefined.
Segment contents
Contents of a segment are usually in the form of output sections. These
section are further specified to contain input sections (see below), and
are laid out in the order specified. The default is to build upwards in
virtual address space.
Specifying "default" as segment contents allows the linker to place input
sections with compatible attributes which are not otherwise mentioned in
the current segment. This is accomplished by creating a distinct output
sections for each unique set of section type, flags, and section name,
and placing it in the "best" segment which has specified "default" as one
of its segment contents.
<segcontents> ::= /* empty */
| <segcontents> <outsection>
| <segcontents> noheaders
| <segcontents> default;
Output sections
Output sections are a convenient way to group material within a segment.
For example, we may wish to have read-only data and program text in the
same segment, but within that segment we want to have all the read-only
data together and all the text together. We define two output sections
named ".rdata" and ".text" and place them both within a single segment.
<outsection> ::= beginscn <idstring> <scnattr> <scnspecial>
<scncontents> endscn
| beginscn <idstring> relfor <idstring> endscn
| beginscn <idstring> relafor <idstring> endscn
;
Page 4
ELSPEC(5)ELSPEC(5)
<scnattr> ::= /* empty string */
| <scnattr> scntype <scntype>
| <scnattr> scnflags <scnflags>
| <scnattr> scnsize <size>
| <scnattr> link <number>
| <scnattr> info <number
| <scnattr> scnalign <number>
| <scnattr> entsize <number>
;
<scntype> ::= PROGBITS | NOTE | NOBITS | <number>;
<scnflags> ::= <scnflaglist> | <number> | none;
<scnflaglist> ::= /* empty */
| <scngflaglist> WRITE
| <scnflaglist> ALLOC
| <scnflaglist> EXECINSTR
| <scnflaglist> GPREL
| <scnflaglist> MERGE
| <scnflaglist> ADDR
| <scnflaglist> NOSTRIP
| <scnflaglist> LOCAL;
Layout specification for relocatable ("-r") links is supported. Unlike
other types of output sections, the contents of relocation sections
cannot be freely specified. Rather, the contents of a given "relfor"
section are determined relative to some other output section. For
example, the section specified by
beginscn .rel.mytext relfor .mytext endscn
contains all the Rel-type relocations for the output section named
".mytext". Relocation sections can be given any name, but the relocation
must be preceded by the section the relocations are relative to.
Input sections
Input sections are the basic building blocks which the linker
manipulates. Each object file read by the linker may contain several of
these input section. The lspec file works by specifying the arrangement
of these input sections. Input sections may be specified in two basic
ways. The user may attempt to specify the section directly, or may
specify an external symbol name, which has the effect of specifying the
section in which that symbol definition resides.
<scncontents> ::= /* Nothing */
| <scncontents> default
| <scncontents> <inputscn>
| <scncontents> <symspec>;
In the rule below, the <idstring> specifies the name of the input
section. If no name is specified, all sections from the mentioned object
with matching attributes are selected.
Page 5
ELSPEC(5)ELSPEC(5)
Sometimes it may occur that the attributes of an input section are not
compatible with those of the enclosing output section. Below you see
different input section specifications categorized as either specific or
generic. If a specific mention conflicts with default output section
attributes, the output section attributes are promoted to be compatible.
If a specific mention conflicts with user-specified output section
attributes, the input section is included with a warning, but the output
section attributes are not altered. If a generic mention conflicts with
output section attributes, the input section is not included in the
output section, regardless of whether the output sections attributes were
user-specified or not.
<inputscn> ::= sec <idstring> /* specific mention */
| sec <idstring> in <object> /* specific mention */
| <object>; /* generic mention */
<object> ::= obj[ect] <idstring> ( <idstring> )
/* archive(filename) */
| obj[ect] <idstring>
| ar[chive] <idstring>
| ldobj;
/* for specifying loader-defined sections */
<symspec> ::= sym <idstring> in <inputscn>
| sym <idstring>;
ELSpec Variables
Various ELF layout Specification (ELSpec) variables can be given values.
These values will be used by the linker when laying out your program.
<globals> ::= /* NULL */ | globals set_global;
<set_global ::= <gsize> = <size>
| <gbool> = <boolean>;
<gsize> ::= $blocksize
| $cachesize
| $pagesize
| $cachelinesize;
<gbool> ::= $ignoreldgen
| $r4kbugfix
| $ignoreoverlaps;
Segment Special attributes
These allow users to specify special attributes of a segment.
Specifying "ascending" means that the components will be laid out in
order of increasing address, beginning at the specified (or default)
address. This is the default behavior.
Page 6
ELSPEC(5)ELSPEC(5)
Specifying "overlap <idstring>" denotes that the normal linker checking
for overlaps in virtual address are not to be performed between the
current segment and the segment named by <idstring>. This is to
facilitate overlay links.
<segspecial> ::= /* empty */
| <segspecial> ascending
| <segspecial> overlap <idstring>;
Base Data Types
Here is the syntax for numbers, booleans, strings and so on.
<size> ::= <number> | <number> K | <number> M
<address> ::= <number>
<number> ::= 0x[0-9a-f]+ /* Hex number */
| 0[0-7]+ /* Octal number */
| [0-9]+ /* decimal number */
<boolean> ::= true | false;
<idstring> ::= [a-zA-Z0-9$_.]+
| "<any string>";
Comments
If the character '#' appears in a layout specification (except when with
in a string specified with ""), the remainder of the line, including the
'#' will be treated as a comment and ignored.
EXAMPLES
Default link spec
#
# This is the default link spec. Using it should give the
# same result as not using -elspec
#
beginseg
name text
segtype LOAD
vaddr 0x10000000
segflags R X
segalign 0x10000
contents default
endseg
beginseg
name data
segtype LOAD
segflags R W X
segalign 0x1000
contents default
endseg
beginseg
Page 7
ELSPEC(5)ELSPEC(5)
name noload
segtype noload
contents default
endseg
Aligning a COMMON symbol
#
# This link spec will give the COMMON symbol a_ an alignment of 128
# bytes. This can be useful to prevent false sharing, among other
# things.
#
beginseg
segtype LOAD
segflags R X
# vaddr 0x10000000
segalign 0x1000
contents default
endseg
beginseg
segtype LOAD
segflags R W
# vaddr 0x10011000
segalign 0x1000
contents default
beginscn .mybss
scntype NOBITS
scnflags ALLOC WRITE
scnalign 0x80
sym a_
endscn
endseg
SEE ALSOld(1), elf(5), elfdump(5)UPDATES
This manpage is updated periodically, the last update was on 3/1/95 for
IRIX 6.0.2
Page 8
