debug_symbol disassemble
API Reference Manual  /  7 Simulator-to-Simulator Interfaces  / 

debug_symbol_file

Description

This interface has functions for operating directly on symbol files, instead of using contexts related to processes or processors. Files opened with this interface can be used together with functions in the debug_symbol interface that do not require any stack or location information. There are also functions for getting information about the symbol file, such as listing sections or segments.

For all functions that return an attr_value_t, that return value will consists of a list with two elements. The first element is an error code of debugger_error_t type (see debug_query interface documentation for definition). The second element depends on the first. If the first element is Debugger_No_Error, meaning that the function went well, then the second element will contain the expected return value that is specified per function below. If the first element is another error code, then the second element will be a string describing the error that occurred.

All function but open_symbol_file has to act on a context id, ctx_id, that has been returned by open_symbol_file, otherwise a Debugger_Not_Supported_For_Context error will be returned.

open_symbol_file opens a symbol file, specified by the filename argument, as a context so that this can be used with many of the symbol lookup functions in the debug_symbol interface. The address is the offset for which to load the symbol file if absolute_address is false. If absolute_address is true, address will instead be the absolute address to load the symbol file on. The returned value will be a context id that can be used as argument where a ctx_id is required. Functions that take a stack frame can only be accessed with no stack (value -1) when used with a symbol file context. Files that read or write memory cannot be used.

Errors specific to this function:

open_symbol_section opens a symbol file in the same way as open_symbol_file, but only adds symbols from the specified section. Other arguments and return value are as for open_symbol_file. The symbol section is closed using close_symbol_file. This method can only handle ELF binaries. In addition to errors reported by open_symbol_file this function can report Debugger_Section_Not_Found if the section cannot be found.

close_symbol_file closes a symbol file that was opened with open_symbol_file. The ctx_id should be the context id returned from that function. The returned value will just be nil when this goes well.

symbol_file_info returns a list containing a string describing the file format and a dictionary with information about the file. The ctx_id argument should be the context id returned from the open_symbol_file. The returned information depends on which file format the file has. For ELF files the string is "ELF" and the returned entries are:

For PE files the string is "PE" and the returned entries are:

Both PE and ELF files will include the following entries:

sections_info provides information about the sections in the symbol file. The ctx_id must be an id for a file opened with open_symbol_file or open_symbol_section in this interface. The returned result is a list with two elements, the first a string specifying the format of the file, "ELF" or "PE", and the second a list of dictionaries where each dictionary contains information about the section. If an id from open_symbol_section is used then only the opened section will be included in the list. The following keys exist in the dictionary:

segments_info provides information about the segments in the symbol file, this is only supported for ELF. The ctx_id must be an id for a file opened with open_symbol_file in this interface. The returned result is a list where each entry represent a segment. Each entry is in turn a dictionary with the following keys: 

SIM_INTERFACE(debug_symbol_file) {
        attr_value_t (*open_symbol_file)(conf_object_t *NOTNULL obj,
                                         const char *NOTNULL filename,
                                         uint64 address, bool absolute_address);
        attr_value_t (*close_symbol_file)(conf_object_t *NOTNULL obj,
                                         const char *NOTNULL ctx_id);
        attr_value_t (*symbol_file_info)(conf_object_t *NOTNULL obj,
                                         const char *NOTNULL ctx_id);
        attr_value_t (*sections_info)(conf_object_t *NOTNULL obj,
                                      const char *NOTNULL ctx_id);
        attr_value_t (*segments_info)(conf_object_t *NOTNULL obj,
                                      const char *NOTNULL ctx_id);
        attr_value_t (*open_symbol_section)(conf_object_t *NOTNULL obj,
                                            const char *NOTNULL filename,
                                            const char *NOTNULL section,
                                            uint64 address,
                                            bool absolute_address);
};
#define DEBUG_SYMBOL_FILE_INTERFACE "debug_symbol_file"

Execution Context
Global Context for all methods.

debug_symbol disassemble