Linker

The linker module implements the various tasks of linking. This includes:

  • Symbol resolution
  • Applying relocations
  • Section merging
  • Layout of section into memory
  • Linker relaxation

Module reference

Linker utility.

class ppci.binutils.linker.Linker(arch, reporter=None)

Merges the sections of several object files and performs relocation

add_missing_symbols_from_libraries(libraries)

Try to fetch extra code from libraries to resolve symbols.

Note that this can be a rabbit hole, since libraries can have undefined symbols as well.

check_undefined_symbols()

Find undefined symbols.

do_relaxations()

Linker relaxation. Just relax ;).

Linker relaxation is the process of finding shorted opcodes for jumps to addresses nearby.

For example, an instruction set might define two jump operations. One with a 32 bits offset, and one with an 8 bits offset. Most likely the compiler will generate conservative code, so always 32 bits branches. During the relaxation phase, the code is scanned for possible replacements of the 32 bits jump by an 8 bit jump.

Possible issues that might occur during this phase:

  • alignment of code. Code that was previously aligned might be shifted.
  • Linker relaxations might cause the opposite effect on jumps whose distance increases due to relaxation. This occurs when jumping over a memory whole between sections.
do_relocations()

Perform the correct relocation as listed

get_symbol_value(symbol_id)

Get value of a symbol from object or fallback

get_undefined_symbols()

Get a list of currently undefined symbols.

inject_object(obj, debug)

Paste object into destination object.

inject_symbol(name, binding, section, value, typ, size)

Generate new symbol into object file.

layout_sections(layout)

Use the given layout to place sections into memories

Link together the given object files using the layout

merge_global_symbol(name, section, value, typ, size)

Insert or merge a global name.

merge_objects(input_objects, debug)

Merge object files into a single object file

After linking is complete, this function can be used to dump information to a reporter.

Links the iterable of objects into one using the given layout.

Parameters:
  • objects – a collection of objects to be linked together.
  • layout – optional memory layout.
  • use_runtime (bool) – also link compiler runtime functions
  • partial_link – Set this to true if you want to perform a partial link. This means, undefined symbols are no error.
  • debug (bool) – when true, keep debug information. Otherwise remove this debug information from the result.
  • extra_symbols – a dict of extra symbols which can be used during linking.
  • libraries – a list of libraries to use when searching for symbols.
  • entry – the entry symbol where execution should begin.
Returns:

The linked object file

 
>>> import io
>>> from ppci.api import asm, c3c, link
>>> asm_source = io.StringIO("db 0x77")
>>> obj1 = asm(asm_source, 'arm')
>>> c3_source = io.StringIO("module main; var int a;")
>>> obj2 = c3c([c3_source], [], 'arm')
>>> obj = link([obj1, obj2])
>>> print(obj)
CodeObject of 8 bytes