RTEMS: cpukit/include/rtems/rtl/rtl-unresolved.h File Reference

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
rtl-unresolved.h File Reference
API » RTEMS Runtime Link Editor

RTEMS Run-Time Linker Object File Unresolved Relocations Table. More...

`#include <rtems.h>`
`#include <rtems/chain.h>`
`#include "rtl-obj-fwd.h"`

Go to the source code of this file.

## Data Structures
struct | rtems_rtl_unresolv_symbol
struct | rtems_rtl_unresolv_reloc
struct | rtems_rtl_tramp_reloc
struct | rtems_rtl_unresolv_rec
struct | rtems_rtl_unresolv_block
struct | rtems_rtl_unresolved

## Macros
#define | RTEMS_RTL_UNRESOLV_SYM_SEARCH_ARCHIVE (1 << 0)
#define | RTEMS_RTL_UNRESOLV_SYM_HAS_ERROR (1 << 1)

## Typedefs
typedef uint32_t | rtems_rtl_word
typedef enum rtems_rtl_unresolved_rtype | rtems_rtl_unresolved_rtype
typedef struct rtems_rtl_unresolv_symbol | rtems_rtl_unresolv_symbol
typedef struct rtems_rtl_unresolv_reloc | rtems_rtl_unresolv_reloc
typedef struct rtems_rtl_tramp_reloc | rtems_rtl_tramp_reloc
typedef struct rtems_rtl_unresolv_rec | rtems_rtl_unresolv_rec
typedef struct rtems_rtl_unresolv_block | rtems_rtl_unresolv_block
typedef struct rtems_rtl_unresolved | rtems_rtl_unresolved
typedef bool | rtems_rtl_unresolved_iterator(rtems_rtl_unresolv_rec *rec, void *data)

## Enumerations
enum | rtems_rtl_unresolved_rtype { rtems_rtl_unresolved_empty = 0 , rtems_rtl_unresolved_symbol = 1 , rtems_rtl_unresolved_reloc = 2 , rtems_rtl_trampoline_reloc = 3 }

## Functions
bool | rtems_rtl_unresolved_table_open (rtems_rtl_unresolved *unresolved, size_t block_records)
void | rtems_rtl_unresolved_table_close (rtems_rtl_unresolved *unresolved)
bool | rtems_rtl_unresolved_iterate (rtems_rtl_unresolved_iterator iterator, void *data)
bool | rtems_rtl_unresolved_add (rtems_rtl_obj *obj, const uint16_t flags, const char *name, const uint16_t sect, const rtems_rtl_word *rel)
void | rtems_rtl_unresolved_resolve (void)
bool | rtems_rtl_unresolved_remove (rtems_rtl_obj *obj, const char *name, const uint16_t sect, const rtems_rtl_word *rel)
void | rtems_rtl_unresolved_set_archive_search (void)
void | rtems_rtl_unresolved_dump (void)

## Detailed Description

RTEMS Run-Time Linker Object File Unresolved Relocations Table.

The unresolved relocation table holds relocations in a loaded object file which reference unresolved external symbols. The support is needed to allow dependent object files to load. In the case of dependent object files one will have unresolved externals until the dependent object file is also loaded. There is no load order that resolves this.

The unresolved relocation table is a single table used by all object files with unresolved symbols. It made of blocks linked together where blocks are allocated as requiered. The table is always maintained compacted. That is as relocations are resolved and removed the table is compacted. The only pointer in the table is the object file poniter. This is used to identify which object the relocation belongs to. There are no linking or back pointers in the unresolved relocations table. The table is scanned for each object file's relocations. This is not fast but the table should be small and if it happens to grow large you have other more pressing issues to resolve in your application.

The table holds two (2) types of records:

# Symbol name strings.

# Relocations.

The symbol name a relocation references is held in a specific symbol name string record in the table the relocation record references. The record counts the number of references and the string is removed from the table when the reference count reaches 0. There can be many relocations referencing the symbol. The strings are referenced by a single 16bit unsigned integer which is the count of the string in the table.

The section the relocation is for in the object is the section number. The relocation data is series of machine word sized fields:

# Offset in the section.

# Relocation info (format specific)

# Additional format specific data.

## Macro Definition Documentation

## ◆ RTEMS_RTL_UNRESOLV_SYM_HAS_ERROR

#define RTEMS_RTL_UNRESOLV_SYM_HAS_ERROR (1 << 1)

The symbol load has an error.

## ◆ RTEMS_RTL_UNRESOLV_SYM_SEARCH_ARCHIVE

#define RTEMS_RTL_UNRESOLV_SYM_SEARCH_ARCHIVE (1 << 0)

Unresolved external symbol flags. Search the archive.

## Typedef Documentation

## ◆ rtems_rtl_tramp_reloc

typedef struct rtems_rtl_tramp_reloc rtems_rtl_tramp_reloc

Trampolines require the relocation records to be held

