TEMU  2
The Terma Emulator
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Loader.h File Reference
#include <stdint.h>
#include "temu-c/Support/Attributes.h"
Include dependency graph for Loader.h:

Go to the source code of this file.

Typedefs

typedef void temu_DebugInfoCtxt
 
typedef void temu_Symtab
 

Functions

TEMU_API int temu_loadImage (void *mem, const char *file)
 Loads a binary image to the memory object. More...
 
TEMU_API int temu_loadImageAndStartAddr (void *Mem, const char *FileName, uint64_t *StartAddr TEMU_NONNULL)
 Loads a binary image to the memory object. More...
 
TEMU_API int temu_loadRelocatedImage (void *mem, const char *file, uint64_t pa) __attribute__((deprecated))
 
TEMU_API int temu_loadBinaryImage (void *mem, const char *file, uint64_t pa)
 Loads a raw binary image to the memory object at the given address. More...
 
TEMU_API int temu_loadElfImage (void *mem, const char *file, uint64_t pa)
 Loads an ELF file without going through filetype detection. More...
 
TEMU_API int temu_loadElfImageAndStartAddr (void *Mem, const char *FileName, uint64_t *StartAddr TEMU_NONNULL)
 Loads an ELF file without going through filetype detection. More...
 
TEMU_API int temu_imageIsELF (const char *file)
 Return non-zero if file is an ELF file. More...
 
TEMU_API int temu_loadSymtab (const char *FileName, temu_Symtab **Sym TEMU_NONNULL)
 Loads the symbol table from a given ELF file. More...
 
TEMU_API void temu_symtabGetFuncName (temu_Symtab *Sym TEMU_NONNULL, const char **LocalFile TEMU_NONNULL, const char **Symbol TEMU_NONNULL, uint64_t Addr)
 Get the function name associated with the given address. More...
 
TEMU_API void temu_symtabGetObjName (temu_Symtab *Sym TEMU_NONNULL, const char **LocalFile TEMU_NONNULL, const char **Symbol TEMU_NONNULL, uint64_t Addr)
 Get the object name associated with the given address. More...
 
TEMU_API int temu_symtabGetGlobalFuncRange (temu_Symtab *Sym TEMU_NONNULL, const char *FuncName TEMU_NONNULL, uint64_t *Addr TEMU_NONNULL, uint64_t *Size)
 Get the range of a global function. More...
 
TEMU_API int temu_symtabGetLocalFuncRange (temu_Symtab *Sym TEMU_NONNULL, const char *FileName TEMU_NONNULL, const char *FuncName TEMU_NONNULL, uint64_t *Addr TEMU_NONNULL, uint64_t *Size TEMU_NONNULL)
 Get the range of a local/static function. More...
 
TEMU_API int temu_symtabGetGlobalObjRange (temu_Symtab *Sym TEMU_NONNULL, const char *ObjectName TEMU_NONNULL, uint64_t *Addr TEMU_NONNULL, uint64_t *Size TEMU_NONNULL)
 Get the range of a global object. More...
 
TEMU_API int temu_symtabGetLocalObjRange (temu_Symtab *Sym TEMU_NONNULL, const char *FileName TEMU_NONNULL, const char *ObjectName TEMU_NONNULL, uint64_t *Addr TEMU_NONNULL, uint64_t *Size TEMU_NONNULL)
 Get the range of a local/static object. More...
 
TEMU_API void temu_disposeSymtab (temu_Symtab *Sym)
 Dispose (deallocate) the symbol table. More...
 
TEMU_API int temu_loadDebugInfo (const char *File, temu_DebugInfoCtxt **DICtxt)
 Loads a debug info context from the given file. More...
 
TEMU_API void temu_disposeDebugInfo (temu_DebugInfoCtxt *DICtxt)
 Delete loaded debug info. More...
 
TEMU_API int temu_debugGetAddressRange (temu_DebugInfoCtxt *DICtxt, const char *FuncName, uint64_t *Start, uint64_t *End)
 
TEMU_API int temu_debugGetEntryPoint (temu_DebugInfoCtxt *DICtxt, const char *FuncName, uint64_t *Entry)
 
TEMU_API int temu_loadSrecImage (void *mem, const char *file, uint64_t pa)
 Loads an SREC file without going through filetype detection. More...
 
TEMU_API int temu_loadSrecImageAndStartAddr (void *Mem, const char *FileName, uint32_t *StartAddr TEMU_NONNULL)
 

Typedef Documentation

typedef void temu_DebugInfoCtxt

Definition at line 71 of file Loader.h.

typedef void temu_Symtab

Definition at line 72 of file Loader.h.

Function Documentation

