2.7.5 Plug-in API

Plug-ins can play any role in a system, for example, a debugger, a client, a visualization tool, a trace receiver, a trace generator, a component, a part of a component, or any combination of these.

The plug-in API consists of the following:

  • irisInitPlugin() entry point. This allows the plug-in to make and receive Iris function calls.
  • Iris function calls, made in both directions.
  • Iris initialization phase callbacks. These callbacks have names beginning IRIS_SIM_PHASE_. They allow the plug-in to hook into the initialization and shutdown processes.

Initialization phase callbacks

Initialization phase callbacks allow plug-ins, and any other instances, to hook into the initialization and shutdown stages. Depending on its role, a plug-in might perform initialization in different callbacks, in order to provide information to other parts of the system as early as possible.

The initialization phase callbacks are Iris events, without fields. This is the list of callbacks, in the order in which they are called on an instance:

IRIS_SIM_PHASE_INITIAL_PLUGIN_LOADING_COMPLETE
Called just after all plug-ins have been loaded on simulation startup. This is the earliest point in time at which all plug-ins can discover the presence of all other initial plug-in instances, because plug-ins register themselves as at least one instance in irisInitDso().

Note:

Plug-ins can be loaded and unloaded dynamically afterwards. This callback is only called once, after the initial plug-in loading has completed.
IRIS_SIM_PHASE_INSTANTIATE_ENTER
Called just before IRIS_SIM_PHASE_INSTANTIATE. No component instances have been created yet.
IRIS_SIM_PHASE_INSTANTIATE
Called as part of the system instantiation phase. This is when all component instances are created. Plug-ins can use this step to emulate instantiating themselves at the same time as components.
IRIS_SIM_PHASE_INSTANTIATE_LEAVE
Called just after IRIS_SIM_PHASE_INSTANTIATE, which is just after all component instances have been instantiated. All component instances are usually connected, but are not yet initialized.
IRIS_SIM_PHASE_INIT_ENTER
Called just before IRIS_SIM_PHASE_INIT. Connections to other components are already established, but other components are not yet initialized.
IRIS_SIM_PHASE_INIT
Called as part of the init() phase of all components. A component typically initializes itself here. Other components might or might not be initialized yet.
IRIS_SIM_PHASE_INIT_LEAVE
Called just after IRIS_SIM_PHASE_INIT, which is after init() of all components. Other components are already initialized, in the sense of init(). This is the earliest point when all trace sources of all components can be discovered.
IRIS_SIM_PHASE_BEFORE_END_OF_ELABORATION
Called just after IRIS_SIM_PHASE_INIT_LEAVE. In SystemC contexts, this is called in before_end_of_elaboration(). This is also called in non-SystemC contexts.
IRIS_SIM_PHASE_END_OF_ELABORATION
Called just after IRIS_SIM_PHASE_BEFORE_END_OF_ELABORATION. In SystemC contexts, this is called in end_of_elaboration(). This is also called in non-SystemC contexts.
IRIS_SIM_PHASE_INITIAL_RESET_ENTER
Called just before IRIS_SIM_INITIAL_PHASE_RESET.
IRIS_SIM_PHASE_INITIAL_RESET
Called as part of the the first reset() phase of components. This is only called once, after init().
IRIS_SIM_PHASE_INITIAL_RESET_LEAVE
Called just after IRIS_SIM_PHASE_INITIAL_RESET.
IRIS_SIM_PHASE_START_OF_SIMULATION
Called just after IRIS_SIM_PHASE_INITIAL_RESET_LEAVE. In SystemC contexts, this is called in start_of_simulation(). This is also called in non-SystemC contexts.
IRIS_SIM_PHASE_RESET_ENTER
Called just before IRIS_SIM_PHASE_RESET.
IRIS_SIM_PHASE_RESET
Called as part of the the reset() phase of components. This is called for every simulation reset, not hardware reset, after the first one. See IRIS_SIM_PHASE_INITIAL_RESET for the first invocation of reset() after init(). To achieve the semantics of component reset(), combine IRIS_SIM_PHASE_INITIAL_RESET and IRIS_SIM_PHASE_RESET.
IRIS_SIM_PHASE_RESET_LEAVE
Called just after IRIS_SIM_PHASE_RESET.
IRIS_SIM_PHASE_END_OF_SIMULATION
Called just before IRIS_SIM_PHASE_TERMINATE_ENTER. In SystemC contexts, this is called in end_of_simulation(). This is also called in non-SystemC contexts.
IRIS_SIM_PHASE_TERMINATE_ENTER
Called just before IRIS_SIM_PHASE_TERMINATE. This is the last chance to access components before the terminate() phase is called on them. This is generally the last chance to access components in a safe way.
IRIS_SIM_PHASE_TERMINATE
Called as part of the terminate() phase of components.
IRIS_SIM_PHASE_TERMINATE_LEAVE
Called just after IRIS_SIM_PHASE_TERMINATE. As components might already have freed their resources, it is not safe to access other components from this callback.