## ◆ rtems_rtl_unresolv_block

typedef struct rtems_rtl_unresolv_block rtems_rtl_unresolv_block

Unresolved blocks.

## ◆ rtems_rtl_unresolv_rec

typedef struct rtems_rtl_unresolv_rec rtems_rtl_unresolv_rec

Unresolved externals records.

## ◆ rtems_rtl_unresolv_reloc

typedef struct rtems_rtl_unresolv_reloc rtems_rtl_unresolv_reloc

Unresolved externals symbols require the relocation records to be held and referenced.

## ◆ rtems_rtl_unresolv_symbol

typedef struct rtems_rtl_unresolv_symbol rtems_rtl_unresolv_symbol

Unresolved externals symbols. The symbols are reference counted and separate from the relocation records because a number of records could reference the same symbol.

The name is extended in the allocator of the record in the unresolved data block. The 10 is a minimum that is added to by joining more than one record.

## ◆ rtems_rtl_unresolved

typedef struct rtems_rtl_unresolved rtems_rtl_unresolved

Unresolved table holds the names and relocations.

## ◆ rtems_rtl_unresolved_iterator

typedef bool rtems_rtl_unresolved_iterator(rtems_rtl_unresolv_rec *rec, void *data)

The iterator function used to iterate over the unresolved table.

Parameters

  rec | The current iterator.
  data | The user data.

Return values

  true | The iterator has finished.
  false | The iterator has not finished. Keep iterating.

## ◆ rtems_rtl_unresolved_rtype

typedef enum rtems_rtl_unresolved_rtype rtems_rtl_unresolved_rtype

The types of records in the blocks.

## ◆ rtems_rtl_word

typedef uint32_t rtems_rtl_word

Hack to work around machine size. This needs to be cleaned up to better support 64bit targets.

## Enumeration Type Documentation

## ◆ rtems_rtl_unresolved_rtype

enum rtems_rtl_unresolved_rtype

The types of records in the blocks.

Enumerator
rtems_rtl_unresolved_empty | The records is empty. Must always be 0
rtems_rtl_unresolved_symbol | The record is a symbol.
rtems_rtl_unresolved_reloc | The record is a relocation record.
rtems_rtl_trampoline_reloc | The record is a trampoline relocation record.

## Function Documentation

## ◆ rtems_rtl_unresolved_add()

bool rtems_rtl_unresolved_add | ( | rtems_rtl_obj * | obj,
|  | const uint16_t | flags,
|  | const char * | name,
|  | const uint16_t | sect,
|  | const rtems_rtl_word * | rel
| ) |  |

Add a relocation to the list of unresolved relocations.

Parameters

  unresolved | The unresolved symbol table.
  obj | The object table the symbols are for.
  flags | Format specific flags.
  name | The symbol name the relocation references.
  sect | The target section number the relocation references.
  rel | The format specific relocation data.

Return values

  true | The relocation has been added.
  false | The relocation could not be added.

## ◆ rtems_rtl_unresolved_dump()

void rtems_rtl_unresolved_dump | ( | void |  | ) |

Dump the RTL unresolved data.

## ◆ rtems_rtl_unresolved_iterate()

bool rtems_rtl_unresolved_iterate | ( | rtems_rtl_unresolved_iterator | iterator,
|  | void * | data
| ) |  |

Iterate over the table of unresolved entries.

## ◆ rtems_rtl_unresolved_remove()

bool rtems_rtl_unresolved_remove | ( | rtems_rtl_obj * | obj,
|  | const char * | name,
|  | const uint16_t | sect,
|  | const rtems_rtl_word * | rel
| ) |  |

Remove a relocation from the list of unresolved relocations.

Parameters

  unresolved | The unresolved symbol table.
  obj | The object table the symbols are for.
  esyms | The exported symbol table.
  size | The size of the table in bytes.

## ◆ rtems_rtl_unresolved_resolve()

void rtems_rtl_unresolved_resolve | ( | void |  | ) |

Resolve the unresolved symbols.

## ◆ rtems_rtl_unresolved_set_archive_search()

void rtems_rtl_unresolved_set_archive_search | ( | void |  | ) |

Set all symbols to be archive searchable. This is done when the available archives have been refreshed and there are new archives to search for.

## ◆ rtems_rtl_unresolved_table_close()

void rtems_rtl_unresolved_table_close | ( | rtems_rtl_unresolved * | unresolved | ) |

Close the table and erase the blocks.

Parameters

  unreolved | Close the unresolved table.

## ◆ rtems_rtl_unresolved_table_open()

bool rtems_rtl_unresolved_table_open | ( | rtems_rtl_unresolved * | unresolved,
|  | size_t | block_records
| ) |  |

Open an unresolved relocation table.

Parameters

  unresolv | The unresolved table to open.
  block_records | The number of records per block allocated.

Return values

  true | The table is open.
  false | The unresolved relocation table could not created. The RTL error has the error.