5.17.3 Creating and destroying event streams

eventStream_create() creates a new event stream, which is identified by an event stream id, esId. Event streams are destroyed by eventStream_destroy() or by calling instanceRegistry_unregisterInstance() either explicitly or implicitly.

By default, eventStream_create() enables event generation for the selected event. The ec_<eventName> callback is called on the instance specified by ecInstId, which is usually the client creating the event stream, with the requested event source fields, or a superset of them.

There are internal checks and states associated with an event stream that might suppress event generation:

  • Enable flag. An event stream can be enabled or disabled. This state is controlled by:

    • The disable argument of eventStream_create().
    • The functions eventStream_enable() and eventStream_disable().
    • Trace point breakpoints. These are breakpoints with action=eventStream_enable or eventStream_disable, see the BreakpointAction object.
  • Range check. An enabled event stream might only emit the events that match the ranges for a specific event source field, or the PC. See eventStream_setTraceRanges().
  • Latency. eventStream_create() and eventStream_destroy() do not take effect until the next sync point, in other words, the point at which a stop can be detected. Therefore, event generation might be delayed after calling eventStream_create(), depending on the sync level of the event-producing instance and on the nature of the events, for example INST events, which are generated by instruction execution. Stopping event generation might also be delayed after calling eventStream_destroy(). For more information, see 5.19 Simulation accuracy (sync levels) API.

To stop generating events for a specific event stream that was previously started with eventStream_create(), a client can call either:

  • eventStream_destroy(). The event stream id, esId, is no longer valid after entering this function.
  • instanceRegistry_unregisterInstance(). This unregisters instance X and automatically destroys all event streams that were sent to instance X, that is, event streams that were created using eventStream_create(ecInstId=X).

Use the following guidelines on whether to use eventStream_create() and eventStream_destroy() or eventStream_enable() and eventStream_disable():

  • Use eventStream_create() and eventStream_destroy() to enable and disable events interactively, at a low frequency. These functions might have some latency until events are generated, depending on the current sync level and the nature of the events. Only eventStream_destroy() ensures all event generation overhead is removed. Use these functions if you can, or if you are unsure.
  • Use eventStream_enable() and eventStream_disable() to enable and disable event generation at a high frequency, for example while the simulation is running. Trace points are an example of this. These functions usually have the lowest possible latency until event generation starts or stops. A disabled event stream might have a significant runtime overhead, depending on the frequency of the event. Use these functions only if you must.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.