RTEMS: cpukit/libdl/rtl.c File Reference

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
rtl.c File Reference

RTEMS Run-Time Link Editor. More...

`#include <stdlib.h>`
`#include <stdio.h>`
`#include <string.h>`
`#include <rtems/libio_.h>`
`#include <rtems/rtl/rtl.h>`
`#include <rtems/rtl/rtl-allocator.h>`
`#include <rtems/rtl/rtl-trace.h>`
`#include "rtl-chain-iterator.h"`
`#include "rtl-error.h"`
`#include "rtl-string.h"`

## Data Structures
struct | rtems_rtl_obj_flags_data

## Macros
#define | RTEMS_RTL_ELF_SYMBOL_CACHE (2048)
#define | RTEMS_RTL_ELF_STRING_CACHE (2048)
#define | RTEMS_RTL_ELF_RELOC_CACHE (2048)
#define | RTEMS_RTL_COMP_OUTPUT (2048)

## Typedefs
typedef struct rtems_rtl_obj_flags_data | rtems_rtl_obj_flags_data

## Functions
void | rtems_rtl_base_global_syms_init (void)
rtems_rtl_data * | rtems_rtl_data_unprotected (void)
rtems_rtl_symbols * | rtems_rtl_global_symbols (void)
const char * | rtems_rtl_last_error_unprotected (void)
rtems_chain_control * | rtems_rtl_objects_unprotected (void)
rtems_chain_control * | rtems_rtl_pending_unprotected (void)
rtems_rtl_unresolved * | rtems_rtl_unresolved_unprotected (void)
rtems_rtl_archives * | rtems_rtl_archives_unprotected (void)
void | rtems_rtl_obj_caches (rtems_rtl_obj_cache **symbols, rtems_rtl_obj_cache **strings, rtems_rtl_obj_cache **relocs)
void | rtems_rtl_obj_caches_flush (void)
void | rtems_rtl_obj_decompress (rtems_rtl_obj_comp **decomp, rtems_rtl_obj_cache *cache, int fd, int compression, off_t offset)
void | rtems_rtl_obj_update_flags (uint32_t clear, uint32_t set)
rtems_rtl_data * | rtems_rtl_lock (void)
void | rtems_rtl_unlock (void)
rtems_rtl_obj * | rtems_rtl_check_handle (void *handle)
rtems_rtl_obj * | rtems_rtl_find_obj (const char *name)
rtems_rtl_obj * | rtems_rtl_find_obj_with_symbol (const rtems_rtl_obj_sym *sym)
rtems_rtl_obj * | rtems_rtl_load_object (const char *name, int mode)
rtems_rtl_obj * | rtems_rtl_load (const char *name, int mode)
bool | rtems_rtl_unload_object (rtems_rtl_obj *obj)
bool | rtems_rtl_unload (rtems_rtl_obj *obj)
bool | rtems_rtl_path_append (const char *path)
bool | rtems_rtl_path_prepend (const char *path)
void | rtems_rtl_base_sym_global_add (const unsigned char *esyms, unsigned int size)
rtems_rtl_obj * | rtems_rtl_baseimage (void)

## Detailed Description

RTEMS Run-Time Link Editor.

This is the RTL implementation.

## Macro Definition Documentation

## ◆ RTEMS_RTL_COMP_OUTPUT

#define RTEMS_RTL_COMP_OUTPUT (2048)

Decompression output buffer.

## ◆ RTEMS_RTL_ELF_RELOC_CACHE

#define RTEMS_RTL_ELF_RELOC_CACHE (2048)

Relocations table cache size.

## ◆ RTEMS_RTL_ELF_STRING_CACHE

#define RTEMS_RTL_ELF_STRING_CACHE (2048)

String table cache size.

## ◆ RTEMS_RTL_ELF_SYMBOL_CACHE

#define RTEMS_RTL_ELF_SYMBOL_CACHE (2048)

Symbol table cache size. They can be big so the cache needs space to work.

## Function Documentation

## ◆ rtems_rtl_archives_unprotected()

rtems_rtl_archives * rtems_rtl_archives_unprotected | ( | void |  | ) |

Get the RTL archives with out locking. This call assumes the RTL is locked.

Returns
  rtems_rtl_archives* The RTL acrhives.

Return values

  NULL | The RTL data is not initialised.

## ◆ rtems_rtl_base_global_syms_init()

void rtems_rtl_base_global_syms_init | ( | void |  | ) |

Define a default base global symbol loader function that is weak so a real table can be linked in when the user wants one.

## ◆ rtems_rtl_base_sym_global_add()