Plug-ins and callbacks

Different types of plug-in must do work in different callbacks.

Trace plug-ins and debugger plug-ins

To receive trace events from components, a trace plug-in typically does work in the following callbacks:

IRIS_SIM_PHASE_INIT_LEAVE
This corresponds to the MTI registerSimulation() callback. The plug-in can discover all trace sources here.
IRIS_SIM_PHASE_INITIAL_RESET_LEAVE
Here, all components are properly initialized and their register values are properly reset.
IRIS_SIM_PHASE_TERMINATE_ENTER
This is the last chance to read the final trace state of components.

Trace plug-ins should generally not do any work in the following callbacks because it is unclear which part of the observed components have completed these stages and which have not:

  • IRIS_SIM_PHASE_INSTANTIATE.
  • IRIS_SIM_PHASE_INIT.
  • IRIS_SIM_PHASE_RESET.
  • IRIS_SIM_PHASE_TERMINATE.

To provide debugger-like functionality or to simply observe the state of components, a plug-in typically does work in the same callbacks as trace plug-ins.

Special plug-ins

A plug-in can discover other plug-ins that were loaded at startup in IRIS_SIM_PHASE_INITIAL_PLUGIN_LOADING_COMPLETE, for example to print a list of all plug-in instances.

Note:

The behavior of a plug-in should not depend on other plug-ins because this violates user expectations. Plug-ins should not influence each other, unless this influence is their main purpose.

SystemC simulation phases

The Iris initialization phase callbacks occur during the following SystemC simulation phases:

Table 2-4 Iris initialization phase callbacks and SystemC simulation phases

Iris initialization phase callback SystemC simulation phase
IRIS_SIM_PHASE_INITIAL_PLUGIN_LOADING_COMPLETE sc_main(), before sc_start()
IRIS_SIM_PHASE_INSTANTIATE_ENTER before_end_of_elaboration()
IRIS_SIM_PHASE_INSTANTIATE
IRIS_SIM_PHASE_INSTANTIATE_LEAVE
IRIS_SIM_PHASE_INIT_ENTER
IRIS_SIM_PHASE_INIT
IRIS_SIM_PHASE_INIT_LEAVE
IRIS_SIM_PHASE_BEFORE_END_OF_ELABORATION
IRIS_SIM_PHASE_END_OF_ELABORATION end_of_elaboration()
IRIS_SIM_PHASE_INITIAL_RESET_ENTER start_of_simulation()
IRIS_SIM_PHASE_INITIAL_RESET
IRIS_SIM_PHASE_INITIAL_RESET_LEAVE
IRIS_SIM_PHASE_START_OF_SIMULATION
IRIS_SIM_PHASE_RESET_ENTER sc_start(), after start_of_simulation(), and before end_of_simulation()
IRIS_SIM_PHASE_RESET
IRIS_SIM_PHASE_RESET_LEAVE
IRIS_SIM_PHASE_END_OF_SIMULATION end_of_simulation()
IRIS_SIM_PHASE_TERMINATE_ENTER
IRIS_SIM_PHASE_TERMINATE
IRIS_SIM_PHASE_TERMINATE_LEAVE
Non-ConfidentialPDF file icon PDF version101196_0100_00_en
Copyright © 2018 Arm Limited or its affiliates. All rights reserved.