3.10.2 Reentrancy

irisHandleMessage() implementations must support reentrancy. It can be called, and therefore reentered, by any number of pair-wise different host threads at the same time.

  • irisHandleMessage() can be called, and therefore reentered, by its own thread. The irisHandleMessage() implementation must support reentrancy by the same thread and must hold mutexes only for short periods, when recursive reentrancy cannot happen, for example only when modifying local data structures and not when forwarding calls, to avoid deadlocks.
  • Recursive mutexes should not generally be used, because mutexes protect invariants and recursive mutexes do not.
  • Calling Iris functions while the simulation is running, for example from asynchronous ec_FOO() callbacks, is allowed. Reading state, for example, using resource_read() or memory_read() is allowed, but the results are random because the model state is fluctuating. It would not be possible to retrieve a consistent state across two or more Iris function calls. By the time a client receives an asynchronous ec_FOO() callback, the model might have progressed, and any observed state is unlikely to be related to the event. A typical use case is to indicate progress to the user by reading and displaying an instruction count.
  • Calling back the simulation from within synchronous ec_FOO() callbacks is much more restricted than calling back from asynchronous ec_FOO() callbacks because Iris calls cannot be scheduled, but must complete while the simulation is blocked in the instance generating the event. This should only be done in very specific circumstances. The documentation of the Events API describes what functionality can be expected from within synchronous ec_FOO() callbacks. Also, not all event sources support synchronous ec_FOO() calls.

    Calling back into the simulation from within a synchronous ec_FOO() callback of instance A has the following implications:

    • If there are multiple parallel simulation threads, reading state from other instances might or might not be synchronous, for example when reading state from a completely unrelated instance that is still progressing. In this case, the Iris call is scheduled onto the other thread and is effectively asynchronous.
    • If there is only a single simulation thread, the whole simulation is blocked by the synchronous event callback. All state is stable, but the state of instance A and all related instances might be inconsistent, depending on the nature of the event.
    • As a guideline, data that is directly related to the event should be taken from the event fields rather than being read directly from the instance. For example, if the event is notifying about a bus fault, the ec_FOO() callback should not try to read fault registers, or registers and memory that are related to the current transaction. Instead, it should interpret the fields transported with the event and it can read unrelated state, for example the PC registers of all cores.
    • Instances indicate that they do not support certain functions, or accessing certain state, while they are blocked in a synchronous event, by returning E_not_supported_while_instance_is_blocked.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.