void rtems_rtl_base_sym_global_add | ( | const unsigned char * | esyms,
|  | unsigned int | count
| ) |  |

Add an exported symbol table to the global symbol table. This call is normally used by an object file when loaded that contains a global symbol table.

Parameters

  esyms | The exported symbol table.
  count | The size of the exported symbol table.

## ◆ rtems_rtl_baseimage()

rtems_rtl_obj * rtems_rtl_baseimage | ( | void |  | ) |

Return the object file descriptor for the base image. The object file descriptor returned is created when the run time linker is initialised.

Assumes the RTL has been locked.

Returns
  rtl_obj* The object file descriptor for the base image. NULL is returned if the load fails.

## ◆ rtems_rtl_check_handle()

rtems_rtl_obj * rtems_rtl_check_handle | ( | void * | handle | ) |

Check a pointer is a valid object file descriptor returning the pointer as that type.

Assumes the RTL has been locked.

Parameters

  handle | Pointer to the object file to be validated.

Returns
  rtl_obj* The object file descriptor. NULL is returned if invalid.

## ◆ rtems_rtl_data_unprotected()

rtems_rtl_data * rtems_rtl_data_unprotected | ( | void |  | ) |

Get the RTL data with out locking. This call assumes the RTL is locked.

Returns
  rtems_rtl_data* The RTL data after being locked.

Return values

  NULL | The RTL data is not initialised.

## ◆ rtems_rtl_find_obj()

rtems_rtl_obj * rtems_rtl_find_obj | ( | const char * | name | ) |

Find the object given a file name.

Parameters

  name | The name of the object file.

Return values

  NULL | No object file with that name found.

Returns
  rtems_rtl_obj* The object file descriptor.

## ◆ rtems_rtl_find_obj_with_symbol()

rtems_rtl_obj * rtems_rtl_find_obj_with_symbol | ( | const rtems_rtl_obj_sym * | sym | ) |

Find the object file a symbol is exported from.

Parameters

  sym | The symbol to search with.

Return values

  NULL | No object file found.

Returns
  rtems_rtl_obj* Reference to the symbol.

## ◆ rtems_rtl_global_symbols()

rtems_rtl_symbols * rtems_rtl_global_symbols | ( | void |  | ) |

Get the RTL global symbol table with out locking. This call assumes the RTL is locked.

Returns
  rtems_rtl_symbols* The RTL global symbols after being locked.

Return values

  NULL | The RTL data is not initialised.

## ◆ rtems_rtl_last_error_unprotected()

const char * rtems_rtl_last_error_unprotected | ( | void |  | ) |

Get the RTL last error string with out locking. This call assumes the RTL is locked.

Returns
  const char* The RTL's laste error.

Return values

  NULL | The RTL data is not initialised.

## ◆ rtems_rtl_load()

rtems_rtl_obj * rtems_rtl_load | ( | const char * | name,
|  | int | mode
| ) |  |

Load an object file. This is the user accessable interface to unloading an object file. See @rtems_rtl_load_object.

Parameters

  name | The name of the object file.
  mode | The mode of the load as defined by the dlopen call.

Returns
  rtl_obj* The object file descriptor. NULL is returned if the load fails.

## ◆ rtems_rtl_load_object()

rtems_rtl_obj * rtems_rtl_load_object | ( | const char * | name,
|  | int | mode
| ) |  |

Load an object file into memory relocating it. It will not be resolved against other symbols in other object files or the base image.

The name can be a file name for an object file or it can be encoded to reference an archive of object modules (static library). This encoding is specific to RTEMS and allows dependences to specify an archive without the searching overhead normally incurred by linkers locating object files in an archive. The file name format rules are:

1. Absolute file references a specific object file in the architecture specific location on the file system.
2. Relative file references an object format file in the search path.
3. Absolute archive and file reference to a specific location in the file system. The archive and file are encoded as 'archive:file [@offset]' where 'archive' is a valid file at the absolute path in the file system, and 'file' is a contained in the archive, and optionally an offset to the 'file' in the 'archive'. If no offset is provided the archive is searched.
4. Relative archive and file in the search path. The encoding is the same as described in item 3 of this list.

Assumes the RTL has been locked.

Parameters

  name | The name of the object file.
  mode | The mode of the load as defined by the dlopen call.

Returns
  rtl_obj* The object file descriptor. NULL is returned if the load fails.

## ◆ rtems_rtl_lock()

rtems_rtl_data * rtems_rtl_lock | ( | void |  | ) |

Lock the Run-time Linker.