TEMU_API int temu_debugGetAddressRange ( temu_DebugInfoCtxt DICtxt,
const char *  FuncName,
uint64_t *  Start,
uint64_t *  End 
)
TEMU_API int temu_debugGetEntryPoint ( temu_DebugInfoCtxt DICtxt,
const char *  FuncName,
uint64_t *  Entry 
)
TEMU_API void temu_disposeDebugInfo ( temu_DebugInfoCtxt DICtxt)

Delete loaded debug info.

TEMU_API void temu_disposeSymtab ( temu_Symtab Sym)

Dispose (deallocate) the symbol table.

Parameters
SymSymbol table pointer to free.
TEMU_API int temu_imageIsELF ( const char *  file)

Return non-zero if file is an ELF file.

Parameters
filePath to file to check for ELFiness.
Returns
0 if file is not an ELF file, 1 if the file is an ELF file.
TEMU_API int temu_loadBinaryImage ( void *  mem,
const char *  file,
uint64_t  pa 
)

Loads a raw binary image to the memory object at the given address.

The function will assume that the file is a raw binary. This way you can load an ELF file as is to memory (e.g. where it is expected by the boot loader).

Parameters
memMemory object, must conform to the mem interface.
filePath to file to load.
paPhysical address where to load the image.
Returns
0 on success, other values indicates errors.
TEMU_API int temu_loadDebugInfo ( const char *  File,
temu_DebugInfoCtxt **  DICtxt 
)

Loads a debug info context from the given file.

This function is EXPERIMENTAL! It is aimed at providing a way to load debug info data, e.g. DWARF or STABS from an elf file, or simply read a symbol file. Currently, the function is able to parse DWARF4 info in an elf-file.

Parameters
FilePath to file to load.
DICtxtIf non-null, a DebugInfoCtxt object will be returned in the provided pointer.
Returns
0 on success, other values indicates errors.
TEMU_API int temu_loadElfImage ( void *  mem,
const char *  file,
uint64_t  pa 
)

Loads an ELF file without going through filetype detection.

Parameters
memMemory object, must conform to the mem interface.
filePath to file to load.
paUnused argument
Returns
0 on success, other values indicates errors
TEMU_API int temu_loadElfImageAndStartAddr ( void *  Mem,
const char *  FileName,
uint64_t *StartAddr  TEMU_NONNULL 
)

Loads an ELF file without going through filetype detection.

Parameters
MemMemory object, must conform to the mem interface.
FileNamePath to file to load.
StartAddrPointer where to place the start address of the elf file
Returns
0 on success, other values indicates errors
TEMU_API int temu_loadImage ( void *  mem,
const char *  file 
)

Loads a binary image to the memory object.

The function will autodetect the file type (based on extensions and magic headers in the file).

Binary images will be placed at address 0.

The image can be one of the supported file formats.

Parameters
memMemory object, must conform to the mem interface.
filePath to file to load.
Returns
0 on success, other values indicates errors.
TEMU_API int temu_loadImageAndStartAddr ( void *  Mem,
const char *  FileName,
uint64_t *StartAddr  TEMU_NONNULL 
)

Loads a binary image to the memory object.

The function will autodetect the file type (based on extensions and magic headers in the file).

Binary images will be placed at address 0.

The image can be one of the supported file formats.

This specific variant, will return the start address of the binary, the StartAddr is typically embedded in the ELF or SREC files. The function therefore allows you to set the program counter to the correct start address after the function has been called.

Parameters
MemMemory object, must conform to the mem interface.
FileNamePath to file to load.
StartAddrPointer to location to store the start address.
Returns
0 on success, other values indicates errors.
TEMU_API int temu_loadRelocatedImage ( void *  mem,
const char *  file,
uint64_t  pa 
)
TEMU_API int temu_loadSrecImage ( void *  mem,
const char *  file,
uint64_t  pa 
)

Loads an SREC file without going through filetype detection.

Parameters
memMemory object, must conform to the mem interface.
filePath to file to load.
paUnused argument
Returns
0 on success, other values indicates errors
TEMU_API int temu_loadSrecImageAndStartAddr ( void *  Mem,
const char *  FileName,
uint32_t *StartAddr  TEMU_NONNULL 
)
TEMU_API int temu_loadSymtab ( const char *  FileName,
temu_Symtab **Sym  TEMU_NONNULL 
)

Loads the symbol table from a given ELF file.

The symbol table is allocated and the pointer of the allocated symbol table is placed in Sym. The user is responsible for disposing the symbol table with temu_disposeSymtab().

