2.10.2 The howto manager

When an application wants to create a relocation, but doesn't
know what the target machine might call it, it can find out by
using this bit of code.

2.10.2.1 bfd_reloc_code_type

Description
The insides of a reloc code. The idea is that, eventually, there
will be one enumerator for every type of relocation we ever do.
Pass one of these values to bfd_reloc_type_lookup, and it'll
return a howto pointer.

This does mean that the application must determine the correct
enumerator value; you can't get a howto pointer from a random set
of attributes.

PC-relative relocations. Sometimes these are relative to the address
of the relocation itself; sometimes they are relative to the start of
the section containing the relocation. It depends on the specific target.

These PC-relative relocations are stored as word displacements –
i.e., byte displacements shifted right two bits. The 30-bit word
displacement (<<32_PCREL_S2>> – 32 bits, shifted 2) is used on the
SPARC. (SPARC tools generally refer to this as <<WDISP30>>.) The
signed 16-bit displacement is used on the MIPS, and the 23-bit
displacement is used on the Alpha.

— : BFD_RELOC_HI22
— : BFD_RELOC_LO10

High 22 bits and low 10 bits of 32-bit value, placed into lower bits of
the target word. These are used on the SPARC.

— : BFD_RELOC_GPREL16
— : BFD_RELOC_GPREL32

For systems that allocate a Global Pointer register, these are
displacements off that register. These relocation types are
handled specially, because the value the register will have is
decided relatively late.

Alpha ECOFF and ELF relocations. Some of these treat the symbol or
"addend" in some special way.
For GPDISP_HI16 ("gpdisp") relocations, the symbol is ignored when
writing; when reading, it will be the absolute section symbol. The
addend is the displacement in bytes of the "lda" instruction from
the "ldah" instruction (which is at the address of this reloc).

— : BFD_RELOC_ALPHA_GPDISP_LO16

For GPDISP_LO16 ("ignore") relocations, the symbol is handled as
with GPDISP_HI16 relocs. The addend is ignored when writing the
relocations out, and is filled in with the file's GP value on
reading, for convenience.

— : BFD_RELOC_ALPHA_GPDISP

The ELF GPDISP relocation is exactly the same as the GPDISP_HI16
relocation except that there is no accompanying GPDISP_LO16
relocation.

The Alpha LITERAL/LITUSE relocs are produced by a symbol reference;
the assembler turns it into a LDQ instruction to load the address of
the symbol, and then fills in a register in the real instruction.

The LITERAL reloc, at the LDQ instruction, refers to the .lita
section symbol. The addend is ignored when writing, but is filled
in with the file's GP value on reading, for convenience, as with the
GPDISP_LO16 reloc.

The ELF_LITERAL reloc is somewhere between 16_GOTOFF and GPDISP_LO16.
It should refer to the symbol to be referenced, as with 16_GOTOFF,
but it generates output not based on the position within the .got
section, but relative to the GP value chosen for the file during the
final link stage.

The LITUSE reloc, on the instruction using the loaded address, gives
information to the linker that it might be able to use to optimize
away some literal section references. The symbol is ignored (read
as the absolute section symbol), and the "addend" indicates the type
of instruction using the register:
1 - "memory" fmt insn
2 - byte-manipulation (byte offset reg)
3 - jsr (target of branch)

— : BFD_RELOC_ALPHA_HINT

The HINT relocation indicates a value that should be filled into the
"hint" field of a jmp/jsr/ret instruction, for possible branch-
prediction logic which may be provided on some processors.

— : BFD_RELOC_ALPHA_LINKAGE

The LINKAGE relocation outputs a linkage pair in the object file,
which is filled by the linker.

— : BFD_RELOC_ALPHA_CODEADDR

The CODEADDR relocation outputs a STO_CA in the object file,
which is filled by the linker.

— : BFD_RELOC_ALPHA_GPREL_HI16
— : BFD_RELOC_ALPHA_GPREL_LO16

The GPREL_HI/LO relocations together form a 32-bit offset from the
GP register.

— : BFD_RELOC_ALPHA_BRSGP

Like BFD_RELOC_23_PCREL_S2, except that the source and target must
share a common GP, and the target address is adjusted for
STO_ALPHA_STD_GPLOAD.

High 16 bits of 32-bit value but the low 16 bits will be sign
extended and added to form the final result. If the low 16
bits form a negative number, we need to add one to the high value
to compensate for the borrow when the low bits are added.

— : BFD_RELOC_LO16

Low 16 bits.

— : BFD_RELOC_HI16_PCREL

High 16 bits of 32-bit pc-relative value

— : BFD_RELOC_HI16_S_PCREL

High 16 bits of 32-bit pc-relative value, adjusted

— : BFD_RELOC_LO16_PCREL

Low 16 bits of pc-relative value

— : BFD_RELOC_MIPS16_GOT16
— : BFD_RELOC_MIPS16_CALL16

Equivalent of BFD_RELOC_MIPS_*, but with the MIPS16 layout of
16-bit immediate fields

— : BFD_RELOC_MIPS16_HI16

MIPS16 high 16 bits of 32-bit value.

— : BFD_RELOC_MIPS16_HI16_S

MIPS16 high 16 bits of 32-bit value but the low 16 bits will be sign
extended and added to form the final result. If the low 16
bits form a negative number, we need to add one to the high value
to compensate for the borrow when the low bits are added.

Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches.
The lowest bit must be zero and is not stored in the instruction.
Note that the corresponding ELF R_ARM_THM_JUMPnn constant has an
"nn" one smaller in all cases. Note further that BRANCH23
corresponds to R_ARM_THM_CALL.

