Storing Build Time Information In ELF Binary Files
In a Format Suitable for Static Analysis
A specification by Nick Clifton. Version 3.0. Dec 20, 2017.
ChangeLog:
For v3.0:
Add end-of-range addresses to description field, to allow
for gaps in the coverage.
For v2.0:
Added an "owner" string at the start of the name field so that
naive processors of Elf Notes are less likely to complain.
----------------------------------------------------------------------
* The information is stored in a new section in the file using the ELF
NOTE format. This format is already well defined, and supported by
binary tools.
Creator tools (compilers, assemblers) place the notes into the
binary files. Consumer tools (readelf, built-by) read the notes and
answer questions about the binaries concerned. Processing tools
(linker, objcopy) combine and merge the notes as needed.
Note - this specification could have used the gnu_attributes format
instead, but this has a few drawbacks:
- Support for section and symbol tagged gnu_attributes is not
currently implemented anywhere, and these features are needed.
Adding support for them to the binutils would mean that the
specification is not backwards compatible with older tools.
* The gnu attributes specification requires that when merging
attributes from multiple input files the tool performing the merge
must create new, section-relative attributes where conflicts
occur. Similarly conflicts between section-relative attributes
must be resolved by the creation of new symbol-relative
attributes. Adding support for this requirement would have again
introduced a barrier to backwards compatiblity, and would also
result in the attribute section being larger than an equivalent
section using this proposal.
* The information is stored in a new section called .gnu.build.attributes.
(The name can be changed - it is basically irrelevant anyway, it is
the new section flag (defined below) that matters).
The section has the type SHT_NOTE.
The section has a new flag set: SHF_GNU_BUILD_ATTRIBUTES
(suggested value: 0x00100000).
The sh_link and sh_info fields of this section should be set to 0.
The sh_align field should be set to 4, even on 64-bit systems.
This does mean that 8-byte values inside the notes might have to be
relocated using unaligned relocs, and that they might have to be
read and written using unaligned loads and stores.
* The type field of a note is used to distinguish the range of memory
over which an attribute applies. The name field identifies the
attribute and gives it a value. The description field specifies the
starting and ending addresses for where the attribute is applied.
Two new note types are defined: NT_GNU_BUILD_ATTRIBUTE_OPEN (0x100)
and NT_GNU_BUILD_ATTRIBUTE_FUNC (0x101). These are used by the
description field (see below).
The description field of the note is either 0-bytes long, or else a
pair of 4-byte wide (for 32-bit targets) or 8-byte wide (for 64-bit
targets) addresses which indicate the starting and ending location
for the attribute.
If the description field is empty, the note should be treated as if
it applies to the same region as the nearest preceeding note of the
same type (ie either OPEN or FUNC).
In unrelocated files the addresses should instead be zero, with a
relocation present to set the actual value once the file is linked.
The numbers are stored in the same endian format as that specified
in the EI_DATA field of the ELF header of the file containing the
note. The size of the numbers is dictated by the EI_CLASS field of
the ELF header.
The name field identifies the type and value of the attribute.
The name starts with the string "GA", which is an abbreviation for
GNU Attribute. The abbreviation is used in order to save space.
The string is there so that tools that do not know about these notes
will still be able to parse the note structure.
The character following the identifier string indicates the kind of
attribute, based upon the following table:
* - The attribute takes a numeric value. Numbers are stored in
little endian binary format.
$ - The attribute takes a string value.
! - The attribute takes a boolean value, and the value is false.
+ - The attribute takes a boolean value, and the value is true.
The next character indicates the specific attribute:
Character Allowed Meaning
--------------- Types -------
0 <none> Reserved for future use.
1 $ Version of the specification supported and producer(s) of the notes (see below).
2 * Stack protector
3 !+ Relro
4 * Stack size
5 $ Build tool & version
6 $* ABI
7 * Position Independence Status: 0 => static, 1 => pic, 2 => PIC, 3 => pie
8 !+ Short enums
9..31 <none> Reserved for future use.
32..126 $*!+ An annotation type not explicitly defined by this specification.
127+ <none> Reserved for future use.
For * and $ type attributes the value is then appended.
Per the ELF note spec the name must end with a NUL byte.
Some examples:
GA*foo\0\001\0\002\0 Attribute 'foo' with numeric value 0x20001
GA*bar\00\0 Attribute 'bar' with numeric value 0
GA$fred\0hello\0 Attribute 'fred' with string value "hello"
GA*4\377\377\0 Attribute stack size with numeric value 0xffff
GA*21\0 Atrribute -fstack-protector.
GA*24\0 Atrribute -fstack-protector-explicit.
GA$\0013p5\0 Supports spec version 3, created by plugin version 5.
GA$5gcc v7.0\0 Attribute build tool "gcc v7.0"
Multiple notes for the same attribute can exist, providing that they
have different values and that their description address ranges do
not overlap. The exception to this rule is that
NT_GNU_BUILD_ATTRIBUTE_FUNC attributes are allowed to overlap
NT_GNU_BUILD_ATTRIBUTE_OPEN attributes.
The first note should be a version note. The version note string
should consist of an odd number of characters. The first character
is the ascii code for the number of the version of this protocol
supported by the notes. The next pair of characters indicate who
produced the notes and which version of this producer has been
used. A 'p' character indicates a compiler plugin. An 'l'
character indicates the linker. An 'a' character indicates the
assembler. Other characters may be defined in the future. Multiple
producers can contribute to the notes. Their identifying pair of
characters should be appended to the version note.
The description field for the version note should not be empty.
This note serves as the base address for other open notes that
follow, allowing them to use an empty description field.
* When the linker merges two or more files containing these notes it
should ensure that the above rules are maintained. Simply
concatenating the incoming note sections should ensure this.
The linker can, if it wishes, create its own notes and append, or
insert them into the note section. Eg to indicate that -z relro is
enabled.
The order of the notes from an incoming section must be preserved in
the outgoing section. Notes do not have to be sorted by address
range although this often happens automatically when sections are
concatenated.
If this is a final link, then relocations on the notes should of
course be resolved.
The linker, or another tool, may wish to eliminate redundant notes
in the note section. When doing this the following rules must be
observed:
0. [Optional] If relocations exist against the notes then
they should not be merged.
1. Preserve the ordering of the notes.
2. Preserve any NT_GNU_BUILD_ATTRIBUTE_FUNC notes.
3. Eliminate any NT_GNU_BUILD_ATTRIBUTE_OPEN notes that have
the same full name field as the immediately preceeding
note with the same type of name and whoes address ranges
coincide.
4. Combine the numeric value of any NT_GNU_BUILD_ATTRIBUTE_OPEN
notes of type GNU_BUILD_ATTRIBUTE_STACK_SIZE.
5. If an NT_GNU_BUILD_ATTRIBUTE_OPEN note is going to be
preserved and its description field is empty then the
nearest preceeding OPEN note with a non-empty
description field must also be preserved *OR* the
description field of the note must be changed to
contain the starting address to which it refers.
* Note - this specification is intended for storing information for
use by static tools. There is another, similar specification for
storing information for use by run-time tools, specifically the
dynamic loader. This specifcation also uses the ELF Note format,
but it is intended to be a lot smaller, only storing information
essential to the loader, and a lot faster to process.
ToDo:
Check if -grecord-gcc-switches preserved per-translation-unit info
after linking.
Handle -ffunction-sections.