Parameters
FileNameName of ELF file
SymAddress of your symtab pointer.
Returns
0 on success, other values indicates errors.
TEMU_API void temu_symtabGetFuncName ( temu_Symtab *Sym  TEMU_NONNULL,
const char **LocalFile  TEMU_NONNULL,
const char **Symbol  TEMU_NONNULL,
uint64_t  Addr 
)

Get the function name associated with the given address.

The address can be any address within the range of the function, i.e. from the start to othe end of the function. Thus this serves as a way to find the name of the current function given a PC value.

The function first searches for local symbols (e.g. static symbols in C). It then searches for global symbols and last for weak symbols.

If a local symbol is found, the LocalFile pointer will point at a string with the file name it is associated to, otherwise the local file pointer will be set to null.

The returned pointers are valid until the symbol table is disposed.

Parameters
SymSymboltable
LocalFileThe pointer it refers to will be set to NULL if the symbol found is global.
SymbolThe pointer will be set to NULL if a function cannot be found at the address.
AddrVirtual address to find a function name for.
TEMU_API int temu_symtabGetGlobalFuncRange ( temu_Symtab *Sym  TEMU_NONNULL,
const char *FuncName  TEMU_NONNULL,
uint64_t *Addr  TEMU_NONNULL,
uint64_t *  Size 
)

Get the range of a global function.

On success, the Addr and the Size references will be set to the starting virtual address of the function and the size in bytes respectively.

Parameters
SymThe Symbol table, from which the function to be retrieved TODO: check if correct
FuncNameThe function, whose range is required
AddrOn success, gives the address of the function
SizeOn success, gives the size of the function start from Addr
Returns
0 on success (the function exists), other values indicate falures.
TEMU_API int temu_symtabGetGlobalObjRange ( temu_Symtab *Sym  TEMU_NONNULL,
const char *ObjectName  TEMU_NONNULL,
uint64_t *Addr  TEMU_NONNULL,
uint64_t *Size  TEMU_NONNULL 
)

Get the range of a global object.

On success, the Addr and the Size references will be set to the starting virtual address of the object and the size in bytes respecivelly.

Parameters
SymThe Symbol table, from which the object to be retrieved
ObjectNameName of the object, whose address range is to be obtained
AddrOn success, gives the address of the object
SizeOn success, gives the size of the object start from Addr
Returns
0 on success (the object exists), other values indicate falures
TEMU_API int temu_symtabGetLocalFuncRange ( temu_Symtab *Sym  TEMU_NONNULL,
const char *FileName  TEMU_NONNULL,
const char *FuncName  TEMU_NONNULL,
uint64_t *Addr  TEMU_NONNULL,
uint64_t *Size  TEMU_NONNULL 
)

Get the range of a local/static function.

On success, the Addr and the Size references will be set to the starting virtual address of the function and the size in bytes respecivelly.

Parameters
SymThe Symbol table, from which the function to be retrieved
FileNameThe file/compilation unit that contains the function
FuncNameThe function, whose range is required
AddrOn success, gives the address of the function
SizeOn success, gives the size of the function start from Addr
Returns
0 on success (the function exists in the given file), other values indicate falures
TEMU_API int temu_symtabGetLocalObjRange ( temu_Symtab *Sym  TEMU_NONNULL,
const char *FileName  TEMU_NONNULL,
const char *ObjectName  TEMU_NONNULL,
uint64_t *Addr  TEMU_NONNULL,
uint64_t *Size  TEMU_NONNULL 
)

Get the range of a local/static object.

On success, the Addr and the Size references will be set to the starting virtual address of the object and the size in bytes respecivelly.

Parameters
SymThe Symbol table, from which the object to be retrieved
FileNameThe file/compilation unit that contains the function
ObjectNameThe object, whose range is required
AddrOn success, gives the address of the object
SizeOn success, gives the size of the object start from Addr
Returns
0 on success (the object exists), other values indicate falures
TEMU_API void temu_symtabGetObjName ( temu_Symtab *Sym  TEMU_NONNULL,
const char **LocalFile  TEMU_NONNULL,
const char **Symbol  TEMU_NONNULL,
uint64_t  Addr 
)

Get the object name associated with the given address.

The address can be any address within the range of the object. Thus this serves as a way to find the name of a global or static object given an address.

The function first searches for local symbols (e.g. static symbols in C). It then searches for global symbols and last for weak symbols.

If a local symbol is found, the LocalFile pointer will point at a string with the file name it is associated to, otherwise the local file pointer will be set to NULL.

The returned pointers are valid until the symbol table is disposed.

Parameters
SymSymboltable
LocalFileThe pointer it refers to will be set to NULL if the symbol found is global.
SymbolThe pointer will be set to NULL if an object cannot be found at the address.
AddrVirtual address to find an object name for.