blob: 52d1ed41b951882fcf5e08b4c22cacb79de885b5 [file] [log] [blame]
Dan Handley610e7e12018-03-01 18:44:00 +00001Trusted Firmware-A interrupt management design guide
2====================================================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
4
5.. section-numbering::
6 :suffix: .
7
8.. contents::
9
10This framework is responsible for managing interrupts routed to EL3. It also
11allows EL3 software to configure the interrupt routing behavior. Its main
12objective is to implement the following two requirements.
13
14#. It should be possible to route interrupts meant to be handled by secure
15 software (Secure interrupts) to EL3, when execution is in non-secure state
16 (normal world). The framework should then take care of handing control of
17 the interrupt to either software in EL3 or Secure-EL1 depending upon the
18 software configuration and the GIC implementation. This requirement ensures
19 that secure interrupts are under the control of the secure software with
20 respect to their delivery and handling without the possibility of
21 intervention from non-secure software.
22
23#. It should be possible to route interrupts meant to be handled by
24 non-secure software (Non-secure interrupts) to the last executed exception
25 level in the normal world when the execution is in secure world at
26 exception levels lower than EL3. This could be done with or without the
27 knowledge of software executing in Secure-EL1/Secure-EL0. The choice of
28 approach should be governed by the secure software. This requirement
29 ensures that non-secure software is able to execute in tandem with the
30 secure software without overriding it.
31
32Concepts
33--------
34
35Interrupt types
36~~~~~~~~~~~~~~~
37
38The framework categorises an interrupt to be one of the following depending upon
39the exception level(s) it is handled in.
40
41#. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or
42 Secure-EL1 depending upon the security state of the current execution
43 context. It is always handled in Secure-EL1.
44
45#. Non-secure interrupt. This type of interrupt can be routed to EL3,
46 Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the
47 current execution context. It is always handled in either Non-secure EL1
48 or EL2.
49
50#. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1
51 depending upon the security state of the current execution context. It is
52 always handled in EL3.
53
54The following constants define the various interrupt types in the framework
55implementation.
56
57::
58
59 #define INTR_TYPE_S_EL1 0
60 #define INTR_TYPE_EL3 1
61 #define INTR_TYPE_NS 2
62
63Routing model
64~~~~~~~~~~~~~
65
66A type of interrupt can be either generated as an FIQ or an IRQ. The target
67exception level of an interrupt type is configured through the FIQ and IRQ bits
68in the Secure Configuration Register at EL3 (``SCR_EL3.FIQ`` and ``SCR_EL3.IRQ``
69bits). When ``SCR_EL3.FIQ``\ =1, FIQs are routed to EL3. Otherwise they are routed
70to the First Exception Level (FEL) capable of handling interrupts. When
71``SCR_EL3.IRQ``\ =1, IRQs are routed to EL3. Otherwise they are routed to the
72FEL. This register is configured independently by EL3 software for each security
73state prior to entry into a lower exception level in that security state.
74
75A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as
76its target exception level for each security state. It is represented by a
77single bit for each security state. A value of ``0`` means that the interrupt
78should be routed to the FEL. A value of ``1`` means that the interrupt should be
79routed to EL3. A routing model is applicable only when execution is not in EL3.
80
81The default routing model for an interrupt type is to route it to the FEL in
82either security state.
83
84Valid routing models
85~~~~~~~~~~~~~~~~~~~~
86
87The framework considers certain routing models for each type of interrupt to be
88incorrect as they conflict with the requirements mentioned in Section 1. The
89following sub-sections describe all the possible routing models and specify
90which ones are valid or invalid. EL3 interrupts are currently supported only
Dan Handley610e7e12018-03-01 18:44:00 +000091for GIC version 3.0 (Arm GICv3) and only the Secure-EL1 and Non-secure interrupt
92types are supported for GIC version 2.0 (Arm GICv2) (See 1.2). The terminology
Douglas Raillardd7c21b72017-06-28 15:23:03 +010093used in the following sub-sections is explained below.
94
95#. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure
96
97#. **TEL3**. Target Exception Level 3. ``0`` when targeted to the FEL. ``1`` when
98 targeted to EL3.
99
100Secure-EL1 interrupts
101^^^^^^^^^^^^^^^^^^^^^
102
103#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
104 secure state. This is a valid routing model as secure software is in
105 control of handling secure interrupts.
106
107#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in secure
108 state. This is a valid routing model as secure software in EL3 can
109 handover the interrupt to Secure-EL1 for handling.
110
111#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
112 non-secure state. This is an invalid routing model as a secure interrupt
113 is not visible to the secure software which violates the motivation behind
Dan Handley610e7e12018-03-01 18:44:00 +0000114 the Arm Security Extensions.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100115
116#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
117 non-secure state. This is a valid routing model as secure software in EL3
118 can handover the interrupt to Secure-EL1 for handling.
119
120Non-secure interrupts
121^^^^^^^^^^^^^^^^^^^^^
122
123#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
124 secure state. This allows the secure software to trap non-secure
125 interrupts, perform its book-keeping and hand the interrupt to the
126 non-secure software through EL3. This is a valid routing model as secure
127 software is in control of how its execution is preempted by non-secure
128 interrupts.
129
130#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in secure
131 state. This is a valid routing model as secure software in EL3 can save
132 the state of software in Secure-EL1/Secure-EL0 before handing the
133 interrupt to non-secure software. This model requires additional
134 coordination between Secure-EL1 and EL3 software to ensure that the
135 former's state is correctly saved by the latter.
136
137#. **CSS=1, TEL3=0**. Interrupt is routed to FEL when execution is in
Jeenu Viswambharan61c5bc72018-01-10 14:56:03 +0000138 non-secure state. This is a valid routing model as a non-secure interrupt
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100139 is handled by non-secure software.
140
141#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
142 non-secure state. This is an invalid routing model as there is no valid
143 reason to route the interrupt to EL3 software and then hand it back to
144 non-secure software for handling.
145
146EL3 interrupts
147^^^^^^^^^^^^^^
148
149#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
150 Secure-EL1/Secure-EL0. This is a valid routing model as secure software
151 in Secure-EL1/Secure-EL0 is in control of how its execution is preempted
152 by EL3 interrupt and can handover the interrupt to EL3 for handling.
153
Jeenu Viswambharanf4194ee2018-01-10 15:00:20 +0000154 However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is
155 invalid as EL3 interrupts are unconditionally routed to EL3, and EL3
Jeenu Viswambharancbb40d52017-10-18 14:30:53 +0100156 interrupts will always preempt Secure EL1/EL0 execution. See `exception
157 handling`__ documentation.
158
159 .. __: exception-handling.rst#interrupt-handling
Jeenu Viswambharanf4194ee2018-01-10 15:00:20 +0000160
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100161#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in
162 Secure-EL1/Secure-EL0. This is a valid routing model as secure software
163 in EL3 can handle the interrupt.
164
165#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
166 non-secure state. This is an invalid routing model as a secure interrupt
167 is not visible to the secure software which violates the motivation behind
Dan Handley610e7e12018-03-01 18:44:00 +0000168 the Arm Security Extensions.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100169
170#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
171 non-secure state. This is a valid routing model as secure software in EL3
172 can handle the interrupt.
173
174Mapping of interrupt type to signal
175~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
176
177The framework is meant to work with any interrupt controller implemented by a
178platform. A interrupt controller could generate a type of interrupt as either an
179FIQ or IRQ signal to the CPU depending upon the current security state. The
180mapping between the type and signal is known only to the platform. The framework
181uses this information to determine whether the IRQ or the FIQ bit should be
182programmed in ``SCR_EL3`` while applying the routing model for a type of
183interrupt. The platform provides this information through the
184``plat_interrupt_type_to_line()`` API (described in the
Dan Handley610e7e12018-03-01 18:44:00 +0000185`Porting Guide`_). For example, on the FVP port when the platform uses an Arm GICv2
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100186interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal
187while Non-secure interrupts are signaled through the IRQ signal. This applies
188when execution is in either security state.
189
190Effect of mapping of several interrupt types to one signal
191^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
192
193It should be noted that if more than one interrupt type maps to a single
194interrupt signal, and if any one of the interrupt type sets **TEL3=1** for a
195particular security state, then interrupt signal will be routed to EL3 when in
196that security state. This means that all the other interrupt types using the
197same interrupt signal will be forced to the same routing model. This should be
198borne in mind when choosing the routing model for an interrupt type.
199
Dan Handley610e7e12018-03-01 18:44:00 +0000200For example, in Arm GICv3, when the execution context is Secure-EL1/
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100201Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ
202signal. So if either one of the interrupt type sets the routing model so
203that **TEL3=1** when **CSS=0**, the FIQ bit in ``SCR_EL3`` will be programmed to
204route the FIQ signal to EL3 when executing in Secure-EL1/Secure-EL0, thereby
205effectively routing the other interrupt type also to EL3.
206
207Assumptions in Interrupt Management Framework
208---------------------------------------------
209
210The framework makes the following assumptions to simplify its implementation.
211
212#. Although the framework has support for 2 types of secure interrupts (EL3
213 and Secure-EL1 interrupt), only interrupt controller architectures
Dan Handley610e7e12018-03-01 18:44:00 +0000214 like Arm GICv3 has architectural support for EL3 interrupts in the form of
215 Group 0 interrupts. In Arm GICv2, all secure interrupts are assumed to be
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100216 handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they
217 cannot be handled in EL3.
218
219#. Interrupt exceptions (``PSTATE.I`` and ``F`` bits) are masked during execution
220 in EL3.
221
Jeenu Viswambharan61c5bc72018-01-10 14:56:03 +0000222#. Interrupt management: the following sections describe how interrupts are
223 managed by the interrupt handling framework. This entails:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100224
Jeenu Viswambharan61c5bc72018-01-10 14:56:03 +0000225 #. Providing an interface to allow registration of a handler and
226 specification of the routing model for a type of interrupt.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100227
Jeenu Viswambharan61c5bc72018-01-10 14:56:03 +0000228 #. Implementing support to hand control of an interrupt type to its
229 registered handler when the interrupt is generated.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100230
231Both aspects of interrupt management involve various components in the secure
232software stack spanning from EL3 to Secure-EL1. These components are described
233in the section 2.1. The framework stores information associated with each type
234of interrupt in the following data structure.
235
236.. code:: c
237
238 typedef struct intr_type_desc {
239 interrupt_type_handler_t handler;
240 uint32_t flags;
241 uint32_t scr_el3[2];
242 } intr_type_desc_t;
243
244The ``flags`` field stores the routing model for the interrupt type in
245bits[1:0]. Bit[0] stores the routing model when execution is in the secure
246state. Bit[1] stores the routing model when execution is in the non-secure
247state. As mentioned in Section 1.2.2, a value of ``0`` implies that the interrupt
248should be targeted to the FEL. A value of ``1`` implies that it should be targeted
249to EL3. The remaining bits are reserved and SBZ. The helper macro
250``set_interrupt_rm_flag()`` should be used to set the bits in the ``flags``
251parameter.
252
253The ``scr_el3[2]`` field also stores the routing model but as a mapping of the
254model in the ``flags`` field to the corresponding bit in the ``SCR_EL3`` for each
255security state.
256
257The framework also depends upon the platform port to configure the interrupt
258controller to distinguish between secure and non-secure interrupts. The platform
259is expected to be aware of the secure devices present in the system and their
260associated interrupt numbers. It should configure the interrupt controller to
261enable the secure interrupts, ensure that their priority is always higher than
262the non-secure interrupts and target them to the primary CPU. It should also
263export the interface described in the `Porting Guide`_ to enable
264handling of interrupts.
265
Dan Handley610e7e12018-03-01 18:44:00 +0000266In the remainder of this document, for the sake of simplicity a Arm GICv2 system
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100267is considered and it is assumed that the FIQ signal is used to generate Secure-EL1
268interrupts and the IRQ signal is used to generate non-secure interrupts in either
269security state. EL3 interrupts are not considered.
270
271Software components
272-------------------
273
274Roles and responsibilities for interrupt management are sub-divided between the
275following components of software running in EL3 and Secure-EL1. Each component is
276briefly described below.
277
Dan Handley610e7e12018-03-01 18:44:00 +0000278#. EL3 Runtime Firmware. This component is common to all ports of TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100279
280#. Secure Payload Dispatcher (SPD) service. This service interfaces with the
281 Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is
282 responsible for switching execution between secure and non-secure states.
283 A switch is triggered by a Secure Monitor Call and it uses the APIs
284 exported by the Context management library to implement this functionality.
285 Switching execution between the two security states is a requirement for
286 interrupt management as well. This results in a significant dependency on
Dan Handley610e7e12018-03-01 18:44:00 +0000287 the SPD service. TF-A implements an example Test Secure Payload Dispatcher
288 (TSPD) service.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100289
290 An SPD service plugs into the EL3 runtime firmware and could be common to
Dan Handley610e7e12018-03-01 18:44:00 +0000291 some ports of TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100292
293#. Secure Payload (SP). On a production system, the Secure Payload corresponds
294 to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the
Dan Handley610e7e12018-03-01 18:44:00 +0000295 SPD service to manage communication with non-secure software. TF-A
296 implements an example secure payload called Test Secure Payload (TSP)
297 which runs only in Secure-EL1.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100298
Dan Handley610e7e12018-03-01 18:44:00 +0000299 A Secure payload implementation could be common to some ports of TF-A,
300 just like the SPD service.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100301
302Interrupt registration
303----------------------
304
305This section describes in detail the role of each software component (see 2.1)
306during the registration of a handler for an interrupt type.
307
308EL3 runtime firmware
309~~~~~~~~~~~~~~~~~~~~
310
311This component declares the following prototype for a handler of an interrupt type.
312
313.. code:: c
314
315 typedef uint64_t (*interrupt_type_handler_t)(uint32_t id,
316 uint32_t flags,
317 void *handle,
318 void *cookie);
319
320The ``id`` is parameter is reserved and could be used in the future for passing
321the interrupt id of the highest pending interrupt only if there is a foolproof
322way of determining the id. Currently it contains ``INTR_ID_UNAVAILABLE``.
323
324The ``flags`` parameter contains miscellaneous information as follows.
325
326#. Security state, bit[0]. This bit indicates the security state of the lower
327 exception level when the interrupt was generated. A value of ``1`` means
328 that it was in the non-secure state. A value of ``0`` indicates that it was
329 in the secure state. This bit can be used by the handler to ensure that
330 interrupt was generated and routed as per the routing model specified
331 during registration.
332
333#. Reserved, bits[31:1]. The remaining bits are reserved for future use.
334
335The ``handle`` parameter points to the ``cpu_context`` structure of the current CPU
336for the security state specified in the ``flags`` parameter.
337
338Once the handler routine completes, execution will return to either the secure
339or non-secure state. The handler routine must return a pointer to
340``cpu_context`` structure of the current CPU for the target security state. On
341AArch64, this return value is currently ignored by the caller as the
342appropriate ``cpu_context`` to be used is expected to be set by the handler
343via the context management library APIs.
344A portable interrupt handler implementation must set the target context both in
345the structure pointed to by the returned pointer and via the context management
346library APIs. The handler should treat all error conditions as critical errors
347and take appropriate action within its implementation e.g. use assertion
348failures.
349
350The runtime firmware provides the following API for registering a handler for a
351particular type of interrupt. A Secure Payload Dispatcher service should use
352this API to register a handler for Secure-EL1 and optionally for non-secure
353interrupts. This API also requires the caller to specify the routing model for
354the type of interrupt.
355
356.. code:: c
357
358 int32_t register_interrupt_type_handler(uint32_t type,
359 interrupt_type_handler handler,
360 uint64_t flags);
361
362The ``type`` parameter can be one of the three interrupt types listed above i.e.
363``INTR_TYPE_S_EL1``, ``INTR_TYPE_NS`` & ``INTR_TYPE_EL3``. The ``flags`` parameter
364is as described in Section 2.
365
366The function will return ``0`` upon a successful registration. It will return
367``-EALREADY`` in case a handler for the interrupt type has already been
368registered. If the ``type`` is unrecognised or the ``flags`` or the ``handler`` are
369invalid it will return ``-EINVAL``.
370
371Interrupt routing is governed by the configuration of the ``SCR_EL3.FIQ/IRQ`` bits
372prior to entry into a lower exception level in either security state. The
373context management library maintains a copy of the ``SCR_EL3`` system register for
374each security state in the ``cpu_context`` structure of each CPU. It exports the
375following APIs to let EL3 Runtime Firmware program and retrieve the routing
376model for each security state for the current CPU. The value of ``SCR_EL3`` stored
377in the ``cpu_context`` is used by the ``el3_exit()`` function to program the
378``SCR_EL3`` register prior to returning from the EL3 exception level.
379
380.. code:: c
381
382 uint32_t cm_get_scr_el3(uint32_t security_state);
383 void cm_write_scr_el3_bit(uint32_t security_state,
384 uint32_t bit_pos,
385 uint32_t value);
386
387``cm_get_scr_el3()`` returns the value of the ``SCR_EL3`` register for the specified
388security state of the current CPU. ``cm_write_scr_el3()`` writes a ``0`` or ``1`` to
389the bit specified by ``bit_pos``. ``register_interrupt_type_handler()`` invokes
390``set_routing_model()`` API which programs the ``SCR_EL3`` according to the routing
391model using the ``cm_get_scr_el3()`` and ``cm_write_scr_el3_bit()`` APIs.
392
393It is worth noting that in the current implementation of the framework, the EL3
394runtime firmware is responsible for programming the routing model. The SPD is
395responsible for ensuring that the routing model has been adhered to upon
396receiving an interrupt.
397
398Secure payload dispatcher
399~~~~~~~~~~~~~~~~~~~~~~~~~
400
401A SPD service is responsible for determining and maintaining the interrupt
402routing model supported by itself and the Secure Payload. It is also responsible
403for ferrying interrupts between secure and non-secure software depending upon
404the routing model. It could determine the routing model at build time or at
405runtime. It must use this information to register a handler for each interrupt
406type using the ``register_interrupt_type_handler()`` API in EL3 runtime firmware.
407
408If the routing model is not known to the SPD service at build time, then it must
409be provided by the SP as the result of its initialisation. The SPD should
410program the routing model only after SP initialisation has completed e.g. in the
411SPD initialisation function pointed to by the ``bl32_init`` variable.
412
413The SPD should determine the mechanism to pass control to the Secure Payload
414after receiving an interrupt from the EL3 runtime firmware. This information
415could either be provided to the SPD service at build time or by the SP at
416runtime.
417
418Test secure payload dispatcher behavior
419~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
420
Jeenu Viswambharan2f40f322018-01-11 14:30:22 +0000421**Note:** where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being
422``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``.
423
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100424The TSPD only handles Secure-EL1 interrupts and is provided with the following
425routing model at build time.
426
427- Secure-EL1 interrupts are routed to EL3 when execution is in non-secure
428 state and are routed to the FEL when execution is in the secure state
429 i.e **CSS=0, TEL3=0** & **CSS=1, TEL3=1** for Secure-EL1 interrupts
430
431- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is zero, the default routing
432 model is used for non-secure interrupts. They are routed to the FEL in
433 either security state i.e **CSS=0, TEL3=0** & **CSS=1, TEL3=0** for
434 Non-secure interrupts.
435
436- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, then the
437 non secure interrupts are routed to EL3 when execution is in secure state
438 i.e **CSS=0, TEL3=1** for non-secure interrupts. This effectively preempts
439 Secure-EL1. The default routing model is used for non secure interrupts in
440 non-secure state. i.e **CSS=1, TEL3=0**.
441
442It performs the following actions in the ``tspd_init()`` function to fulfill the
443requirements mentioned earlier.
444
445#. It passes control to the Test Secure Payload to perform its
446 initialisation. The TSP provides the address of the vector table
447 ``tsp_vectors`` in the SP which also includes the handler for Secure-EL1
448 interrupts in the ``sel1_intr_entry`` field. The TSPD passes control to the TSP at
449 this address when it receives a Secure-EL1 interrupt.
450
451 The handover agreement between the TSP and the TSPD requires that the TSPD
452 masks all interrupts (``PSTATE.DAIF`` bits) when it calls
453 ``tsp_sel1_intr_entry()``. The TSP has to preserve the callee saved general
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100454 purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100455 ``x0-x18`` to enable its C runtime.
456
457#. The TSPD implements a handler function for Secure-EL1 interrupts. This
458 function is registered with the EL3 runtime firmware using the
459 ``register_interrupt_type_handler()`` API as follows
460
461 .. code:: c
462
463 /* Forward declaration */
464 interrupt_type_handler tspd_secure_el1_interrupt_handler;
465 int32_t rc, flags = 0;
466 set_interrupt_rm_flag(flags, NON_SECURE);
467 rc = register_interrupt_type_handler(INTR_TYPE_S_EL1,
468 tspd_secure_el1_interrupt_handler,
469 flags);
470 if (rc)
471 panic();
472
473#. When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, the TSPD
474 implements a handler function for non-secure interrupts. This function is
475 registered with the EL3 runtime firmware using the
476 ``register_interrupt_type_handler()`` API as follows
477
478 .. code:: c
479
480 /* Forward declaration */
481 interrupt_type_handler tspd_ns_interrupt_handler;
482 int32_t rc, flags = 0;
483 set_interrupt_rm_flag(flags, SECURE);
484 rc = register_interrupt_type_handler(INTR_TYPE_NS,
485 tspd_ns_interrupt_handler,
486 flags);
487 if (rc)
488 panic();
489
490Secure payload
491~~~~~~~~~~~~~~
492
493A Secure Payload must implement an interrupt handling framework at Secure-EL1
494(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload
495execution will alternate between the below cases.
496
497#. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt
498 type is targeted to the FEL, then it will be routed to the Secure-EL1
499 exception vector table. This is defined as the **asynchronous mode** of
500 handling interrupts. This mode applies to both Secure-EL1 and non-secure
501 interrupts.
502
503#. In the code where both interrupts are disabled, if an interrupt type is
504 targeted to the FEL, then execution will eventually migrate to the
505 non-secure state. Any non-secure interrupts will be handled as described
506 in the routing model where **CSS=1 and TEL3=0**. Secure-EL1 interrupts
507 will be routed to EL3 (as per the routing model where **CSS=1 and
508 TEL3=1**) where the SPD service will hand them to the SP. This is defined
509 as the **synchronous mode** of handling interrupts.
510
511The interrupt handling framework implemented by the SP should support one or
512both these interrupt handling models depending upon the chosen routing model.
513
514The following list briefly describes how the choice of a valid routing model
515(See 1.2.3) effects the implementation of the Secure-EL1 IHF. If the choice of
516the interrupt routing model is not known to the SPD service at compile time,
517then the SP should pass this information to the SPD service at runtime during
518its initialisation phase.
519
Dan Handley610e7e12018-03-01 18:44:00 +0000520As mentioned earlier, an Arm GICv2 system is considered and it is assumed that
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100521the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal
522is used to generate non-secure interrupts in either security state.
523
524Secure payload IHF design w.r.t secure-EL1 interrupts
525^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
526
527#. **CSS=0, TEL3=0**. If ``PSTATE.F=0``, Secure-EL1 interrupts will be
528 triggered at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1
529 IHF should implement support for handling FIQ interrupts asynchronously.
530
531 If ``PSTATE.F=1`` then Secure-EL1 interrupts will be handled as per the
532 synchronous interrupt handling model. The SP could implement this scenario
533 by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD
534 service during the registration phase. The SPD service would also need to
535 know the state of the system, general purpose and the ``PSTATE`` registers
536 in which it should arrange to return execution to the SP. The SP should
537 provide this information in an implementation defined way during the
538 registration phase if it is not known to the SPD service at build time.
539
540#. **CSS=1, TEL3=1**. Interrupts are routed to EL3 when execution is in
541 non-secure state. They should be handled through the synchronous interrupt
542 handling model as described in 1. above.
543
544#. **CSS=0, TEL3=1**. Secure-EL1 interrupts are routed to EL3 when execution
545 is in secure state. They will not be visible to the SP. The ``PSTATE.F`` bit
546 in Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will
547 call the handler registered by the SPD service for Secure-EL1 interrupts.
548 Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the
549 synchronous interrupt handling model described in 1. above.
550
551Secure payload IHF design w.r.t non-secure interrupts
552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
553
554#. **CSS=0, TEL3=0**. If ``PSTATE.I=0``, non-secure interrupts will be
555 triggered at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1
556 IHF should co-ordinate with the SPD service to transfer execution to the
557 non-secure state where the interrupt should be handled e.g the SP could
558 allocate a function identifier to issue a SMC64 or SMC32 to the SPD
559 service which indicates that the SP execution has been preempted by a
560 non-secure interrupt. If this function identifier is not known to the SPD
561 service at compile time then the SP could provide it during the
562 registration phase.
563
564 If ``PSTATE.I=1`` then the non-secure interrupt will pend until execution
565 resumes in the non-secure state.
566
567#. **CSS=0, TEL3=1**. Non-secure interrupts are routed to EL3. They will not
568 be visible to the SP. The ``PSTATE.I`` bit in Secure-EL1/Secure-EL0 will
569 have not effect. The SPD service should register a non-secure interrupt
570 handler which should save the SP state correctly and resume execution in
571 the non-secure state where the interrupt will be handled. The Secure-EL1
572 IHF does not need to take any action.
573
574#. **CSS=1, TEL3=0**. Non-secure interrupts are handled in the FEL in
575 non-secure state (EL1/EL2) and are not visible to the SP. This routing
576 model does not affect the SP behavior.
577
578A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly
579configured at the interrupt controller by the platform port of the EL3 runtime
580firmware. It should configure any additional Secure-EL1 interrupts which the EL3
581runtime firmware is not aware of through its platform port.
582
583Test secure payload behavior
584~~~~~~~~~~~~~~~~~~~~~~~~~~~~
585
586The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is
587described in Section 2.2.2. It is known to the TSPD service at build time.
588
589The TSP implements an entrypoint (``tsp_sel1_intr_entry()``) for handling Secure-EL1
590interrupts taken in non-secure state and routed through the TSPD service
591(synchronous handling model). It passes the reference to this entrypoint via
592``tsp_vectors`` to the TSPD service.
593
594The TSP also replaces the default exception vector table referenced through the
595``early_exceptions`` variable, with a vector table capable of handling FIQ and IRQ
596exceptions taken at the same (Secure-EL1) exception level. This table is
597referenced through the ``tsp_exceptions`` variable and programmed into the
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100598VBAR_EL1. It caters for the asynchronous handling model.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100599
Dan Handley610e7e12018-03-01 18:44:00 +0000600The TSP also programs the Secure Physical Timer in the Arm Generic Timer block
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100601to raise a periodic interrupt (every half a second) for the purpose of testing
602interrupt management across all the software components listed in 2.1
603
604Interrupt handling
605------------------
606
607This section describes in detail the role of each software component (see
608Section 2.1) in handling an interrupt of a particular type.
609
610EL3 runtime firmware
611~~~~~~~~~~~~~~~~~~~~
612
613The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced
614by the ``runtime_exceptions`` variable as follows.
615
616#. IRQ and FIQ exceptions taken from the current exception level with
617 ``SP_EL0`` or ``SP_EL3`` are reported as irrecoverable error conditions. As
618 mentioned earlier, EL3 runtime firmware always executes with the
619 ``PSTATE.I`` and ``PSTATE.F`` bits set.
620
621#. The following text describes how the IRQ and FIQ exceptions taken from a
622 lower exception level using AArch64 or AArch32 are handled.
623
624When an interrupt is generated, the vector for each interrupt type is
625responsible for:
626
627#. Saving the entire general purpose register context (x0-x30) immediately
628 upon exception entry. The registers are saved in the per-cpu ``cpu_context``
629 data structure referenced by the ``SP_EL3``\ register.
630
631#. Saving the ``ELR_EL3``, ``SP_EL0`` and ``SPSR_EL3`` system registers in the
632 per-cpu ``cpu_context`` data structure referenced by the ``SP_EL3`` register.
633
634#. Switching to the C runtime stack by restoring the ``CTX_RUNTIME_SP`` value
635 from the per-cpu ``cpu_context`` data structure in ``SP_EL0`` and
636 executing the ``msr spsel, #0`` instruction.
637
638#. Determining the type of interrupt. Secure-EL1 interrupts will be signaled
639 at the FIQ vector. Non-secure interrupts will be signaled at the IRQ
640 vector. The platform should implement the following API to determine the
641 type of the pending interrupt.
642
643 .. code:: c
644
645 uint32_t plat_ic_get_interrupt_type(void);
646
647 It should return either ``INTR_TYPE_S_EL1`` or ``INTR_TYPE_NS``.
648
649#. Determining the handler for the type of interrupt that has been generated.
650 The following API has been added for this purpose.
651
652 .. code:: c
653
654 interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type);
655
656 It returns the reference to the registered handler for this interrupt
657 type. The ``handler`` is retrieved from the ``intr_type_desc_t`` structure as
658 described in Section 2. ``NULL`` is returned if no handler has been
659 registered for this type of interrupt. This scenario is reported as an
660 irrecoverable error condition.
661
662#. Calling the registered handler function for the interrupt type generated.
663 The ``id`` parameter is set to ``INTR_ID_UNAVAILABLE`` currently. The id along
664 with the current security state and a reference to the ``cpu_context_t``
665 structure for the current security state are passed to the handler function
666 as its arguments.
667
668 The handler function returns a reference to the per-cpu ``cpu_context_t``
669 structure for the target security state.
670
671#. Calling ``el3_exit()`` to return from EL3 into a lower exception level in
672 the security state determined by the handler routine. The ``el3_exit()``
673 function is responsible for restoring the register context from the
674 ``cpu_context_t`` data structure for the target security state.
675
676Secure payload dispatcher
677~~~~~~~~~~~~~~~~~~~~~~~~~
678
679Interrupt entry
680^^^^^^^^^^^^^^^
681
682The SPD service begins handling an interrupt when the EL3 runtime firmware calls
683the handler function for that type of interrupt. The SPD service is responsible
684for the following:
685
686#. Validating the interrupt. This involves ensuring that the interrupt was
Jeenu Viswambharan61c5bc72018-01-10 14:56:03 +0000687 generated according to the interrupt routing model specified by the SPD
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100688 service during registration. It should use the security state of the
689 exception level (passed in the ``flags`` parameter of the handler) where
690 the interrupt was taken from to determine this. If the interrupt is not
691 recognised then the handler should treat it as an irrecoverable error
692 condition.
693
Jeenu Viswambharan61c5bc72018-01-10 14:56:03 +0000694 An SPD service can register a handler for Secure-EL1 and/or Non-secure
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100695 interrupts. A non-secure interrupt should never be routed to EL3 from
696 from non-secure state. Also if a routing model is chosen where Secure-EL1
697 interrupts are routed to S-EL1 when execution is in Secure state, then a
698 S-EL1 interrupt should never be routed to EL3 from secure state. The handler
699 could use the security state flag to check this.
700
701#. Determining whether a context switch is required. This depends upon the
702 routing model and interrupt type. For non secure and S-EL1 interrupt,
703 if the security state of the execution context where the interrupt was
704 generated is not the same as the security state required for handling
705 the interrupt, a context switch is required. The following 2 cases
706 require a context switch from secure to non-secure or vice-versa:
707
708 #. A Secure-EL1 interrupt taken from the non-secure state should be
709 routed to the Secure Payload.
710
711 #. A non-secure interrupt taken from the secure state should be routed
712 to the last known non-secure exception level.
713
714 The SPD service must save the system register context of the current
715 security state. It must then restore the system register context of the
716 target security state. It should use the ``cm_set_next_eret_context()`` API
717 to ensure that the next ``cpu_context`` to be restored is of the target
718 security state.
719
720 If the target state is secure then execution should be handed to the SP as
721 per the synchronous interrupt handling model it implements. A Secure-EL1
722 interrupt can be routed to EL3 while execution is in the SP. This implies
723 that SP execution can be preempted while handling an interrupt by a
724 another higher priority Secure-EL1 interrupt or a EL3 interrupt. The SPD
725 service should be able to handle this preemption or manage secure interrupt
726 priorities before handing control to the SP.
727
728#. Setting the return value of the handler to the per-cpu ``cpu_context`` if
729 the interrupt has been successfully validated and ready to be handled at a
730 lower exception level.
731
732The routing model allows non-secure interrupts to interrupt Secure-EL1 when in
733secure state if it has been configured to do so. The SPD service and the SP
734should implement a mechanism for routing these interrupts to the last known
735exception level in the non-secure state. The former should save the SP context,
736restore the non-secure context and arrange for entry into the non-secure state
737so that the interrupt can be handled.
738
739Interrupt exit
740^^^^^^^^^^^^^^
741
742When the Secure Payload has finished handling a Secure-EL1 interrupt, it could
743return control back to the SPD service through a SMC32 or SMC64. The SPD service
744should handle this secure monitor call so that execution resumes in the
745exception level and the security state from where the Secure-EL1 interrupt was
746originally taken.
747
748Test secure payload dispatcher Secure-EL1 interrupt handling
749^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
750
751The example TSPD service registers a handler for Secure-EL1 interrupts taken
752from the non-secure state. During execution in S-EL1, the TSPD expects that the
753Secure-EL1 interrupts are handled in S-EL1 by TSP. Its handler
754``tspd_secure_el1_interrupt_handler()`` expects only to be invoked for Secure-EL1
755originating from the non-secure state. It takes the following actions upon being
756invoked.
757
758#. It uses the security state provided in the ``flags`` parameter to ensure
759 that the secure interrupt originated from the non-secure state. It asserts
760 if this is not the case.
761
762#. It saves the system register context for the non-secure state by calling
763 ``cm_el1_sysregs_context_save(NON_SECURE);``.
764
765#. It sets the ``ELR_EL3`` system register to ``tsp_sel1_intr_entry`` and sets the
766 ``SPSR_EL3.DAIF`` bits in the secure CPU context. It sets ``x0`` to
767 ``TSP_HANDLE_SEL1_INTR_AND_RETURN``. If the TSP was preempted earlier by a non
768 secure interrupt during ``yielding`` SMC processing, save the registers that
769 will be trashed, which is the ``ELR_EL3`` and ``SPSR_EL3``, in order to be able
770 to re-enter TSP for Secure-EL1 interrupt processing. It does not need to
771 save any other secure context since the TSP is expected to preserve it
772 (see Section 2.2.2.1).
773
774#. It restores the system register context for the secure state by calling
775 ``cm_el1_sysregs_context_restore(SECURE);``.
776
777#. It ensures that the secure CPU context is used to program the next
778 exception return from EL3 by calling ``cm_set_next_eret_context(SECURE);``.
779
780#. It returns the per-cpu ``cpu_context`` to indicate that the interrupt can
781 now be handled by the SP. ``x1`` is written with the value of ``elr_el3``
782 register for the non-secure state. This information is used by the SP for
783 debugging purposes.
784
785The figure below describes how the interrupt handling is implemented by the TSPD
786when a Secure-EL1 interrupt is generated when execution is in the non-secure
787state.
788
789|Image 1|
790
791The TSP issues an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier to
792signal completion of interrupt handling.
793
794The TSPD service takes the following actions in ``tspd_smc_handler()`` function
795upon receiving an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier:
796
797#. It ensures that the call originated from the secure state otherwise
798 execution returns to the non-secure state with ``SMC_UNK`` in ``x0``.
799
800#. It restores the saved ``ELR_EL3`` and ``SPSR_EL3`` system registers back to
801 the secure CPU context (see step 3 above) in case the TSP had been preempted
802 by a non secure interrupt earlier.
803
804#. It restores the system register context for the non-secure state by
805 calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
806
807#. It ensures that the non-secure CPU context is used to program the next
808 exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``.
809
810#. ``tspd_smc_handler()`` returns a reference to the non-secure ``cpu_context``
811 as the return value.
812
813Test secure payload dispatcher non-secure interrupt handling
814^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
815
816The TSP in Secure-EL1 can be preempted by a non-secure interrupt during
817``yielding`` SMC processing or by a higher priority EL3 interrupt during
Jeenu Viswambharan2f40f322018-01-11 14:30:22 +0000818Secure-EL1 interrupt processing. When ``EL3_EXCEPTION_HANDLING`` is ``0``, only
819non-secure interrupts can cause preemption of TSP since there are no EL3
820interrupts in the system. With ``EL3_EXCEPTION_HANDLING=1`` however, any EL3
821interrupt may preempt Secure execution.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100822
823It should be noted that while TSP is preempted, the TSPD only allows entry into
824the TSP either for Secure-EL1 interrupt handling or for resuming the preempted
825``yielding`` SMC in response to the ``TSP_FID_RESUME`` SMC from the normal world.
826(See Section 3).
827
828The non-secure interrupt triggered in Secure-EL1 during ``yielding`` SMC processing
829can be routed to either EL3 or Secure-EL1 and is controlled by build option
830``TSP_NS_INTR_ASYNC_PREEMPT`` (see Section 2.2.2.1). If the build option is set,
831the TSPD will set the routing model for the non-secure interrupt to be routed to
832EL3 from secure state i.e. **TEL3=1, CSS=0** and registers
833``tspd_ns_interrupt_handler()`` as the non-secure interrupt handler. The
834``tspd_ns_interrupt_handler()`` on being invoked ensures that the interrupt
835originated from the secure state and disables routing of non-secure interrupts
836from secure state to EL3. This is to prevent further preemption (by a non-secure
837interrupt) when TSP is reentered for handling Secure-EL1 interrupts that
838triggered while execution was in the normal world. The
839``tspd_ns_interrupt_handler()`` then invokes ``tspd_handle_sp_preemption()`` for
840further handling.
841
842If the ``TSP_NS_INTR_ASYNC_PREEMPT`` build option is zero (default), the default
843routing model for non-secure interrupt in secure state is in effect
844i.e. **TEL3=0, CSS=0**. During ``yielding`` SMC processing, the IRQ
845exceptions are unmasked i.e. ``PSTATE.I=0``, and a non-secure interrupt will
846trigger at Secure-EL1 IRQ exception vector. The TSP saves the general purpose
847register context and issues an SMC with ``TSP_PREEMPTED`` as the function
848identifier to signal preemption of TSP. The TSPD SMC handler,
849``tspd_smc_handler()``, ensures that the SMC call originated from the
850secure state otherwise execution returns to the non-secure state with
851``SMC_UNK`` in ``x0``. It then invokes ``tspd_handle_sp_preemption()`` for
852further handling.
853
854The ``tspd_handle_sp_preemption()`` takes the following actions upon being
855invoked:
856
857#. It saves the system register context for the secure state by calling
858 ``cm_el1_sysregs_context_save(SECURE)``.
859
860#. It restores the system register context for the non-secure state by
861 calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
862
863#. It ensures that the non-secure CPU context is used to program the next
864 exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``.
865
866#. ``SMC_PREEMPTED`` is set in x0 and return to non secure state after
867 restoring non secure context.
868
869The Normal World is expected to resume the TSP after the ``yielding`` SMC preemption
870by issuing an SMC with ``TSP_FID_RESUME`` as the function identifier (see section 3).
871The TSPD service takes the following actions in ``tspd_smc_handler()`` function
872upon receiving this SMC:
873
874#. It ensures that the call originated from the non secure state. An
875 assertion is raised otherwise.
876
877#. Checks whether the TSP needs a resume i.e check if it was preempted. It
878 then saves the system register context for the non-secure state by calling
879 ``cm_el1_sysregs_context_save(NON_SECURE)``.
880
881#. Restores the secure context by calling
882 ``cm_el1_sysregs_context_restore(SECURE)``
883
884#. It ensures that the secure CPU context is used to program the next
885 exception return from EL3 by calling ``cm_set_next_eret_context(SECURE)``.
886
887#. ``tspd_smc_handler()`` returns a reference to the secure ``cpu_context`` as the
888 return value.
889
890The figure below describes how the TSP/TSPD handle a non-secure interrupt when
891it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the
892``TSP_NS_INTR_ASYNC_PREEMPT`` build flag is 0.
893
894|Image 2|
895
896Secure payload
897~~~~~~~~~~~~~~
898
899The SP should implement one or both of the synchronous and asynchronous
900interrupt handling models depending upon the interrupt routing model it has
901chosen (as described in 2.2.3).
902
903In the synchronous model, it should begin handling a Secure-EL1 interrupt after
904receiving control from the SPD service at an entrypoint agreed upon during build
905time or during the registration phase. Before handling the interrupt, the SP
906should save any Secure-EL1 system register context which is needed for resuming
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100907normal execution in the SP later e.g. ``SPSR_EL1,``\ ELR_EL1\`. After handling the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100908interrupt, the SP could return control back to the exception level and security
909state where the interrupt was originally taken from. The SP should use an SMC32
910or SMC64 to ask the SPD service to do this.
911
912In the asynchronous model, the Secure Payload is responsible for handling
913non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception
914vector table when ``PSTATE.I`` and ``PSTATE.F`` bits are 0. As described earlier,
915when a non-secure interrupt is generated, the SP should coordinate with the SPD
916service to pass control back to the non-secure state in the last known exception
917level. This will allow the non-secure interrupt to be handled in the non-secure
918state.
919
920Test secure payload behavior
921^^^^^^^^^^^^^^^^^^^^^^^^^^^^
922
923The TSPD hands control of a Secure-EL1 interrupt to the TSP at the
924``tsp_sel1_intr_entry()``. The TSP handles the interrupt while ensuring that the
925handover agreement described in Section 2.2.2.1 is maintained. It updates some
926statistics by calling ``tsp_update_sync_sel1_intr_stats()``. It then calls
927``tsp_common_int_handler()`` which.
928
929#. Checks whether the interrupt is the secure physical timer interrupt. It
930 uses the platform API ``plat_ic_get_pending_interrupt_id()`` to get the
931 interrupt number. If it is not the secure physical timer interrupt, then
932 that means that a higher priority interrupt has preempted it. Invoke
933 ``tsp_handle_preemption()`` to handover control back to EL3 by issuing
934 an SMC with ``TSP_PREEMPTED`` as the function identifier.
935
936#. Handles the secure timer interrupt interrupt by acknowledging it using the
937 ``plat_ic_acknowledge_interrupt()`` platform API, calling
938 ``tsp_generic_timer_handler()`` to reprogram the secure physical generic
939 timer and calling the ``plat_ic_end_of_interrupt()`` platform API to signal
940 end of interrupt processing.
941
942The TSP passes control back to the TSPD by issuing an SMC64 with
943``TSP_HANDLED_S_EL1_INTR`` as the function identifier.
944
945The TSP handles interrupts under the asynchronous model as follows.
946
947#. Secure-EL1 interrupts are handled by calling the ``tsp_common_int_handler()``
948 function. The function has been described above.
949
950#. Non-secure interrupts are handled by by calling the ``tsp_common_int_handler()``
951 function which ends up invoking ``tsp_handle_preemption()`` and issuing an
952 SMC64 with ``TSP_PREEMPTED`` as the function identifier. Execution resumes at
953 the instruction that follows this SMC instruction when the TSPD hands
954 control to the TSP in response to an SMC with ``TSP_FID_RESUME`` as the
955 function identifier from the non-secure state (see section 2.3.2.4).
956
957#. .. rubric:: Other considerations
958 :name: other-considerations
959
960Implication of preempted SMC on Non-Secure Software
961---------------------------------------------------
962
963A ``yielding`` SMC call to Secure payload can be preempted by a non-secure
964interrupt and the execution can return to the non-secure world for handling
965the interrupt (For details on ``yielding`` SMC refer `SMC calling convention`_).
966In this case, the SMC call has not completed its execution and the execution
967must return back to the secure payload to resume the preempted SMC call.
968This can be achieved by issuing an SMC call which instructs to resume the
969preempted SMC.
970
971A ``fast`` SMC cannot be preempted and hence this case will not happen for
972a fast SMC call.
973
974In the Test Secure Payload implementation, ``TSP_FID_RESUME`` is designated
975as the resume SMC FID. It is important to note that ``TSP_FID_RESUME`` is a
976``yielding`` SMC which means it too can be be preempted. The typical non
977secure software sequence for issuing a ``yielding`` SMC would look like this,
978assuming ``P.STATE.I=0`` in the non secure state :
979
980.. code:: c
981
982 int rc;
983 rc = smc(TSP_YIELD_SMC_FID, ...); /* Issue a Yielding SMC call */
984 /* The pending non-secure interrupt is handled by the interrupt handler
985 and returns back here. */
986 while (rc == SMC_PREEMPTED) { /* Check if the SMC call is preempted */
987 rc = smc(TSP_FID_RESUME); /* Issue resume SMC call */
988 }
989
990The ``TSP_YIELD_SMC_FID`` is any ``yielding`` SMC function identifier and the smc()
991function invokes a SMC call with the required arguments. The pending non-secure
992interrupt causes an IRQ exception and the IRQ handler registered at the
993exception vector handles the non-secure interrupt and returns. The return value
994from the SMC call is tested for ``SMC_PREEMPTED`` to check whether it is
995preempted. If it is, then the resume SMC call ``TSP_FID_RESUME`` is issued. The
996return value of the SMC call is tested again to check if it is preempted.
997This is done in a loop till the SMC call succeeds or fails. If a ``yielding``
998SMC is preempted, until it is resumed using ``TSP_FID_RESUME`` SMC and
999completed, the current TSPD prevents any other SMC call from re-entering
1000TSP by returning ``SMC_UNK`` error.
1001
1002--------------
1003
Dan Handley610e7e12018-03-01 18:44:00 +00001004*Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001005
1006.. _Porting Guide: ./porting-guide.rst
1007.. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
1008
1009.. |Image 1| image:: diagrams/sec-int-handling.png?raw=true
1010.. |Image 2| image:: diagrams/non-sec-int-handling.png?raw=true