Welcome to AVR32 Linux... Users Groups

LibBfd: The Binary File Descriptor library

This page aims to describe the internal implementation of the AVR32 ELF BFD backend. This is very much a work in progress, but some of the most important stuff is documented, so it may still be useful.

Table of Contents


The AVR32 ELF backend consists mainly of two files:

  • cpu-avr32.c: Very basic architecture description.
  • elf32-avr32.c: All the ugly low-level hooks necessary to link AVR32 ELF objects. Also contains some code related to parsing of object files and core files.

There are a few other files that had to be modified in order to make libbfd aware of the AVR32 architecture. Most of it is pure boilerplate, with one notable exception: reloc.c. This file contains definitions of the AVR32 RelocationTypes.

Since ELF is the only supported object file format on AVR32, this documentation will focus on the ELF linking code, in particular how the low-level ELF hooks are implemented on AVR32. The AVR32 ELF backend interfaces with the generic ELF code in libbfd, which in turn interfaces with the generic libbfd code.

Interface to the BFD ELF core

The actual interface between the generic ELF code and the AVR32 ELF backend is located at the very end of elf32-avr32.c as a set of macro definitions. After all the necessary macros have been defined, the file elf32-target.h is included, hooking everything up to the internal ELF backend structure. elf32-target.h is generated from elfxx-target.h by substituting "32" for all occurrences of "NN".

A short walkthrough of all the AVR32-specific backend definitions follows. Note that elf32-target.h provides reasonable defaults for all macros that haven't been defined by the backend.

Defined as bfd_arch_avr32. This has to custom writing paper correspond with the definitions used in archures.c and cpu-avr32.c
Magic number used to identify ELF files for AVR32. This is EM_AVR32, which is defined by include/elf/common.h to be 0x18ad.
Maximum page size supported by the target. Defined as 4096 bytes, which is not strictly true since the AVR32 supports page sizes up to 1MiB. At the moment, however, only 4K pages are supported for userspace programs.
Big endian target vector. This has to correspond with the definitions in config.bfd and targets.c.
Name of the big endian target. This can be used in the linker script to select this particular target, although this isn't all that useful on AVR32 since only one target is defined.
Hook for parsing process status information in core dump files.
Hook for parsing the elf_prpsinfo structure in core dump files.
0 because AVR32 does not use REL relocations (without addend.)
1 because AVR32 does use RELA relocations (with addend.)
1 because RELA is the default relocation type (duh.)
Not quite sure what this is.
NULL because REL relocations aren't being used. I think this hook is only used on targets that use both REL and RELA.
Look up a "relocation howto" structure based on an ELF relocation type. A "relocation howto" is a common internal representation of a relocation which all architectures are forced to use whether they like it or not.
Copy backend-specific data from one object module to another. This is necessary to preserve architecture-specific fields and flags when object files are copied.
Merge backend-specific data from one object module into another. This is used when several object-files are combined into one output (i.e. linking), so this hook needs to consider both the flags in the input and the flags that have already been set in the output. When this has been called for all inputs, the resulting set of flags in the output should be compatible with all inputs. For AVR32, this specifically means that EF_AVR32_PIC should only be set if all input files had this flags set. The same applies to EF_AVR32_LINKRELAX.
Set the given target-specific flags in the given object file.
Display the target-specific flags that are set in a given object file.
This hook is called whenever a new section is created. The AVR32 ELF backend uses this to allocate a private per-section data structure, struct avr32_section_data used during relaxing.
Return the section referenced by a given relocation.
Called when a section is being removed. Go through all relocations in this section and update the internal state to reflect the fact that these relocations are no longer there. This includes decrementing the reference count of all GOT entries referenced by these relocations.
Relocate a section. This involves fixing up the raw binary data in the section to reference the symbol the relocation refers to directly. In dynamically linked executables and shared libraries, not all relocations can be resolved completely; this function will insert dynamic relocations (a small subset of the available relocations) for all such unresolved references so that they can be fixed up at runtime by the dynamic linker.
Called when an indirect symbol is replaced by a direct symbol. Make sure that the direct symbol reflects the state associated with the indirect symbol.
Create any dynamic (i.e. linker-created) sections that may be needed during the link. This includes the .got (Global Offset Table), .stub (function stubs for lazy binding) and .rela.got (dynamic relocations for the .got section) sections as well as the _GLOBAL_OFFSET_TABLE_ symbol.
Create a link hash table. This allocates space for any AVR32-specific information in addition to the generic ELF link hash table.
Called for all symbols that can't be resolved directly, i.e. they're either not defined in the output binary at all or they are only defined weakly (and can thus be overridden by a shared library at runtime.)
Determine the size of all linker-generated sections and allocate memory for them.
Finalize a dynamic symbol. This involves initializing a GOT entry for it and emitting dynamic relocations as necessary.
Finalize all dynamic sections. This involves initializing the .dynamic section with various pieces of information for the dynamic linker.
Go through all relocations in a section and try to replace them with smaller ones. This is called multiple times for each section, until no sections can be optimized further.
Initial pass over all sections to see if any special treatment is required. This can be dynamic section creation, dynamic relocations, got entries, etc. An initial reference count of all GOT entries is also made, and the highest refcount is recorded for use when allocating memory for the GOT sorting algorithm later on.
Used to do strange voodoo magic in elf.c. Defined to 1 because we can indeed refcount the GOT entries.
Defined to 1 because --gc-sections is supported.
Defined to 1 since the PLT (which is not really used, but would have contained code if it was) should be read-only.
Defined to 1.
0. We don't want a PLT symbol (sheesh)
2. Whatever.
0. We don't need a dynamic .bss section.
0. We don't want a .got to go with the .plt which we don't want either.
Yes, we do want the _GLOBAL_OFFSET_TABLE_ symbol to be defined (although it seems like we have to define it ourselves anyway.)
The number of bytes at the start of the GOT before the actual GOT entries begin. On AVR32, this is 8 (i.e. two "entries".)

