SIM_hap_add_type — register a new hap type
#include <simics/device-api.h> // in C
// always available in DML
hap_type_t
SIM_hap_add_type(const char *NOTNULL hap,
const char *NOTNULL params,
const char *param_desc,
const char *index,
const char *desc,
int unused);
import simics
simics.SIM_hap_add_type(...)
Creates a run-time defined hap type.
The params parameter specifies the argument that callbacks for this hap is called with; e.g., "s" or "II". The first two arguments are always lang_void * and conf_object_t * respectively, and should not be included in that string. The table below shows which characters may be used, and what their meaning is:
| i | an int |
| I | an int64 (64 bit integer) |
| e | an exception_type_t |
| o | a script specific object; void * in C and any Python object in Python |
| s | a string |
| m | a memory transaction (generic_transaction_t *) |
| c | a configuration object (conf_object_t *) |
param_desc should be a string of space-separated parameter names, or nullptr if params is the empty string. There should be one word in param_desc for each character in params.
index is a string describing the index value for this hap, or nullptr if there is no index value.
desc is a description string for the hap.
SimExc_General Thrown if hap is already defined. However, consequent calls with the same parameters will be successful, and return the same hap type number each time.
The hap type number or -1 on error.
Global Context
SIM_hap_get_name — get hap name by number
#include <simics/device-api.h> // in C
// always available in DML
const char *
SIM_hap_get_name(hap_type_t hap);
import simics
simics.SIM_hap_get_name(...)
Returns the name of hap, or NULL for no such hap. The returned value is a static string that should not be modified or freed by the caller.
Cell Context
SIM_hap_get_number — get hap number by name
#include <simics/device-api.h> // in C
// always available in DML
hap_type_t
SIM_hap_get_number(const char *NOTNULL hap);
import simics
simics.SIM_hap_get_number(...)
Return the runtime number associated with a hap identifier. All haps are listed in the Haps chapter in each reference manual.
SimExc_Lookup Thrown if no hap is associated with name hap.
The hap type number, or 0 on failure.
Global Context
SIM_hap_is_active, SIM_hap_is_active_obj, SIM_hap_is_active_obj_idx — check if hap has callbacks
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_hap_is_active(hap_type_t hap);
bool
SIM_hap_is_active_obj(hap_type_t hap, conf_object_t *NOTNULL obj);
bool
SIM_hap_is_active_obj_idx(hap_type_t hap, conf_object_t *NOTNULL obj,
int64 index);
import simics
simics.SIM_hap_is_active(...)
simics.SIM_hap_is_active_obj(...)
simics.SIM_hap_is_active_obj_idx(...)
Indicate whether the hap has any callback functions to be called when the hap is triggered with the given arguments (object and index). The return value is approximate: if false, no functions would be called; if true, there may be functions to call.
The SIM_hap_is_active function should be avoided; it may be slower and less precise than the other variants.
Cell Context
SIM_hap_occurred — trigger a hap occurrence
#include <simics/device-api.h> // in C
// always available in DML
int
SIM_hap_occurred_always(hap_type_t hap, conf_object_t *obj,
int64 value, attr_value_t *NOTNULL list);
int
SIM_c_hap_occurred_always(hap_type_t hap, conf_object_t *obj,
int64 value, ...);
int
SIM_hap_occurred(hap_type_t hap, conf_object_t *obj,
int64 value, attr_value_t *NOTNULL list);
int
SIM_c_hap_occurred(hap_type_t hap, conf_object_t *obj,
int64 value, ...);
// not available in DML
int
SIM_c_hap_occurred_always_vararg(hap_type_t hap, conf_object_t *obj,
int64 value, va_list ap);
int
SIM_c_hap_occurred_vararg(hap_type_t hap, conf_object_t *obj,
int64 value, va_list ap);
import simics
simics.SIM_hap_occurred_always(...)
simics.SIM_hap_occurred(...)
These functions are used to trigger a hap of type hap. When a hap triggers, all callback functions installed on the hap are called.
The obj argument is the object that the hap triggering is associated with. It may be nullptr for haps that are not associated with an object.
The value argument is used for filtering out callback functions to call based on the index or range that they are installed for. What the index or range corresponds to is hap specific, but could for example be the exception number for the Core_Exception hap.
SIM_hap_occurred() will only call the callbacks once every simulated cycle; if this hap is triggered several times during one cycle, the callbacks will still only be called once. The SIM_hap_occurred_always() function will always call the hap callback functions every time. It is recommended that SIM_hap_occurred_always() is used.
These hap triggering functions return whether or not there were any matching callback function registered on the hap. This can be useful information when one wants a default behavior to be triggered (for example, stopping the simulation) if nobody is listening to the hap.
The hap-specific parameters to the callback function can be passed in various ways: The SIM_c_hap_occurred... functions are only available in C/C++ and are variadic or take a va_list as argument. SIM_hap_occurred and SIM_hap_occurred_always are mainly intended to be used from Python, taking the parameters from an attribute value of list type, or an empty list ([]) if no parameters are passed. In all cases, the number and types of passed parameters must agree with the hap type definition.
The return value is 0 if no callbacks are registered on the hap and non-zero if there are callbacks registered.
SimExc_General Thrown if hap is not a valid hap type or if the values in the list argument are of the wrong type.
Cell Context
SIM_hap_remove_type — remove a hap type
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_hap_remove_type(const char *NOTNULL hap);
import simics
simics.SIM_hap_remove_type(...)
Remove a run-time defined hap type.
Global Context