debug_setup

Description

Functions in the debug_setup interfaces are used to provide the debugger with symbol files and paths. There are also functions for listing what symbol files and paths have been added.

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.

Upon success, all functions for adding symbols will return an id that can be used with remove_symbol_file.

add_symbol_file adds a symbol file, symbol_file, used for debugging contexts that match the context-query query. The address argument specifies the address that the file should be mapped to. If absolute_address is set then the given address will be the absolute address of the first relocatable segment and other segments will be added with their given offsets to that segment.

Errors specific to this function:

• Debugger_Failed_To_Open_File - File cannot be opened.
• Debugger_Unrecognized_File_Format - The file format is not recognized.
• Debugger_Segment_Info_Missing - If an ELF file is being added, but no valid segments can be found.

add_symbol_segment adds symbols from the specified segment of an ELF symbol file. Other arguments are the same as for add_symbol_file. The address of the segment is specified with the address argument. If absolute_address is set this address will be an absolute address otherwise it will be an offset to the address found in the symbol file for that segment.

Errors specific to this function:

• Debugger_Segment_Not_Found - Segment not found when adding a segment.
• Debugger_Segment_Info_Missing - Segment information is missing or incomplete.
• Debugger_Not_Relocatable - The segment is not relocatable.
• Debugger_Unsupported_For_File_Format - File format is not ELF.

add_symbol_section adds symbols from the specified section of an ELF symbol file. Other arguments are the same as for add_symbol_file. The address of the section is specified with the address argument. If absolute_address is set this address will be an absolute address otherwise it will be an offset to the address found in the symbol file for that section.

Errors specific to this function:

• Debugger_Section_Not_Found - Section not found when adding a section.
• Debugger_Section_Info_Missing - Section information is missing or incomplete.
• Debugger_Not_Relocatable - The section is not relocatable.
• Debugger_Unsupported_For_File_Format - File format is not ELF.

Note: Adding the same symbol file, section or segment more than once might result in unexpected behavior and is not supported.

remove_symbol_file removes the debugger's knowledge of symbols that was added with any of the functions for adding symbols. The id argument is the id returned from the add function.

Errors specific to this function:

• Debugger_Unknown_Id - The id is unknown.

clear_symbol_files removes the debugger's knowledge about all symbol files added by add_symbol_file.

symbol_files lists all added symbol files. A dictionary, with id as key will be returned. An id is always bound to one query and one symbol file, but it can contain several memory maps. The listed id is the argument passed to remove_symbol_file. The dictionary values have the following format:

• query (string) - The context query the symbol is valid for.
• relocation (uint64) - The relocation address provided when the symbol file was added.
• symbol-file (string) - The file containing the symbol information.
• memory-maps ([<dict>, ...]) - A list of memory maps that are added togheter as the same id, see format below:

The dictionary describing a memory map has the following format:

• address (uint64) - The address of the section in memory.
• size (uint64) - The section size in memory.
• flags (uint64) - Format specific flags describing the section.
• section (string) - The name of the section.
• file-offset (uint64) - Offset in symbol file for the section.
• file-size (uint64) - Size of the section in the symbol file.

symbol_files_for_ctx is the same as symbol_files except that it only returns symbol files that are valid for the given context id, ctx_id.

list_all_mappings lists all symbol mappings for a certain context ctx_id. This will be all mappings from symbol files added by users plus any symbol mappings added elsewhere, from trackers for example. The returned value is a dictionary on the following format:

• filename (string) - The file backing the memory map.
• query (string) - The query the map is valid for.
• address (uint64) - The map's address in context memory.
• size (uint64) - The size of the map in memory.
• flags (uint64) - Read, write, and execute flags, bit 0 is set if readable, bit 1 if writeable and bit 2 if executable. If this value is 0 this is the same as if all flags are set.
• section-name (string) - The section name, or NIL.
• file-offset (int64) - Offset into the backing file.
• file-size (uint64) - Size of the map in the backing file.
• relocation (uint64) - The offset from the address in the symbol file to where the mappings is actually loaded in memory. This is not always present in the dictionary.

