5.17 Events and trace API

All Iris events are handled through this interface.

Target instances can expose zero or more event sources. Event sources emit:

  • Trace events, for example INST events for each executed instruction.
  • Simulation events, for example IRIS_BREAKPOINT_HIT events.
  • Other events, for example events defined by a custom GUI.

An instance that produces events is called an event producer, or trace producer. It implements the event_*() functions.

An instance that receives event callbacks is called an event consumer, or trace consumer. It must implement the callbacks for the events it requested, for example ec_INST() and ec_IRIS_BREAKPOINT_HIT().

Instances that do not expose any event sources must either return E_function_not_supported_by_instance for the event_*() functions, or return an empty list of event sources. In practice, however, all instances that implement Iris interfaces that might generate events, must also implement the event interface to expose them, and allow clients to receive them. In particular, instances that support the breakpoint interface or the semihosting interface must implement the event interface.

Most clients only need to call the following functions:

event_getEventSources()
Get a list of all events that an instance supports.
eventStream_create()
Enable receiving the specified event.
eventStream_destroy()
When the events are no longer required.

Alternatively, clients can enable or disable events by calling eventStream_enable() or eventStream_disable(). These functions might provide a performance benefit over eventStream_create() and eventStream_destroy() when repeatedly enabling and disabling the same event stream.

The client implements the event callback functions ec_*(), as needed.

The other functions in this API are more unusual and deal with ringbuffering events, counter events, and reading the state of an event.

$PVLIB_HOME/Iris/Examples/Client/SimpleTraceClient/ contains an example client application that demonstrates how to use this API.

This section contains the following subsections:
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.