diff options
Diffstat (limited to 'docs/sdei.rst')
| -rw-r--r-- | docs/sdei.rst | 83 |
1 files changed, 46 insertions, 37 deletions
diff --git a/docs/sdei.rst b/docs/sdei.rst index b81e21a9a..531145f87 100644 --- a/docs/sdei.rst +++ b/docs/sdei.rst @@ -48,8 +48,10 @@ execute the registered handler [10]. The client terminates its execution with original EL2 execution [13]. Note that the SDEI interrupt remains active until the client handler completes, at which point EL3 does EOI [12]. -SDEI events can be explicitly dispatched in response to other asynchronous -exceptions. See `Explicit dispatch of events`_. +Other than events bound to interrupts (as depicted in the sequence above, SDEI +events can be explicitly dispatched in response to other exceptions, for +example, upon receiving an *SError* or *Synchronous External Abort*. See +`Explicit dispatch of events`_. The remainder of this document only discusses the design and implementation of SDEI dispatcher in TF-A, and assumes that the reader is familiar with the SDEI @@ -71,7 +73,8 @@ event descriptors. Both macros take 3 arguments: - The event number: this must be a positive 32-bit integer. -- The interrupt number the event is bound to: +- For an event that has a backing interrupt, the interrupt number the event is + bound to: - If it's not applicable to an event, this shall be left as ``0``. @@ -82,6 +85,17 @@ event descriptors. Both macros take 3 arguments: To define event 0, the macro ``SDEI_DEFINE_EVENT_0()`` should be used. This macro takes only one parameter: an SGI number to signal other PEs. +To define an event that's meant to be `explicitly dispatched`__ (i.e., not as a +result of receiving an SDEI interrupt), the macro ``SDEI_EXPLICIT_EVENT()`` +should be used. It accepts two parameters: + +.. __: `Explicit dispatch of events`_ + +- The event number (as above); + +- Event priority: ``SDEI_MAPF_CRITICAL`` or ``SDEI_MAPF_NORMAL``, as described + below. + Once the event descriptor arrays are defined, they should be exported to the SDEI dispatcher using the ``REGISTER_SDEI_MAP()`` macro, passing it the pointers to the private and shared event descriptor arrays, respectively. Note that the @@ -99,6 +113,8 @@ Regarding event descriptors: - Must be bound to a Secure SGI on the platform. +- Explicit events should only be used in the private array. + - Statically bound shared and private interrupts must be bound to shared and private interrupts on the platform, respectively. See the section on `interrupt configuration`__. @@ -132,8 +148,10 @@ Event flags describe the properties of the event. They are bit maps that can be - ``SDEI_MAPF_BOUND``: Marks the event as statically bound to an interrupt. These events cannot be re-bound at runtime. +- ``SDEI_MAPF_NORMAL``: Marks the event as having *Normal* priority. This is + the default priority. + - ``SDEI_MAPF_CRITICAL``: Marks the event as having *Critical* priority. - Without this flag, the event is assumed to have *Normal* priority. Event definition example ------------------------ @@ -150,6 +168,10 @@ Event definition example /* Dynamic private events */ SDEI_PRIVATE_EVENT(100, SDEI_DYN_IRQ, SDEI_MAPF_DYNAMIC), SDEI_PRIVATE_EVENT(101, SDEI_DYN_IRQ, SDEI_MAPF_DYNAMIC) + + /* Events for explicit dispatch */ + SDEI_EXPLICIT_EVENT(2000, SDEI_MAPF_NORMAL); + SDEI_EXPLICIT_EVENT(2000, SDEI_MAPF_CRITICAL); }; /* Shared event mappings */ @@ -211,14 +233,10 @@ this purpose. The API has the following signature: :: - int sdei_dispatch_event(int ev_num, unsigned int preempted_sec_state); - -- The parameter ``ev_num`` is the event number to dispatch; - -- The parameter ``preempted_sec_state`` indicates the context that was - preempted. This must be either ``SECURE`` or ``NON_SECURE``. + int sdei_dispatch_event(int ev_num); -The API returns ``0`` on success, or ``-1`` on failure. +The parameter ``ev_num`` is the event number to dispatch. The API returns ``0`` +on success, or ``-1`` on failure. The following figure depicts a scenario involving explicit dispatch of SDEI event. A commentary is provided below: @@ -231,22 +249,18 @@ unlike in `general SDEI dispatch`_, this doesn't involve interrupt binding, as bound or dynamic events can't be explicitly dispatched (see the section below). At a later point in time, a critical event [#critical-event]_ is trapped into -EL3 [7]. EL3 performs a first-level triage of the event, and decides to dispatch -to a Secure Partition [#secpart]_ for further handling [8]. The dispatch -completes, but intends to involve Non-secure world in further handling, and -therefore decides to explicitly dispatch an event [10] (which the client had -already registered for [1]). The rest of the sequence is similar to that in the -`general SDEI dispatch`_: the requested event is dispatched to the client -(assuming all the conditions are met), and when the handler completes, the -preempted execution resumes. +EL3 [7]. EL3 performs a first-level triage of the event, and a RAS component +assumes further handling [8]. The dispatch completes, but intends to involve +Non-secure world in further handling, and therefore decides to explicitly +dispatch an event [10] (which the client had already registered for [1]). The +rest of the sequence is similar to that in the `general SDEI dispatch`_: the +requested event is dispatched to the client (assuming all the conditions are +met), and when the handler completes, the preempted execution resumes. .. [#critical-event] Examples of critical event are *SError*, *Synchronous External Abort*, *Fault Handling interrupt*, or *Error Recovery interrupt* from one of RAS nodes in the system. -.. [#secpart] Dispatching to Secure Partition involves *Secure Partition - Manager*, which isn't depicted in the sequence. - Conditions for event dispatch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -258,7 +272,8 @@ event to be dispatched: - Event 0 can't be dispatched. -- The event must neither be a dynamic event nor be bound to an interrupt. +- The event must be declared using the ``SDEI_EXPLICIT_EVENT()`` macro + described above. - The event must be private to the PE. @@ -279,28 +294,22 @@ event to be dispatched: Further, the caller should be aware of the following assumptions made by the dispatcher: -- The caller of the API is a component running in EL3; for example, the *Secure - Partition Manager*. +- The caller of the API is a component running in EL3; for example, a RAS + driver. - The requested dispatch will be permitted by the Exception Handling Framework. I.e. the caller must make sure that the requested dispatch has sufficient priority so as not to cause priority level inversion within Exception Handling Framework. -- At the time of the call, the active context is Secure, and it has been saved. - -- Upon returning success, the Non-secure context will be restored and setup for - the event dispatch, and it will be the active context. The Non-secure context - should not be modified further by the caller. +- The caller must be prepared for the SDEI dispatcher to restore the Non-secure + context, and mark that the active context. -- The API returning success only means that the dispatch is scheduled at the - next ``ERET``, and not immediately performed. Also, the caller must be - prepared for this API to return failure and handle accordingly. +- The call will block until the SDEI client completes the event (i.e. when the + client calls either ``SDEI_EVENT_COMPLETE`` or ``SDEI_COMPLETE_AND_RESUME``). -- Upon completing the event (i.e. when the client calls either - ``SDEI_EVENT_COMPLETE`` or ``SDEI_COMPLETE_AND_RESUME``), the preempted - context is resumed (as indicated by the ``preempted_sec_state`` parameter of - the API). +- The caller must be prepared for this API to return failure and handle + accordingly. Porting requirements -------------------- |