This interface provides functions for querying the debugger for contexts and their information. Functions here will be used to find specific contexts or to create context-queries, that can be used with other functions in debugger interfaces.
Most functions in this interface take a Context ID, ctx_id, as
argument. This ID is passed as an argument to most callback functions in the
debug_notification interface and returned by some functions
in this interface.
All functions return an attr_value_t consisting of a list with
two elements. The first element is an error code of
debugger_error_t type. 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.
matching_contexts returns a list of context IDs matching the specified context-query, query. The returned list can be empty if there are no matching contexts.
get_context_group returns a context ID for the context marked as the group leader for the specified context, ctx_id. As example in a Linux tracker the process node will be the group leader for all threads belonging to that process. A context that lacks a specific group leader will return itself.
get_context_parent returns an ID to the parent context for the specified context.
Errors specific to this function:
get_context_children returns a list of context IDs for the children of the specified context. This list can be empty if the context has no children.
query_for_context_group, query_for_context_id and query_for_context_tree will return context-queries which can be used for matching all contexts in a group, the context that matches an ID or contexts in the tree that starts with the specified context. The latter context-query will match the context itself plus all its child contexts, the children of those contexts and so on. The result of these functions should be used with functions that take a context-query as argument.
context_name returns the name of the specified context.
Errors specific to this function:
context_id_for_object returns a context ID for the specified Simics object, ctx_obj, if that has an associated context. In general, processors and some memory spaces usually have contexts associated with them.
Errors specific to this function:
context_has_state returns a boolean that tells whether the
specified context has state or not. That a context has state will mean that
callbacks in the debug_notification will trigger for this
context. The contexts that have state are usually leaf nodes in the OS
Awareness node tree.
object_for_context is used to get a Simics object that matches the context for ctx_id, if such an object exists.
Errors specific to this function:
get_active_processor is used check if a context is active and in that case return the Simics processor object that the node is active on.
Errors specific to this function:
"*". A bad context query will
result in a Debugger_Incorrect_Context_Query error.SIM_INTERFACE(debug_query) {
attr_value_t (*matching_contexts)(conf_object_t *NOTNULL obj,
const char *query);
attr_value_t (*get_context_group)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*get_context_parent)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*get_context_children)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*query_for_context_group)(conf_object_t *NOTNULL obj,
const char *ctx_id);
attr_value_t (*query_for_context_id)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*query_for_context_tree)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*context_name)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*context_id_for_object)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL ctx_obj);
attr_value_t (*object_for_context)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*context_has_state)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*get_active_processor)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
};
#define DEBUG_QUERY_INTERFACE "debug_query"
typedef enum {
Debugger_No_Error = 0,
Debugger_Not_Allowed_In_Execution_Context,
Debugger_Unknown_Context,
Debugger_Not_Supported_For_Context,
Debugger_Context_Does_Not_Have_State,
Debugger_Context_Is_Not_Active,
Debugger_Lookup_Failure,
Debugger_Failed_To_Get_Stack_Frame,
Debugger_Failed_To_Get_PC,
Debugger_Failed_To_Read,
Debugger_Failed_To_Write,
Debugger_Frame_Outside_Of_Known_Stack,
Debugger_Failed_To_Evaluate_Expression,
Debugger_Incorrect_Type,
Debugger_Incorrect_Size,
Debugger_Incorrect_Context_Query,
Debugger_Unknown_Id,
Debugger_Source_Not_Found,
Debugger_File_Not_Found,
Debugger_Unrecognized_File_Format,
Debugger_Unsupported_For_File_Format,
Debugger_Failed_To_Open_File,
Debugger_Not_Relocatable,
Debugger_Segment_Info_Missing,
Debugger_Section_Info_Missing,
Debugger_Segment_Not_Found,
Debugger_Section_Not_Found,
Debugger_Already_Running,
Debugger_Failed_To_Continue,
Debugger_No_Context_For_Object,
Debugger_Invalid_Path,
Debugger_Missing_Object,
Debugger_Unexpected_Error,
Debugger_Step_Interrupted,
} debugger_error_t;