bank_instrumentation_subscribe

Description

The bank_instrumentation_subscribe interface is implemented by non-anonymous register banks. The interface may be used to monitor and modify register accesses using callbacks.

Similar to the CPU instrumentation framework, a bank that implements the interface is considered an instrumentation provider and is typically used by an instrumentation tool. The tool registers callbacks using this interface and performs its actions once they are called. Using this interface, tools may also group registered callbacks using connection objects. This can be useful to enforce a certain evaluation order of grouped callbacks.

The bank argument in all methods is the register bank object implementing this interface.

The connection can be used to group registered callbacks together, so that their order may be changed or their registered callbacks be enabled, disabled, or removed collectively. If connection is NULL when registering a callback, the callback is considered anonymous. Anonymous callbacks are evaluated before any other callbacks in the order of creation. See instrumentation_order interface for more details on the callback order.

Each registration method installs a callback which is called at a particular time, before or after, read and write register accesses. Callbacks are not invoked during inquiry accesses. Using the offset and size arguments, a user may install the callback only for a particular range. If offset and size are 0 the callback is installed for the entire bank.

The user_data is used to associate user defined data with every callback. Every time the callback is invoked the data is provided as an argument to the callback.

SIM_INTERFACE(bank_instrumentation_subscribe) {
        bank_callback_handle_t (*register_before_read)(
                conf_object_t *NOTNULL bank,
                conf_object_t *connection,
                uint64 offset,
                uint64 size,
                before_read_callback_t before_read,
                lang_void *user_data);
        bank_callback_handle_t (*register_after_read)(
                conf_object_t *NOTNULL bank,
                conf_object_t *connection,
                uint64 offset,
                uint64 size,
                after_read_callback_t after_read,
                lang_void *user_data);

        bank_callback_handle_t (*register_before_write)(
                conf_object_t *NOTNULL bank,
                conf_object_t *connection,
                uint64 offset,
                uint64 size,
                before_write_callback_t before_write,
                lang_void *user_data);
        bank_callback_handle_t (*register_after_write)(
                conf_object_t *NOTNULL bank,
                conf_object_t *connection,
                uint64 offset,
                uint64 size,
                after_write_callback_t after_write,
                lang_void *user_data);

        void (*remove_callback)(conf_object_t *NOTNULL bank,
                                bank_callback_handle_t callback);

        void (*remove_connection_callbacks)(conf_object_t *NOTNULL bank,
                                            conf_object_t *NOTNULL connection);
        void (*enable_connection_callbacks)(conf_object_t *NOTNULL bank,
                                            conf_object_t *NOTNULL connection);
        void (*disable_connection_callbacks)(conf_object_t *NOTNULL bank,
                                             conf_object_t *NOTNULL connection);

};
#define BANK_INSTRUMENTATION_SUBSCRIBE_INTERFACE \
        "bank_instrumentation_subscribe"

Every function that registers a callback returns a unique handle of type bank_callback_handle_t. The remove_callback method uninstalls the callback associated with the handle. The remove_connection_callbacks uninstalls all callbacks associated with a connection object. Similarly, the enable_connection_callbacks and disable_connection_callbacks methods are used to temporarily enable or disable a group of callbacks.

Callback functions registered through the bank_instrumentation_subscribe interface are called before or after read and write accesses, like so:

typedef void (*before_read_callback_t)(conf_object_t *connection,
                                       bank_before_read_interface_t *access,
                                       bank_access_t *handle,
                                       lang_void *user_data);

typedef void (*after_read_callback_t)(conf_object_t *connection,
                                      bank_after_read_interface_t *access,
                                      bank_access_t *handle,
                                      lang_void *user_data);

typedef void (*before_write_callback_t)(conf_object_t *connection,
                                        bank_before_write_interface_t *access,
                                        bank_access_t *handle,
                                        lang_void *user_data);

typedef void (*after_write_callback_t)(conf_object_t *connection,
                                       bank_after_write_interface_t *access,
                                       bank_access_t *handle,
                                       lang_void *user_data);

The connection is the object used to group the callback with any other callbacks, which may be NULL. The access object provides a number of methods which may be used along with the handle to perform a certain set of actions at the particular point of the access. The user_data is the custom data which was associated with the callback at registration.

For every callback, additional information may be accessed using a specific interface which is passed as a parameter to the callback. See bank_before_read_interface_t, bank_after_read_interface_t, bank_before_write_interface_t, and bank_after_write_interface_t for details.

Execution Context

Cell Context for all methods.