5.17.6 Events and trace interface functions

Describes the following functions:

ec_FOO()

Event callback function.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance to which this event is sent. This is not the source of the event, see sInstId. This argument can safely be ignored by the client (callee). This argument is used to route the events to the correct receiving instance.

esId

Type: NumberU64

Event stream id.

fields

Type: Map[String]Value

Object that contains the names and values of all event source fields requested by the eventStream_create() call. This can be a superset of fields requested by the eventStream_create() call. It is guaranteed to contain all fields requested by eventStream_create().

Counter overflow events have an additional implicit overflowTrace field in the fields array in the ec_FOO() callback, with value True, to clearly identify this callback as an overflow event.

sInstId

Type: NumberU64

Source instId. The instance that generated and sent this event.

syncEc

Type: Boolean

Default: False

Optional. Synchronous callback behavior. If this is present and True, this invocation of ec_FOO() blocks the execution of the thread that generated the event. Otherwise the execution of the thread that generated the event resumes before this ec_FOO() call returned. This is only True iff it was set to True in eventStream_create().

time

Type: NumberU64

Simulation time timestamp of the event. This is local simulation time, if available, using the terminology of temporal decoupling, or otherwise the best approximation of simulation time available to the instance. The units of this integer timestamp are called ticks and are defined by the simulation environment. The semantics are identical to simulationTime_get().ticks. Instances must report a timestamp. If they are not able to produce a timestamp, they must set this to simulationTime_get().ticks when generating the event.

Return value

Function has no return value.

eventRingBuffer_clear()

Clears all or part of the event ring buffer of a specific client.

Arguments

clearPercent

Type: NumberU64

Default: 100

Optional. Clear N percent of the bytes in the ring buffer, where N is 0-100. This means that at least N percent of the ring buffer can receive new events. Old events are removed first. The default is 100%, which clears the entire ring buffer. This value is approximate. This function might clear more than the specified percentage if N >= 1. If clearPercent is 0, no events are removed. In this case, this function can be used to change the ring buffer mode.

ecInstId

Type: NumberU64

Instance id of the client instance, that is, the instance that receives the events. This identifies the ring buffer that is affected.

mode

Type: String

Optional. Set the ring buffer to this new mode. If this argument is missing, the mode is unchanged.

Return value

Function has no return value.

eventRingBuffer_init()

Enables a ring buffer that collects events as they occur. The ring buffer is specific to the client receiving the events, not to the instances generating the events.

Arguments

ecInstId

Type: NumberU64

Instance id of the client instance, that is, the instance that receives the events. This identifies the ring buffer that is affected.

mode

Type: String

Defines what happens when a new event arrives at the ring buffer but the ring buffer does not have enough space for the new event, in other words, it is full. It must be one of:

overwrite
The oldest events are silently overwritten by newer events. The old events are discarded and are lost.
send
The contents of the ring buffer are sent to the client instance by calling eventRingBuffer_putBufferedEvents() on the client and then the ring buffer is cleared. No events are lost in this mode.
drop
Events are stored in the ring buffer until it is full. When it is full, new events are silently discarded. This is the default for the ring buffer before eventRingBuffer_init() is called.
sizeBytes

Type: NumberU64

Size of the ring buffer in bytes. At startup, sizeBytes is zero bytes which effectively disables the ring buffer. The stricter of the sizeEvents and sizeBytes limits always takes effect. A useful value for sizeBytes is 1MB which is generally enough for 1000-10000 events.

sizeEvents

Type: NumberU64

Optional. Size of the ring buffer in events. The default is unlimited, in which case sizeBytes takes effect. The stricter of the sizeEvents and sizeBytes limits always takes effect.

Return value

Function has no return value.

Errors

  • E_data_size_error.
  • E_unsupported_mode.

eventRingBuffer_putBufferedEvents()

This function is called on clients that requested to receive buffered event data by calling eventStream_create(ringBuffer=True). It is called each time there is not enough space for a new event in the ring buffer.

Arguments

events

Type: TraceEventData[]

Events from the ring buffer. These events were removed from the ring buffer by the time this function arrives at the client. Each TraceEventData object contains the arguments of an ec_FOO() call, except the instId, most importantly the esId and the fields.

Return value

Function has no return value.

eventRingBuffer_read()

Reads the contents of a ring buffer. Clients can just inspect the ring buffer or can optionally remove the returned events from it.

Arguments

clear

