docs/components/sdei.rst

18 client receives the event notification at the registered handler even when it
20 client are specific to the platform [#std-event]_. See also `Determining client
26 at EL2 and an event dispatch resulting from the triggering of a bound interrupt.
32 the SDEI dispatcher returns a platform dynamic event number [2]. The client then
33 registers a handler for that event [3], enables the event [5], and unmasks all
59 The platform is expected to provide two arrays of event descriptors: one for
62 event descriptors. Both macros take 3 arguments:
64 -  The event number: this must be a positive 32-bit integer.
66 -  For an event that has a backing interrupt, the interrupt number the event is
69    - If it's not applicable to an event, this shall be left as ``0``.
71    - If the event is dynamic, this should be specified as ``SDEI_DYN_IRQ``.
75 To define event 0, the macro ``SDEI_DEFINE_EVENT_0()`` should be used. This
78 To define an event that's meant to be explicitly dispatched (i.e., not as a
82 -  The event number (as above);
87 Once the event descriptor arrays are defined, they should be exported to the
89 to the private and shared event descriptor arrays, respectively. Note that the
93 Regarding event descriptors:
100    - The event should be defined using ``SDEI_DEFINE_EVENT_0()``.
113 -  Both arrays must be sorted in the increasing order of event number.
125 Event flags describe the properties of the event. They are bit maps that can be
129 -  ``SDEI_MAPF_DYNAMIC``: Marks the event as dynamic. Dynamic events can be
133 -  ``SDEI_MAPF_BOUND``: Marks the event as statically bound to an interrupt.
136 -  ``SDEI_MAPF_NORMAL``: Marks the event as having *Normal* priority. This is
139 -  ``SDEI_MAPF_CRITICAL``: Marks the event as having *Critical* priority.
162    /* Shared event mappings */
213 Typically, an SDEI event dispatch is caused by the PE receiving interrupts that
214 are bound to an SDEI event. However, there are cases where the Secure world
215 requires dispatch of an SDEI event as a direct or indirect result of a past
225 The parameter ``ev_num`` is the event number to dispatch. The API returns ``0``
229 event. A commentary is provided below:
234 event [1], enables the event [3], and unmasks the current PE [5]. Note that,
238 At a later point in time, a critical event [#critical-event]_ is trapped into
239 EL3 [7]. EL3 performs a first-level triage of the event, and a RAS component
242 dispatch an event [10] (which the client had already registered for [1]). The
244 requested event is dispatched to the client (assuming all the conditions are
247 Conditions for event dispatch
251 event to be dispatched:
258 -  The event must be declared using the ``SDEI_EXPLICIT_EVENT()`` macro
261 -  The event must be private to the PE.
263 -  The event must have been registered for and enabled.
265 -  A dispatch for the same event must not be outstanding. I.e. it hasn't already
268 -  The priority of the event (either Critical or Normal, as configured by the
291 -  The call will block until the SDEI client completes the event (i.e. when the
303 Note on writing SDEI event handlers
306 *This section pertains to SDEI event handlers in general, not just when using
309 The SDEI specification requires that event handlers preserve the contents of all
310 registers except ``x0`` to ``x17``. This has significance if event handler is
337 To work this around, it's advised that the top-level event handlers are
372 A bound event is an SDEI event that corresponds to a client interrupt.
373 The binding of event is done using ``SDEI_INTERRUPT_BIND`` SMC call to associate
374 an SDEI event with a client interrupt. There is a possibility that a rogue
385 For a given event source, if the events are generated continuously, then NS client
395 For a dispatched event, it is the client's responsibility to ensure that the
398 fails to complete the event handling, it might result in ``UNPREDICTABLE`` behavior
405 .. [#std-event] Except event 0, which is defined by the SDEI specification as a
406                 standard event.
408 .. [#critical-event] Examples of critical events are *SError*, *Synchronous