docs/components/sdei.rst

4 This document provides an overview of the SDEI dispatcher implementation in
12 about system events. Firmware will first receive the system events by way of
13 asynchronous exceptions and, in response, arranges for the registered handler to
14 execute in the Non-secure EL.
16 Normal world software that interacts with the SDEI dispatcher (makes SDEI
17 requests and receives notifications) is referred to as the *SDEI Client*. A
18 client receives the event notification at the registered handler even when it
19 was executing with exceptions masked. The list of SDEI events available to the
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.
31 As part of initialisation, the SDEI client binds a Non-secure interrupt [1], and
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
34 events on the current PE [7]. This sequence is typical of an SDEI client, but it
37 At a later point in time, when the bound interrupt triggers [9], it's trapped to
38 EL3. The interrupt is handed over to the SDEI dispatcher, which then arranges to
39 execute the registered handler [10]. The client terminates its execution with
40 ``SDEI_EVENT_COMPLETE`` [11], following which the dispatcher resumes the
41 original EL2 execution [13]. Note that the SDEI interrupt remains active until
42 the client handler completes, at which point EL3 does EOI [12].
44 Other than events bound to interrupts, as depicted in the sequence above, SDEI
49 The remainder of this document only discusses the design and implementation of
50 SDEI dispatcher in TF-A, and assumes that the reader is familiar with the SDEI
51 specification, the interfaces, and their requirements.
56 A platform choosing to include the SDEI dispatcher must also define the events
57 available on the platform, along with their attributes.
61 ``SDEI_PRIVATE_EVENT()`` and ``SDEI_SHARED_EVENT()`` macros to populate the
66 -  For an event that has a backing interrupt, the interrupt number the event is
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
79 result of receiving an SDEI interrupt), the macro ``SDEI_EXPLICIT_EVENT()``
87 Once the event descriptor arrays are defined, they should be exported to the
88 SDEI dispatcher using the ``REGISTER_SDEI_MAP()`` macro, passing it the pointers
89 to the private and shared event descriptor arrays, respectively. Note that the
90 ``REGISTER_SDEI_MAP()`` macro must be used in the same file where the arrays are
97    - There must be exactly one descriptor in the private array, and none in the
102    - Must be bound to a Secure SGI on the platform.
104 -  Explicit events should only be used in the private array.
107    private interrupts on the platform, respectively. See the section on
111    takes care of replicating private events for each PE on the platform.
113 -  Both arrays must be sorted in the increasing order of event number.
116 on the platform. The list of events made available to the client, along with
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
130    bound to (or released from) any Non-secure interrupt at runtime via the
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
137    the default priority.
139 -  ``SDEI_MAPF_CRITICAL``: Marks the event as having *Critical* priority.
177 The SDEI dispatcher functions alongside the Exception Handling Framework. This
178 means that the platform must assign priorities to both Normal and Critical SDEI
179 interrupts for the platform:
184    the ``SDEI_MAPF_BOUND`` property), enumerate their properties for the GIC
188    be configured as *Group 0*.  Additionally, on GICv2 systems, the build option
196 The SDEI specification requires that the *physical* SDEI client executes in the
197 highest Non-secure EL implemented on the system. This means that the dispatcher
206 See the function ``sdei_client_el()`` in ``sdei_private.h``.
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
219 this purpose. The API has the following signature:
225 The parameter ``ev_num`` is the event number to dispatch. The API returns ``0``
233 As part of initialisation, the SDEI client registers a handler for a platform
234 event [1], enables the event [3], and unmasks the current PE [5]. Note that,
236 bound or dynamic events can't be explicitly dispatched (see the section below).
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
243 rest of the sequence is similar to that in the `general SDEI dispatch`_: the
244 requested event is dispatched to the client (assuming all the conditions are
245 met), and when the handler completes, the preempted execution resumes.
250 All of the following requirements must be met for the API to return ``0`` and
253 -  SDEI events must be unmasked on the PE. I.e. the client must have called
258 -  The event must be declared using the ``SDEI_EXPLICIT_EVENT()`` macro
261 -  The event must be private to the PE.
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
272       must be outstanding on the PE.
275       outstanding on the PE.
277 Further, the caller should be aware of the following assumptions made by the
280 -  The caller of the API is a component running in EL3; for example, a RAS
283 -  The requested dispatch will be permitted by the Exception Handling Framework.
284    I.e. the caller must make sure that the requested dispatch has sufficient
288 -  The caller must be prepared for the SDEI dispatcher to restore the Non-secure
289    context, and mark that the active context.
291 -  The call will block until the SDEI client completes the event (i.e. when the
300 The porting requirements of the SDEI dispatcher are outlined in the
307 the TF-A SDEI dispatcher.*
309 The SDEI specification requires that event handlers preserve the contents of all
311 written in C: compilers typically adjust the stack frame at the beginning and
312 end of C functions. For example, AArch64 GCC typically produces the following
330 The register ``x29`` is used as frame pointer in the prologue. Because neither a
332 return to the handler, the epilogue never gets executed, and registers ``x29``
333 and ``x30`` (in the case above) are inadvertently corrupted. This violates the
334 SDEI specification, and the normal execution thereafter will result in
337 To work this around, it's advised that the top-level event handlers are
361 Hypervisor/OS. In doing so, it modifies the priority scheme defined by Interrupt
379 by client is architecturally valid, Non-secure client should also ensure the
385 For a given event source, if the events are generated continuously, then NS client
386 may be unusable. To mitigate against this, the Non-secure client must have
387 mechanism in place to remove such interrupt source from the system.
389 One of the examples is a memory region which continuously generates RAS errors.
395 For a dispatched event, it is the client's responsibility to ensure that the
396 handling finishes in finite time and notify the dispatcher through
397 ``SDEI_EVENT_COMPLETE`` or ``SDEI_EVENT_COMPLETE_AND_RESUME``. If the client
398 fails to complete the event handling, it might result in ``UNPREDICTABLE`` behavior
399 in the client and potentially end up in unusable PE.
405 .. [#std-event] Except event 0, which is defined by the SDEI specification as a
410                      Recovery interrupt* from one of RAS nodes in the system.