Haps

Name

SIM_get_all_hap_types — get list of all hap types

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

attr_value_t
SIM_get_all_hap_types();

Python

import simics

simics.SIM_get_all_hap_types(...)

Description

Get a list of the names of all registered hap types.

Return Value

Attribute list of strings.

Execution Context

Global Context

See Also

SIM_hap_get_number, SIM_hap_add_type

Name

SIM_hap_add_callback — install callback on a hap

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

hap_handle_t
SIM_hap_add_callback(const char *NOTNULL hap,
                     NOTNULL obj_hap_func_t func,
                     lang_void *user_data);

hap_handle_t
SIM_hap_add_callback_index(const char *NOTNULL hap,
                           NOTNULL obj_hap_func_t func,
                           lang_void *user_data,
                           int64 index);

hap_handle_t
SIM_hap_add_callback_range(const char *NOTNULL hap,
                           NOTNULL obj_hap_func_t func,
                           lang_void *user_data,
                           int64 start,
                           int64 end);

hap_handle_t
SIM_hap_add_callback_obj(const char *NOTNULL hap,
                         conf_object_t *NOTNULL obj,
                         int flags,
                         NOTNULL obj_hap_func_t func,
                         lang_void *user_data);

hap_handle_t
SIM_hap_add_callback_obj_index(const char *NOTNULL hap,
                               conf_object_t *NOTNULL obj,
                               int flags,
                               NOTNULL obj_hap_func_t func,
                               lang_void *user_data,
                               int64 index);

hap_handle_t
SIM_hap_add_callback_obj_range(const char *NOTNULL hap,
                               conf_object_t *NOTNULL obj,
                               int flags,
                               NOTNULL obj_hap_func_t func,
                               lang_void *user_data,
                               int64 start,
                               int64 end);

typedef int hap_handle_t;

Python

import simics

simics.SIM_hap_add_callback(...)
simics.SIM_hap_add_callback_index(...)
simics.SIM_hap_add_callback_range(...)
simics.SIM_hap_add_callback_obj(...)
simics.SIM_hap_add_callback_obj_index(...)
simics.SIM_hap_add_callback_obj_range(...)

Description

Registers a function, pointed to by func, to be called when hap occurs for object obj. If a hap add function that does not have the obj argument is used, then the callback function will be called regardless of what object that triggers the hap. The user_data argument is the callback-specific data, and it will be passed as first argument to the installed callback function.

Some hap add functions also take a flags argument. This flag is currently Simics internal and should be set to 0.

The hap callback functions should not return any data. In C, the functions are declared to have a void return type and in Python, any return value is ignored. Since callback functions with different arguments may be installed using the same API function, the compiler may warn about a type mismatch. The solution is to cast the callback function pointer to the obj_hap_func_t type.

The callback will be called in Cell Context, unless the documentation for the hap states otherwise.

In hap functions, the execution can be interrupted by calling SIM_break_simulation. If a frontend or Python exception is raised, an error message will be printed including a stack trace if the callback is written in Python.

The _index_ and _range_ versions will install callbacks that only trigger for a specified index, or range of indices. The index is specific for each hap type, see the hap documentation. The index and range must be non-negative and the end of the range must not be lower than the start.

Return Value

The return value is a hap callback handle (identifier) of the type hap_handle_t, or -1 on error. This handle can be used to remove the installed callback with SIM_hap_delete_callback_id.

Exceptions

SimExc_Lookup Thrown if the hap does not exist.

SimExc_Attribute Thrown if the index is negative or if the range is negative in value or size.

Execution Context

Cell Context for hap callbacks tied to an object, and Global Context for hap callbacks not tied to an object. An exception is made for callbacks on Core_Breakpoint_Memop, which can be installed with SIM_hap_add_callback_index even in Cell Context.

Name

SIM_hap_delete_callback — delete installed hap callback

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

void
SIM_hap_delete_callback(const char *NOTNULL hap,
                        NOTNULL obj_hap_func_t func, lang_void *user_data);

void
SIM_hap_delete_callback_obj(const char *NOTNULL hap,
                            conf_object_t *NOTNULL obj,
                            NOTNULL obj_hap_func_t func, lang_void *user_data);

void
SIM_hap_delete_callback_id(const char *NOTNULL hap, hap_handle_t handle);

void
SIM_hap_delete_callback_obj_id(const char *NOTNULL hap,
                               conf_object_t *NOTNULL obj, hap_handle_t handle);

Python

import simics

simics.SIM_hap_delete_callback(...)
simics.SIM_hap_delete_callback_obj(...)
simics.SIM_hap_delete_callback_id(...)
simics.SIM_hap_delete_callback_obj_id(...)

Description

Removes a callback for a hap type specified by the hap argument.

The SIM_hap_delete_callback_obj... functions will remove a callback that is installed on the specified object obj.

SIM_hap_delete_callback removes a callback not associated with any object, with the callback function func and the same user_data.

The SIM_hap_delete_callback_..._id functions take a hap handle argument instead, as returned by the SIM_hap_add_callback... functions.

These functions will trigger the Core_Hap_Callback_Removed hap for each removed callback.

Exceptions

SimExc_Lookup Thrown if the specified hap does not exist.

Execution Context

Cell Context for callbacks tied to an object. Global Context for callbacks not tied to an object.