A representation of a value within some binary data that has to be fixed up once the exact position of certain symbols within memory is known. More...

#include <relocation.h>

Public Member Functions
	Relocation (bool segment_of, size_t size, Location source, Target target, Target reference, uint64_t addend, EndianType endiantype)

Relocation &	SetMask (uint64_t new_mask)
	Instead of the full word, only modify the following bits.

Relocation &	SetShift (int new_shift)
	The value stored in the word must be shifted by this to give the actual value.

Relocation &	SetSubtract (bool to_subtract=true)
	The value stored in the word must be negated before adding the addend and storing.

bool	Displace (const Displacement &displacement)
	Recalculates the source, target and reference locations after a section has moved.

bool	Resolve (Module &object, Resolution &resolution)
	If the target and reference symbols can be resolved, return the value with some additional information about the segments.

uint64_t	ReadUnsigned ()
	Accesses the value within the section data.

int64_t	ReadSigned ()
	Accesses the value within the section data.

void	WriteWord (uint64_t value)
	Accesses the value within the section data.

void	AddCurrentValue ()
	Updates the addend with the value stored in the section data.

bool	IsRelative () const
	Determines if a relocation is self-relative.

Static Public Member Functions
static Relocation	Empty ()
	Creates an empty relocation.

static Relocation	Absolute (size_t size, Location source, Target target, uint64_t addend, EndianType endiantype)
	Creates a relocation referencing the absolute address of a target.

static Relocation	Absolute (size_t size, Location source, Target target, uint64_t addend=0)
	Creates a relocation referencing the absolute address of a target.

static Relocation	Offset (size_t size, Location source, Target target, uint64_t addend, EndianType endiantype)
	Creates a relocation that references the offset of a target within its preferred segment (Intel 8086 specific)

static Relocation	Offset (size_t size, Location source, Target target, uint64_t addend=0)
	Creates a relocation that references the offset of a target within its preferred segment (Intel 8086 specific)

static Relocation	OffsetFrom (size_t size, Location source, Target target, Target reference, uint64_t addend, EndianType endiantype)
	Creates a relocation that references the offset of a target from a specific reference point.

static Relocation	OffsetFrom (size_t size, Location source, Target target, Target reference, uint64_t addend=0)
	Creates a relocation that references the offset of a target from a specific reference point.

static Relocation	Relative (size_t size, Location source, Target target, uint64_t addend, EndianType endiantype)
	Creates a relocation that references the offset of a target from the source.

static Relocation	Relative (size_t size, Location source, Target target, uint64_t addend=0)
	Creates a relocation that references the offset of a target from the source.

static Relocation	Paragraph (Location source, Target target, uint64_t addend=0)
	Creates a relocation that stores the 16-bit paragraph (shifted right by 4) of the target (Intel 8086 specific)

static Relocation	Selector (Location source, Target target, uint64_t addend=0)
	Creates a relocation that stores the 16-bit paragraph (shifted right by 4) of the target (Intel 8086 specific)

static Relocation	Segment (size_t size, Location source, Target target, uint64_t addend=0)
	Creates a relocation that stores the 8-bit segment number of the target (Zilog Z8000 specific)

static Relocation	ParagraphDifference (Location source, Target target, Target reference, uint64_t addend=0)
	Creates a relocation that stores the 16-bit paragraph difference (shifted right by 4) between the target and the reference (Intel 8086 specific)

Public Attributes
bool	segment_of
	Set when the value to be stored is the segment selector instead of the segment start (Intel 8086 specific)

size_t	size
	The size of the value when stored at the source, in bytes (for example, 2 for 16-bit, 4 for 32-bit)

Location	source
	The location where the value of the symbol should be stored.

Target	target
	The symbol or location referenced by the relocation.

Target	reference
	The symbol or location whose value is subtracted from the final value, used for self-relative and segment-relative addresses.

uint64_t	addend
	A value to be added.

EndianType	endiantype
	The endianness of the stored value.

int	shift
	The amount of bits the value should be shifted by.

uint64_t	mask
	The bitmask of the value within the word.

bool	subtract
	Set to true if value must be negated first.

Detailed Description

A representation of a value within some binary data that has to be fixed up once the exact position of certain symbols within memory is known.

One of the tasks of a linker is to associate symbols in different object files and replace references to them with their values. These references to outside symbols are called relocations or fix-ups. When a linker is unable to resolve a relocation that has to be deferred to run time, such relocations must be stored in the resulting executable file. Different executable file formats have differring levels of support for relocations.

Since RetroLinker supports many very different targets, the Relocation class is designed to be as general as possible. At its most basic, a relocation must store the symbol referenced, the reference, and the location where it is to be stored, the source. The Relocation class also stores the size in bytes of the value expected, a value that needs to be added to the resolved value, and the endianness of the stored value. Relative values can also be represented, which are often used for relative branches. To support Intel 8086 segmentation, the value of the segment selector corresponding to the segment of a symbol may also be used, and resolutions can be made with respect to another reference, usually the start of a segment.

Member Function Documentation

◆ AddCurrentValue()

void Relocation::AddCurrentValue ( )

Updates the addend with the value stored in the section data.

Some object formats do not store the addend in the relocation data. Instead, the value is expected to be added to the value already present in the binary image. We use this function to load the addend from the image data.

◆ Empty()

Relocation Relocation::Empty ( )

static

Creates an empty relocation.

This is used only as a default initializor. The generated relocation references an absolute location, and it is not expected to be resolved.

◆ IsRelative()

bool Relocation::IsRelative ( ) const

Determines if a relocation is self-relative.

The Relocation class represents self-relative relocations using the reference field. For some output formats, it is important to tell whether a relocation is self-relative.

◆ ParagraphDifference()

Relocation Relocation::ParagraphDifference	(	Location	source,
		Target	target,
		Target	reference,
		uint64_t	addend = 0 )

static

Creates a relocation that stores the 16-bit paragraph difference (shifted right by 4) between the target and the reference (Intel 8086 specific)

This relocation is needed on platforms with no segment relocations to set up the segments as part of an initializing routine by adding the offset between segments to the initial value of one of the segment registers. For example, ELKS needs it.

Member Data Documentation

◆ segment_of

bool Linker::Relocation::segment_of

Set when the value to be stored is the segment selector instead of the segment start (Intel 8086 specific)

For real mode targets, this is the value shifted 4 to the right. Protected mode targets might use a more involved method of storing the value.

The documentation for this class was generated from the following files:

src/linker/relocation.h
src/linker/relocation.cc

Public Member Functions

Static Public Member Functions

Public Attributes