SIM_add_notifier — add a notifier callback
#include <simics/device-api.h> // in C
// always available in DML
notifier_handle_t *
SIM_add_notifier(
conf_object_t *NOTNULL obj,
notifier_type_t type,
conf_object_t *subscriber,
void (*callback)(conf_object_t *subscriber,
conf_object_t *NOTNULL notifier,
lang_void *data),
lang_void *data);
import simics
simics.SIM_add_notifier(...)
SIM_add_notifier installs a notifier of type type on the object obj.
The subscriber argument should be the object listening for the notification; this object is passed as the first argument to the callback function. The installed callback is automatically removed if the subscriber object is deleted. It is legal to pass NULL in the subscriber argument if there is no object associated with the callback.
The data argument is passed as the last argument to the callback function.
The function returns a handle to the installed notifier or NULL if the notifier type is not supported by the object.
Adding a notifier callback from another notifier callback of the same notifier type and object does not trigger an immediate callback invocation (from the same call to SIM_notify).
Cell Context
SIM_class_has_notifier — query class for notifier
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_class_has_notifier(conf_class_t *NOTNULL cls, notifier_type_t type);
import simics
simics.SIM_class_has_notifier(...)
SIM_class_has_notifier returns true if the class cls supports the notifier specified by type.
Cell Context
SIM_delete_notifier — delete notifier callback
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_delete_notifier(conf_object_t *NOTNULL obj, notifier_handle_t *handle);
import simics
simics.SIM_delete_notifier(...)
SIM_delete_notifier deletes the notifier callback specified by the handle handle.
Notifiers callbacks are deleted automatically when the subscribing object is deleted.
Deleting a notifier callback from another notifier callback of the same notifier type and object may or may not inhibit the last invocation of the deleted callback; this is undefined.
Cell Context
SIM_describe_notifier, SIM_notifier_description — set short description
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_describe_notifier(notifier_type_t type, const char *NOTNULL generic_desc);
const char *
SIM_notifier_description(notifier_type_t type);
import simics
simics.SIM_describe_notifier(...)
simics.SIM_notifier_description(...)
SIM_describe_notifier sets generic_desc as a generic description of the notification specified by the type argument. If the function is called multiple times then the description supplied during the last invocation of the function will be used. The generic description is shown when no description has been provided to the SIM_register_notifier or SIM_register_tracked_notifier functions.
SIM_notifier_description returns a generic description that was set with the SIM_describe_notifier for the notification specified by the type argument, or the empty string if no description has been set.
Global Context
SIM_has_notifier — query object for notifier
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_has_notifier(conf_object_t *NOTNULL obj, notifier_type_t type);
import simics
simics.SIM_has_notifier(...)
SIM_has_notifier returns true if the object obj supports the notifier specified by type.
Cell Context
SIM_notifier_type — get notifier type
#include <simics/device-api.h> // in C
// always available in DML
notifier_type_t
SIM_notifier_type(const char *NOTNULL type);
import simics
simics.SIM_notifier_type(...)
Given a notifier type type specified in the form of a string, return a notifier_type_t identifier which uniquely corresponds to this type.
This function always returns a valid notifier type; if a particular type string has not been seen before, then a new notifier type is created and associated with this string.
The string must consist of printable 7-bit ASCII characters, and by convention it should be expressed as a noun with words separated by dashes.
Cell Context
SIM_notify — trigger notification callbacks
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_notify(conf_object_t *NOTNULL obj, notifier_type_t type);
import simics
simics.SIM_notify(...)
The SIM_notify function triggers all callbacks associated with the notifier notifier which have been installed on the object obj.
The order in which notifier callbacks are invoked is undefined, but the same order every time.
Cell Context
SIM_register_notifier, SIM_register_tracked_notifier — register notifier
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_register_notifier(conf_class_t *NOTNULL cls, notifier_type_t type,
const char *desc);
void
SIM_register_tracked_notifier(conf_class_t *NOTNULL cls, notifier_type_t type,
const char *desc,
void (*subscribed_changed)(conf_object_t *obj,
notifier_type_t type,
bool has_subscribers));
import simics
simics.SIM_register_notifier(...)
simics.SIM_register_tracked_notifier(...)
These functions add the notifier type (returned by the SIM_notifier_type function) to the set of notifiers supported by the class cls. The desc argument can be used to provide any relevant documentation, e.g., information about when the notifier is triggered and how it should be used by the objects that subscribe to it. For uniformity, we suggest formatting the description similar to this one of the “frequency-change” notifier: “Notifier that is triggered when frequency changes. New frequency can be read via the frequency interface of the object.”
SIM_register_notifier is the base registration function. It should be used in most cases.
SIM_register_tracked_notifier accepts an additional argument - the subscribed_changed callback. This callback can be used to track whether any respective notification subscribers are installed. The callback is invoked in following cases:
type’s notifications from obj of cls class, and a new object subscribes to such notifications, i.e., calls SIM_add_notifier. In this case the callback is invoked with the has_subscribers argument equal to true.type’s notifications from obj of cls class unsubscribes from such notifications, either explicitly by a call to SIM_delete_notifier, or implicitly when the subscriber object is deleted. In this case the callback is invoked with the has_subscribers argument equal to false.If the subscribed_changed argument is equal to NULL then it is just ignored.
The subscribed_changed callback is not invoked while the notifier object is being deleted. Thus, if the callback relies on data structures owned by the notifier object, then it is still safe for the object’s destructor to deinitialize these data structures needed by the callback.
It is legal to call SIM_register_notifier multiple times for the same class and the same notifier type. All subsequent invocations done after the notifier was registered are ignored. Calling SIM_register_tracked_notifier multiple times registers multiple subscribed_changed callbacks. All of them will be invoked as it is specified above.
Global Context