9.2 Simics API Functions

This section lists Simics API functions that a processor model may need to use beyond what is described in other parts of this document. Simics API SIM_register_clock is described in API Reference Manual.

NAME

VT_check_async_events — check for asynchronous events

SYNOPSIS

bool
VT_check_async_events(void);

DESCRIPTION

Check if any async events are pending and if so, make the current executing object exit in order for them to be handled. Return nonzero if there are pending events.

The Simics platform will check for asynchronous events between invocations of the run method in the execute. If significant time passes between such invocations, which will typically be the case unless there are multiple simulated CPUs that are switched between, then the implementor of execute needs to either call this method or exit pre-maturely from run to allow asynchronous events to be handled. If neither is performed, then interactive performance will suffer as user input would be waiting significant time before being processed.

If only the async event state is requested, the faster VT_async_events_pending should be used instead.

EXECUTION CONTEXT

Cell Context

NAME

VT_new_code_block — inform platform of new code block

SYNOPSIS

void
VT_new_code_block(void *start, size_t len);

DESCRIPTION

This function informs the Simics platform that there is a len bytes block at start that can be executed from. The call should be made before the passed code area is executed from. This information is used by Simics to communicate with systems like Pin or Valgrind that do not automatically detect run-time generated code. If modifications are done to a block, then a new call to this function is needed to inform the platform of that.

EXECUTION CONTEXT

Cell Context

NAME

VT_set_object_clock — set clock association for object

SYNOPSIS

void
VT_set_object_clock(conf_object_t *NOTNULL obj, conf_object_t *clock);

DESCRIPTION

The simulation infrastructure keeps track of clock associations for every object. For most objects, this is initialized through the queue attribute.

An object that is itself a clock needs to call this function to initialize the clock coupling to itself. The call to initialize the coupling should be made from the init method registered for the class in its class_info_t (or init_object if registered using class_data_t).

EXECUTION CONTEXT

Global Context

NAME

VT_clock_frequency_about_to_change — inform before clock frequency change

SYNOPSIS

void
VT_clock_frequency_about_to_change(conf_object_t *obj);

DESCRIPTION

To be called by a clock prior to a clock frequency change, with events and cycles reflecting the frequency before the change.

EXECUTION CONTEXT

Cell Context

NAME

VT_clock_frequency_change — inform after clock frequency change

SYNOPSIS

void
VT_clock_frequency_change(conf_object_t *obj, uint64 cycles_per_second);

DESCRIPTION

To be called by a clock when the clock frequency has changed, with events and cycles reflecting the frequency after the change.

EXECUTION CONTEXT

Cell Context

NAME

VT_stop_event_processing — stop event processing

SYNOPSIS

void
VT_stop_event_processing(conf_object_t *clock);

DESCRIPTION

This method is to be called by a clock when it has received a stop request through the execute interface and the clock is about to return from the run method in the execute interface.

In the future, the simulation framework may keep track of this thus relieving the clock from the duty of having to call this method.

EXECUTION CONTEXT

Cell Context