Returns
  rtems_rtl_data* The RTL data after being locked.

Return values

  NULL | The RTL data could not be initialised or locked. Typically this means the lock could not be created.

## ◆ rtems_rtl_obj_caches()

void rtems_rtl_obj_caches | ( | rtems_rtl_obj_cache ** | symbols,
|  | rtems_rtl_obj_cache ** | strings,
|  | rtems_rtl_obj_cache ** | relocs
| ) |  |

Get the RTL symbols, strings, or relocations object file caches. This call assmes the RTL is locked.

Parameters

  symbols | Pointer to the location to set the cache into. Returns NULL is rtl is not initialised. If NULL is passed in no value set.
  strings | Pointer to the location to set the cache into. Returns NULL is rtl is not initialised. If NULL is passed in no value set.
  relocs | Pointer to the location to set the cache into. Returns NULL is rtl is not initialised. If NULL is passed in no value set.

## ◆ rtems_rtl_obj_caches_flush()

void rtems_rtl_obj_caches_flush | ( | void |  | ) |

Flush all the object file caches.

## ◆ rtems_rtl_obj_decompress()

void rtems_rtl_obj_decompress | ( | rtems_rtl_obj_comp ** | decomp,
|  | rtems_rtl_obj_cache * | cache,
|  | int | fd,
|  | int | compression,
|  | off_t | offset
| ) |  |

Get the RTL decompressor setting for the cache and the offset in the file the compressed stream starts. This call assumes the RTL is locked.

Parameters

  decomp | Pointer to the location to set the compressor into. Returns NULL is rtl is not initialised.
  cache | The cache to read the file with. Saves needing an extrs buffer.
  offset | The offset in the file the compressed stream starts.

## ◆ rtems_rtl_obj_update_flags()

void rtems_rtl_obj_update_flags | ( | uint32_t | clear,
|  | uint32_t | set
| ) |  |

Update the mask in the object files. You can clear flags and then set flags. A zero (0) does not clear or set the flags. This is global to all object files that are laoded.

Parameters

  clear | The flag's clear mask, a 0 does not clear any flags.
  set | The flag's set mask, a 0 does not set any flags.

## ◆ rtems_rtl_objects_unprotected()

rtems_chain_control * rtems_rtl_objects_unprotected | ( | void |  | ) |

Get the RTL objects table with out locking. This call assumes the RTL is locked.

Returns
  rtems_chain_control* The RTL objects chain.

Return values

  NULL | The RTL data is not initialised.

## ◆ rtems_rtl_path_append()

bool rtems_rtl_path_append | ( | const char * | path | ) |

Append the path to the search path.

Parameters

  path | The path to append.

Return values

  false | The path could not be appended.
  true | The path was appended.

## ◆ rtems_rtl_path_prepend()

bool rtems_rtl_path_prepend | ( | const char * | path | ) |

Prepend the path to the search path.

Parameters

  path | The path to prepend.

Return values

  false | The path could not be prepended.
  true | The path was prepended.

## ◆ rtems_rtl_pending_unprotected()

rtems_chain_control * rtems_rtl_pending_unprotected | ( | void |  | ) |

Get the RTL pending with out locking. This call assumes the RTL is locked.

Returns
  rtems_chain_control* The RTL pending list control.

Return values

  NULL | The RTL data is not initialised.

## ◆ rtems_rtl_unload()

bool rtems_rtl_unload | ( | rtems_rtl_obj * | obj | ) |

Unload an object file. This is the user accessable interface to unloading an object file. See @rtems_rtl_unload_object.

Assumes the RTL has been locked.

Parameters

  obj | The object file descriptor.

Return values

  true | The object file has been unloaded.
  false | The object file could not be unloaded.

## ◆ rtems_rtl_unload_object()

bool rtems_rtl_unload_object | ( | rtems_rtl_obj * | obj | ) |

Unload an object file. This only happens when the user count is 0.

Assumes the RTL has been locked.

Parameters

  obj | The object file descriptor.

Return values

  true | The object file has been unloaded.
  false | The object file could not be unloaded.

## ◆ rtems_rtl_unlock()

void rtems_rtl_unlock | ( | void |  | ) |

Unlock the Run-time Linker.

## ◆ rtems_rtl_unresolved_unprotected()

rtems_rtl_unresolved * rtems_rtl_unresolved_unprotected | ( | void |  | ) |

Get the RTL unresolved table with out locking. This call assumes the RTL is locked.

Returns
  rtems_rtl_unresolv* The RTL unresolved symbols and reloc records.

Return values

  NULL | The RTL data is not initialised.