Data Structures

struct got_entry

This structure represents one entry in the Global Offset Table and consists of the following members:

Pointer to the next entry in the list of entries with the same refcount.
Pointer to the previous entry's next pointer in the list of entries with the same refcount.
Number of references to this GOT entry. This is initially calculated by avr32_check_relocs and subsequently updated by the relaxation code and the GC code as relocations are converted or removed completely.
This entry's current offset into the Global Offset Table. The offset will change during relaxation as relocations are re-sorted according to their refcount, removed or reinstated.

Note that traditionally, each GOT entry is represented by a union of refcount and offset. Since the AVR32 linker does aggressive optimization of the GOT, it needs to keep more state around and therefore uses the third member of the union: the glist pointer. The BFD core tends to mess up this pointer from time to time by assigning either 0 or -1 to it, but this has been worked around by careful initialization of the init_{got,plt}_{refcount,offset} members in the link hash table.

All got_entry objects are kept in a pigeonhole array where they are moved around as their reference count changes. When the .got section is relaxed, new offsets are assigned based on their position in the array: The ones with most references are assigned the lowest offsets. This is because large offsets may cause large instructions or even multiple instructions to be emitted when referencing them, so this strategy ensures that as many instructions as possible are kept small.

struct elf_avr32_link_hash_entry

This structure represents a global symbol in the link hash table. Global symbols, as opposed to local ones, are referenced by name and must therefore be kept in a hash table for easy lookup as the linker comes across references to them. Global symbols also require a bit extra care to be taken when dealing with them; they may be defined in a shared library, they may be overridden and they may require dynamic relocations to be emitted for references to them.

This structure consists of the following members:

The generic ELF link hash entry that we are extending.
Number of non-GOT references to this symbol, as determined by the avr32_check_relocs hook. How many of these references will actually require dynamic relocations to be emitted is not known until later since it depends on whether or not the symbol can be fully resolved.
If non-zero, something other than a plain function call was found referring to this symbol. This means that lazy binding can not be used.
If non-NULL, a reference to this symbol which may possibly require a dynamic relocation was found in a read-only section, in which case this member contains a pointer to the section where the first such reference was found. If it later turns out that this symbol is indeed dynamic, the link fails and this member as well as the next is used to print an informative error message.
Offset into readonly_reloc_sec where the first possibly-illegal (see above) reference to the symbol was found. Used to make the error message more informative.
The fragment (if any) where this symbol is located. This is used to keep track of any movements of this symbol during relaxing. When the final size of all relocations have been determined, the symbol value is updated according to how much the associated fragment moved.

struct elf_avr32_link_hash_table

This structure contains the link hash table of global symbols as well as pretty much anything that is considered global to the link as a whole. It consists of the following members:

The generic ELF link hash table that we are extending.
Shortcut pointer to the section containing the GOT.
Shortcut pointer to the section containing dynamic relocations for the GOT section.
Shortcut pointer to the section containing function stubs for lazy binding.
Pointer to the pigeonhole array used to sort the GOT. The storage for this array is allocated by avr32_elf_size_dynamic_sections.
The number of entries in the got_hole array.
Number of possibly-dynamic relocations to local symbols. When linking shared libraries with -Bsymbolic or normal executables, references to local symbols are never dynamic, so this member is only used when linking a shared library without -Bsymbolic.
Before any relaxing can be done, the linker must make a pass over all relocations to analyze them and divide the sections into fragments. If this member is set, this pass has been done.
If set, all symbols have had their value adjusted according to frag movement. This is done all in one go after the size of all relocations is known but before the section contents are actually moved.
If set, at least one relocation or the GOT changed size, so another iteration needs to be done before moving on to the next stage.
How many complete relax iterations over all sections have been done so far.
Current relax pass (or rather, relax stage.) The relax code first does one or more iterations of the "size" pass and then does one "move" pass to update symbols, relocations and section contents.

struct relax_state

During relaxing, each relaxable relocation moves between different relax states. This structure describes one such state: The opcode and relocation type it corresponds to, the range of values that can be represented by the immediate, how large the result is and which state changes are allowed.

Each relax state is classified according to its reference type, which can be one of the following:

Absolute reference. The symbol value is encoded directly into the immediate. The mov instruction is an example of an instruction taking an absolute reference.
PC-relative reference. The distance from the reference to the symbol is encoded into the immediate. The sub and rcall instructions are examples of instructions taking relative references.
Constant pool indirect reference. The symbol value is entered into the constant pool and loaded into the target register using a lddpc or ld.w instruction or called using the mcall instruction. Such references are not position-independent, so they can usually not be used in shared libraries.
GOT indirect reference. The symbol value is entered into the Global Offset Table and loaded into the target register using a ld.w instruction or called using the mcall instruction. This must be used for references to run-time external symbols. When linking shared libraries without -Bsymbolic, all references to global symbols must use REF_GOT.
r2 - 2010-03-10 - 09:26:20 - KevinLabster
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
Atmel®, AVR® and others are registered trademarks or trademarks of Atmel Corporation or its subsidiaries.
All other trademarks are the property of their respective owners.
Syndicate this site RSSATOM