Type: Boolean

Default: False

Optional. Iff present and True, clear the ring buffer after reading all events from it. If False or missing, the ring buffer content is left untouched.

ecInstId

Type: NumberU64

Instance id of the client instance, that is, the instance that receives the events. This identifies the ring buffer that is affected.

Return value

TraceEventData[]

Contents of the ring buffer. This can be empty if the ring buffer is empty or uninitialized, in which case it always drops all events. See TraceEventData.

eventStream_create()

Creates a new event stream and returns its esId.

Arguments

instId

Type: NumberU64

Optional. Opaque number uniquely identifying the target instance. This must be omitted iff targeting a global event source exposed by 'framework.GlobalInstance', for example IRIS_SIMULATION_TIME_EVENT.

counter

Type: Boolean

Optional. Iff True, this event stream counts events and does not emit any ec_FOO() callbacks for events. It can emit counter overflow events. See also the startVal and counterMode arguments. If the event source does not support counter mode, E_counter_mode_not_supported is returned.

counterMode

Type: EventCounterMode

Optional. Only relevant if 'counter==True'. Defines what happens when the counter overflows from 0xffff ffff ffff ffff to 0 and what happens on non-overflow events.

disable

Type: Boolean

Optional. Iff present and True, do not enable event generation. Event generation can later be enabled with eventStream_enable() or with breakpoints that have 'action=eventStream_enable'. If this argument is missing or False, event generation is enabled.

ecFunc

Type: String

Optional. Name of the callback function to call on instance ecInstId. This must start with ec, for event callback. See ec_FOO() for a description of this callback function. The default when not specified is ec_<EventSourceInfo.name>, for example ec_INST for the INST event source. Multiple event streams can send their events to the same callback function. The callback function can demultiplex events based on the event stream id. The client implementation must decide which events are sent to which function.

ecInstId

Type: NumberU64

Callback instId. Events are sent to this instance whenever they occur.

evSrcId

Type: NumberU64

Id of the event source to start tracing. This must be one of the EventSourceInfo.evSrcId values returned by event_getEventSources().

fields

Type: String[]

Optional. List of requested event source fields. The array can be empty, in which case only the event is reported. Omit this argument to conveniently select all event fields. An event producer must generate all the requested fields, and can generate a superset of them, but it must avoid generating unrequested fields that are expensive to generate.

ringBuffer

Type: Boolean

Iff present and True, put events into the ring buffer of client instance ecInstId. Do not call ec_FOO(). If False (default), call ec_FOO() and do not put events into the ring buffer.

Note:

Multiple event streams with different properties can be created by calling eventStream_create() multiple times. Therefore it is possible to put events into the ring buffer and at the same time receive them, potentially with different fields, using ec_FOO(). The behavior of the ring buffer is configured using eventRingBuffer_init().
startVal

Type: NumberU64

Optional. Only relevant if 'counter==True'. Set the start value of the counter. Default is zero. This is useful to trigger overflow events after N events by setting startVal to -N. This is silently ignored if 'counter==False'.

stop

Type: Boolean

Optional. Iff present and True, stop the simulation time for each event while the event stream is enabled. The simulation time is not stopped while the event stream is disabled. An IRIS_SIMULATION_TIME_EVENT is generated for each stopping event. This option implements event breakpoints.

syncEc

Type: Boolean

Optional. Synchronous callback behavior. If this is present and True, the event callback function ec_FOO() blocks the execution of the calling thread in the target instance until the callback function returns. Synchronous callbacks have a performance impact and must only be enabled when necessary. Synchronous callbacks enabled by out-of-process clients over IPC have a disastrous performance impact due to network latencies.

If this is missing or False, the event callback function ec_FOO() might be queued and called from another thread to the simulation thread that encountered the event. In any case, the execution of the calling thread in the target instance resumes before the callback returns. This mode must be used for all normal tracing activity, which usually does not require the synchronous callback behavior.

Return value

NumberU64

Event stream id (esId). This id uniquely identifies the event stream created by this call. It is used to manipulate and stop this event stream. Trace streams are specific to a given ecInstId. Each client has its own private event stream ids.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_source_id.
  • E_unknown_event_field.
  • E_unknown_callback_instance_id.
  • E_syncEc_mode_not_supported.
  • E_counter_mode_not_supported.
  • E_error_creating_event_stream.
  • E_error_enabling_event_stream.

eventStream_destroy()

