ram_access_subscribe

Description

This interface is used to register callbacks to instrument ram/rom accesses.

The register_access_before_cb method registers a callback that is called before any memory access reached the backing storage in a ram/rom image. This makes it possible to modify the transaction before it reaches its destination. See the documentation of the ram_access_cb_t type for more information. A ram_cb_handle_t pointer is returned as a reference to the callback.

The register_access_after_cb method registers a callback that is called after any memory access has reached the backing storage in a ram/rom image. This makes it possible to modify the transaction after the access is completed. See the documentation of the ram_access_cb_t type for more information. A ram_cb_handle_t pointer is returned as a reference to the callback.

Both of these register callbacks above will receive all types of accesses, read, write, or execute, from any initiator hitting any address range. It is up to the callback to filter the information if needed, e.g., to only trace read accesses. Normally, ram/rom pages can be cached in object using them by using the direct_memory_lookup interface. This caching must be blocked by this interface to allow the callbacks to be called. This has severe impact on simulation speed. However, the following method should be used to allow caching for accesses that the callbacks have no interest in.

The register_access_filter_cb method can be used to register a function callback that allows ram/rom pages to be cached by a user of the direct_memory_lookup interface. If caching is allowed the access may be invisible to the callbacks installed by register_access_before_cb and register_access_after_cb methods above. Even if an access is allowed to be cached it does not mean that it will be, which means that the callbacks can be called anyway.

See the documentation of the access_filter_cb_t type for more information about the callback and how to allow caching. A ram_cb_handle_t pointer is returned as a reference to the callback.

The remove_callback method removes an earlier installed callback. The handle is used to identify the callback to be removed. All register function above returns such handle.

The enable_callback and disable_callback methods temporarily enables and disables a previously installed callback. The handle is used to identify the callback. All register function above returns such handle.

SIM_INTERFACE(ram_access_subscribe) {
        void (*remove_callback)(conf_object_t *NOTNULL obj,
                                ram_cb_handle_t *handle);
        void (*enable_callback)(conf_object_t *NOTNULL obj,
                                ram_cb_handle_t *handle);
        void (*disable_callback)(conf_object_t *NOTNULL obj,
                                 ram_cb_handle_t *handle);
        ram_cb_handle_t *(*register_access_before_cb)(
                conf_object_t *NOTNULL obj,
                conf_object_t *conn_obj,
                ram_access_cb_t cb,
                lang_void *data);
        ram_cb_handle_t *(*register_access_after_cb)(
                conf_object_t *NOTNULL obj,
                conf_object_t *conn_obj,
                ram_access_cb_t cb,
                lang_void *data);
        ram_cb_handle_t *(*register_access_filter_cb)(
                conf_object_t *NOTNULL obj,
                conf_object_t *connection,
                access_filter_cb_t cb,
                lang_void *data);
};

#define RAM_ACCESS_SUBSCRIBE_INTERFACE "ram_access_subscribe"

Execution Context

Global Context for all methods.