— : BFD_RELOC_ARM_OFFSET_IMM

12-bit immediate offset, used in ARM-format ldr and str instructions.

— : BFD_RELOC_ARM_THUMB_OFFSET

5-bit immediate offset, used in Thumb-format ldr and str instructions.

— : BFD_RELOC_ARM_TARGET1

Pc-relative or absolute relocation depending on target. Used for
entries in .init_array sections.

— : BFD_RELOC_ARM_ROSEGREL32

Read-only segment base relative address.

— : BFD_RELOC_ARM_SBREL32

Data segment base relative address.

— : BFD_RELOC_ARM_TARGET2

This reloc is used for references to RTTI data from exception handling
tables. The actual definition depends on the target. It may be a
pc-relative or some form of GOT-indirect relocation.

This is a 16 bit reloc for the AVR that stores negated 8 bit value
(high 8 bit of data memory address) into 8 bit immediate value of
SUBI insn.

— : BFD_RELOC_AVR_HH8_LDI_NEG

This is a 16 bit reloc for the AVR that stores negated 8 bit value
(most high 8 bit of program memory address) into 8 bit immediate value
of LDI or SUBI insn.

— : BFD_RELOC_AVR_MS8_LDI_NEG

This is a 16 bit reloc for the AVR that stores negated 8 bit value (msb
of 32 bit value) into 8 bit immediate value of LDI insn.

— : BFD_RELOC_AVR_LO8_LDI_PM

This is a 16 bit reloc for the AVR that stores 8 bit value (usually
command address) into 8 bit immediate value of LDI insn.

— : BFD_RELOC_AVR_LO8_LDI_GS

This is a 16 bit reloc for the AVR that stores 8 bit value
(command address) into 8 bit immediate value of LDI insn. If the address
is beyond the 128k boundary, the linker inserts a jump stub for this reloc
in the lower 128k.

— : BFD_RELOC_AVR_HI8_LDI_PM

This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit
of command address) into 8 bit immediate value of LDI insn.

— : BFD_RELOC_AVR_HI8_LDI_GS

This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit
of command address) into 8 bit immediate value of LDI insn. If the address
is beyond the 128k boundary, the linker inserts a jump stub for this reloc
below 128k.

— : BFD_RELOC_AVR_HH8_LDI_PM

This is a 16 bit reloc for the AVR that stores 8 bit value (most high 8 bit
of command address) into 8 bit immediate value of LDI insn.

— : BFD_RELOC_AVR_LO8_LDI_PM_NEG

This is a 16 bit reloc for the AVR that stores negated 8 bit value
(usually command address) into 8 bit immediate value of SUBI insn.

These two relocations are used by the linker to determine which of
the entries in a C++ virtual function table are actually used. When
the –gc-sections option is given, the linker will zero out the entries
that are not used, so that the code for those functions need not be
included in the output.

VTABLE_INHERIT is a zero-space relocation used to describe to the
linker the inheritance tree of a C++ virtual function table. The
relocation's symbol should be the parent class' vtable, and the
relocation should be located at the child vtable.

VTABLE_ENTRY is a zero-space relocation that describes the use of a
virtual function table entry. The reloc's symbol should refer to the
table of the class mentioned in the code. Off of that base, an offset
describes the entry that is being used. For Rela hosts, this offset
is stored in the reloc's addend. For Rel hosts, we are forced to put
this offset in the reloc's section offset.

Motorola 68HC11 reloc.
This is the 8 bit high part of an absolute address.

— : BFD_RELOC_M68HC11_LO8

Motorola 68HC11 reloc.
This is the 8 bit low part of an absolute address.

— : BFD_RELOC_M68HC11_3B

Motorola 68HC11 reloc.
This is the 3 bit of a value.

— : BFD_RELOC_M68HC11_RL_JUMP

Motorola 68HC11 reloc.
This reloc marks the beginning of a jump/call instruction.
It is used for linker relaxation to correctly identify beginning
of instruction and change some branches to use PC-relative
addressing mode.

— : BFD_RELOC_M68HC11_RL_GROUP

Motorola 68HC11 reloc.
This reloc marks a group of several instructions that gcc generates
and for which the linker relaxation pass can modify and/or remove
some of them.

— : BFD_RELOC_M68HC11_LO16

Motorola 68HC11 reloc.
This is the 16-bit lower part of an address. It is used for 'call'
instruction to specify the symbol address without any special
transformation (due to memory bank window).

— : BFD_RELOC_M68HC11_PAGE

Motorola 68HC11 reloc.
This is a 8-bit reloc that specifies the page number of an address.
It is used by 'call' instruction to specify the page number of
the symbol.

— : BFD_RELOC_M68HC11_24

Motorola 68HC11 reloc.
This is a 24-bit reloc that represents the address with a 16-bit
value and a 8-bit page number. The symbol address is transformed
to follow the 16K memory bank of 68HC12 (seen as mapped in the window).

Xtensa relocations to mark the difference of two local symbols.
These are only needed to support linker relaxation and can be ignored
when not relaxing. The field is set to the value of the difference
assuming no relaxation. The relocation encodes the position of the
first symbol so the linker can determine whether to adjust the field
value.

Generic Xtensa relocations for instruction operands. Only the slot
number is encoded in the relocation. The relocation applies to the
last PC-relative immediate operand, or if there are no PC-relative
immediates, to the last immediate operand.