Stops generating events for a specific event stream and destroys the event stream.

Arguments

instId

Type: NumberU64

Optional. Opaque number uniquely identifying the target instance. This must be omitted or set to 0 iff targeting a global event source exposed by 'framework.GlobalInstance', for example IRIS_SIMULATION_TIME_EVENT.

esId

Type: NumberU64

Id of the event stream to be destroyed. This is the return value of eventStream_create().

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_stream_id.
  • E_error_destroying_event_stream.

eventStream_disable()

Disables an existing event stream. If the event stream is already disabled, this function is silently ignored. The event stream is not destroyed and can be re-enabled later by calling eventStream_enable().

Arguments

instId

Type: NumberU64

Optional. Opaque number uniquely identifying the target instance. This must be omitted iff targeting a global event source exposed by 'framework.GlobalInstance', for example IRIS_SIMULATION_TIME_EVENT.

esId

Type: NumberU64

Id of the event stream to be enabled. This is the return value of eventStream_create().

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_stream_id.

eventStream_enable()

Enables an existing event stream. If the event stream is already enabled, this function is silently ignored.

Arguments

instId

Type: NumberU64

Optional. Opaque number uniquely identifying the target instance. This must be omitted iff targeting a global event source exposed by 'framework.GlobalInstance', for example IRIS_SIMULATION_TIME_EVENT.

esId

Type: NumberU64

Id of the event stream to be enabled. This is the return value of eventStream_create().

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_stream_id.

eventStream_getCounter()

Gets the current event counter value for a specific event stream.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

esId

Type: NumberU64

Event stream id of the counter to be returned. The event stream must have been started with counter=True. Trace streams with counter=False return E_not_a_counter.

Return value

NumberU64

Current counter value of the requested event stream id.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_stream_id.
  • E_not_a_counter.

eventStream_getState()

Queries the current state of the resource associated with an event stream.

Arguments

instId

Type: NumberU64

Optional. Opaque number uniquely identifying the target instance. This must be omitted iff targeting a global event source exposed by 'framework.GlobalInstance', for example IRIS_SIMULATION_TIME_EVENT.

esId

Type: NumberU64

Id of the event stream to be queried. This is the return value of eventStream_create().

Return value

EventState

Object that contains the fields of the event. The fields represent the current state of the resource. See EventState.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_stream_id.
  • E_not_supported_for_event_source.

eventStream_setTraceRanges()

Sets a number of ranges and masks/values for an event stream. Events are only generated when a specific aspect, for example the PC of a core, matches any of the ranges or mask/value tuples.

Arguments

aspect

Type: String

Can be any event source field name, or ':pc':

:pc
Enable tracing if the associated PC is in one of the masked ranges. The PC does not have to be, but can be, a field of the event sources.
any field name
Enable event generation if the value of the field matches any of the masked ranges. The field must have been enabled in the fields argument of eventStream_create(). If aspect is not supported for the selected event source, E_not_supported_for_event_source is returned. If the field was not enabled for the selected event stream, E_unknown_event_field is returned.
esId

Type: NumberU64

Event stream id to be gated by the trace ranges.

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

ranges

Type: NumberU64[]

List of (start, end, mask) tuples. The array length must be dividable by 3. Tracing is enabled iff (general case):

(start & mask) <= (aspect & mask) <= (end & mask)

Standard case: Match against [start, end]:

(start, end, 264-1)

Standard case: Match against mask/value:

(value, value, mask)

An empty array is valid and enables tracing permanently, as if no trace range was specified. Event generation is enabled if one of the specified ranges matches.

Return value

Function has no return value.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_stream_id.
  • E_not_supported_for_event_source.
  • E_unknown_event_field.

event_getEventSource()

Gets information about an event source by its name. This function also returns hidden event sources, if their name is known to the caller.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

name

Type: String

Name of the requested event source.

Return value

EventSourceInfo

Metadata about the requested event source. See EventSourceInfo.

Errors

  • E_unknown_instance_id.
  • E_unknown_event_source.

event_getEventSources()

Retrieves a list of all event sources that are supported by a target instance. This function does not return any hidden event sources. Use event_getEventSource() for this.

Arguments

instId

Type: NumberU64

Opaque number uniquely identifying the target instance.

Return value

EventSourceInfo[]

Zero or more EventSourceInfo Objects containing the metadata for all event sources offered by this instance.

Errors

  • E_unknown_instance_id.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.