Some other internal entries could possibly also be present in the dictionary.

add_path_map_entry adds a path math entry that maps a source file from the source in the symbol file to the actual destination, dest, where it is located on disk. The query argument specifies for which context-queries the mapping should apply. The returned id can be used with remove_path_map_entry to remove the added path map. The source path may not be empty or be just "." or "./".

Errors specific to this function:

• Debugger_Invalid_Path - The source path is not valid.

remove_path_map_entry removes an entry that was added with add_path_map_entry. The id is the value returned from the add function.

Errors specific to this function:

• Debugger_Unknown_Id - The provided id is unknown.

clear_path_map_entries removes all knowledge about all path map entries added with add_path_map_entry.

path_map_entries lists all path map entries that have been added with add_path_map_entry, that matches the given context id. If the context id is nil, then all path maps will be listed. The format of the entries in the returned list are dictionaries, with an id of type debug_setup_id_t as key:

• query (string) - The context query the path map is valid for.
• source (string) - The source to translate from.
• destination (string) - The destination to translate to.

path_map_entries_for_ctx is the same as path_map_entries except that it only lists path maps that are valid for the given context id, ctx_id.

apply_path_map applies any added path map to a file path, filename, for a given context with ID ctx_id. The path with the path map applied will be returned. The path map will only apply if the destination file exists and if the path given in filename does not, otherwise the provided file will be returned. The returned path will always contain forward slashes as path separator, regardless of what the host system uses, or if any path map was applied or not.

Note: For functions that take query as argument, having this set to nil will work the same way as for "*". A bad context query will result in a Debugger_Incorrect_Context_Query error.

typedef int64 debug_setup_id_t;

SIM_INTERFACE(debug_setup) {
        attr_value_t (*add_symbol_file)(conf_object_t *NOTNULL obj,
                                        const char *query,
                                        const char *NOTNULL symbol_file,
                                        uint64 address, bool absolute_address);
        attr_value_t (*add_symbol_segment)(conf_object_t *NOTNULL obj,
                                           const char *query,
                                           const char *NOTNULL symbol_file,
                                           unsigned segment, uint64 address,
                                           bool absolute_address);
        attr_value_t (*add_symbol_section)(conf_object_t *NOTNULL obj,
                                           const char *query,
                                           const char *NOTNULL symbol_file,
                                           const char *NOTNULL section,
                                           uint64 address,
                                           bool absolute_address);
        attr_value_t (*remove_symbol_file)(conf_object_t *NOTNULL obj,
                                           debug_setup_id_t id);
        void (*clear_symbol_files)(conf_object_t *NOTNULL obj);
        attr_value_t (*symbol_files)(conf_object_t *NOTNULL obj);
        attr_value_t (*symbol_files_for_ctx)(conf_object_t *NOTNULL obj,
                                             const char *NOTNULL ctx_id);
        attr_value_t (*list_all_mappings)(conf_object_t *NOTNULL obj,
                                          const char *NOTNULL ctx_id);
        attr_value_t (*add_path_map_entry)(conf_object_t *NOTNULL obj,
                                           const char *query,
                                           const char *NOTNULL source,
                                           const char *NOTNULL dest);
        attr_value_t (*remove_path_map_entry)(conf_object_t *NOTNULL obj,
                                              debug_setup_id_t id);
        void (*clear_path_map_entries)(conf_object_t *NOTNULL obj);
        attr_value_t (*path_map_entries)(conf_object_t *NOTNULL obj);
        attr_value_t (*path_map_entries_for_ctx)(conf_object_t *NOTNULL obj,
                                                 const char *NOTNULL ctx_id);
        attr_value_t (*apply_path_map)(conf_object_t *NOTNULL obj,
                                       const char *NOTNULL ctx_id,
                                       const char *NOTNULL filename);
};
#define DEBUG_SETUP_INTERFACE "debug_setup"

Execution Context

Global Context for all methods.