1Trusted Firmware-A interrupt management design guide 2==================================================== 3 4 5 6 7.. contents:: 8 9This framework is responsible for managing interrupts routed to EL3. It also 10allows EL3 software to configure the interrupt routing behavior. Its main 11objective is to implement the following two requirements. 12 13#. It should be possible to route interrupts meant to be handled by secure 14 software (Secure interrupts) to EL3, when execution is in non-secure state 15 (normal world). The framework should then take care of handing control of 16 the interrupt to either software in EL3 or Secure-EL1 depending upon the 17 software configuration and the GIC implementation. This requirement ensures 18 that secure interrupts are under the control of the secure software with 19 respect to their delivery and handling without the possibility of 20 intervention from non-secure software. 21 22#. It should be possible to route interrupts meant to be handled by 23 non-secure software (Non-secure interrupts) to the last executed exception 24 level in the normal world when the execution is in secure world at 25 exception levels lower than EL3. This could be done with or without the 26 knowledge of software executing in Secure-EL1/Secure-EL0. The choice of 27 approach should be governed by the secure software. This requirement 28 ensures that non-secure software is able to execute in tandem with the 29 secure software without overriding it. 30 31Concepts 32-------- 33 34Interrupt types 35~~~~~~~~~~~~~~~ 36 37The framework categorises an interrupt to be one of the following depending upon 38the exception level(s) it is handled in. 39 40#. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or 41 Secure-EL1 depending upon the security state of the current execution 42 context. It is always handled in Secure-EL1. 43 44#. Non-secure interrupt. This type of interrupt can be routed to EL3, 45 Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the 46 current execution context. It is always handled in either Non-secure EL1 47 or EL2. 48 49#. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1 50 depending upon the security state of the current execution context. It is 51 always handled in EL3. 52 53The following constants define the various interrupt types in the framework 54implementation. 55 56:: 57 58 #define INTR_TYPE_S_EL1 0 59 #define INTR_TYPE_EL3 1 60 #define INTR_TYPE_NS 2 61 62Routing model 63~~~~~~~~~~~~~ 64 65A type of interrupt can be either generated as an FIQ or an IRQ. The target 66exception level of an interrupt type is configured through the FIQ and IRQ bits 67in the Secure Configuration Register at EL3 (``SCR_EL3.FIQ`` and ``SCR_EL3.IRQ`` 68bits). When ``SCR_EL3.FIQ``\ =1, FIQs are routed to EL3. Otherwise they are routed 69to the First Exception Level (FEL) capable of handling interrupts. When 70``SCR_EL3.IRQ``\ =1, IRQs are routed to EL3. Otherwise they are routed to the 71FEL. This register is configured independently by EL3 software for each security 72state prior to entry into a lower exception level in that security state. 73 74A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as 75its target exception level for each security state. It is represented by a 76single bit for each security state. A value of ``0`` means that the interrupt 77should be routed to the FEL. A value of ``1`` means that the interrupt should be 78routed to EL3. A routing model is applicable only when execution is not in EL3. 79 80The default routing model for an interrupt type is to route it to the FEL in 81either security state. 82 83Valid routing models 84~~~~~~~~~~~~~~~~~~~~ 85 86The framework considers certain routing models for each type of interrupt to be 87incorrect as they conflict with the requirements mentioned in Section 1. The 88following sub-sections describe all the possible routing models and specify 89which ones are valid or invalid. EL3 interrupts are currently supported only 90for GIC version 3.0 (Arm GICv3) and only the Secure-EL1 and Non-secure interrupt 91types are supported for GIC version 2.0 (Arm GICv2) (see `Assumptions in 92Interrupt Management Framework`_). The terminology used in the following 93sub-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 114 the Arm Security Extensions. 115 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 138 non-secure state. This is a valid routing model as a non-secure interrupt 139 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 154 However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is 155 invalid as EL3 interrupts are unconditionally routed to EL3, and EL3 156 interrupts will always preempt Secure EL1/EL0 execution. See `exception 157 handling`__ documentation. 158 159 .. __: exception-handling.rst#interrupt-handling 160 161#. **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 168 the Arm Security Extensions. 169 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 185`Porting Guide`_). For example, on the FVP port when the platform uses an Arm GICv2 186interrupt 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 200For example, in Arm GICv3, when the execution context is Secure-EL1/ 201Secure-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 214 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 216 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 222#. Interrupt management: the following sections describe how interrupts are 223 managed by the interrupt handling framework. This entails: 224 225 #. Providing an interface to allow registration of a handler and 226 specification of the routing model for a type of interrupt. 227 228 #. Implementing support to hand control of an interrupt type to its 229 registered handler when the interrupt is generated. 230 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 `Software components`_. The framework stores information 234associated with each type of 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 `Routing model`_, a value of ``0`` implies that 248the interrupt should be targeted to the FEL. A value of ``1`` implies that it 249should be targeted to EL3. The remaining bits are reserved and SBZ. The helper 250macro ``set_interrupt_rm_flag()`` should be used to set the bits in the 251``flags`` parameter. 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 266In the remainder of this document, for the sake of simplicity a Arm GICv2 system 267is 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 278#. EL3 Runtime Firmware. This component is common to all ports of TF-A. 279 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 287 the SPD service. TF-A implements an example Test Secure Payload Dispatcher 288 (TSPD) service. 289 290 An SPD service plugs into the EL3 runtime firmware and could be common to 291 some ports of TF-A. 292 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 295 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. 298 299 A Secure payload implementation could be common to some ports of TF-A, 300 just like the SPD service. 301 302Interrupt registration 303---------------------- 304 305This section describes in detail the role of each software component (see 306`Software components`_) during the registration of a handler for an interrupt 307type. 308 309EL3 runtime firmware 310~~~~~~~~~~~~~~~~~~~~ 311 312This component declares the following prototype for a handler of an interrupt type. 313 314.. code:: c 315 316 typedef uint64_t (*interrupt_type_handler_t)(uint32_t id, 317 uint32_t flags, 318 void *handle, 319 void *cookie); 320 321The ``id`` is parameter is reserved and could be used in the future for passing 322the interrupt id of the highest pending interrupt only if there is a foolproof 323way of determining the id. Currently it contains ``INTR_ID_UNAVAILABLE``. 324 325The ``flags`` parameter contains miscellaneous information as follows. 326 327#. Security state, bit[0]. This bit indicates the security state of the lower 328 exception level when the interrupt was generated. A value of ``1`` means 329 that it was in the non-secure state. A value of ``0`` indicates that it was 330 in the secure state. This bit can be used by the handler to ensure that 331 interrupt was generated and routed as per the routing model specified 332 during registration. 333 334#. Reserved, bits[31:1]. The remaining bits are reserved for future use. 335 336The ``handle`` parameter points to the ``cpu_context`` structure of the current CPU 337for the security state specified in the ``flags`` parameter. 338 339Once the handler routine completes, execution will return to either the secure 340or non-secure state. The handler routine must return a pointer to 341``cpu_context`` structure of the current CPU for the target security state. On 342AArch64, this return value is currently ignored by the caller as the 343appropriate ``cpu_context`` to be used is expected to be set by the handler 344via the context management library APIs. 345A portable interrupt handler implementation must set the target context both in 346the structure pointed to by the returned pointer and via the context management 347library APIs. The handler should treat all error conditions as critical errors 348and take appropriate action within its implementation e.g. use assertion 349failures. 350 351The runtime firmware provides the following API for registering a handler for a 352particular type of interrupt. A Secure Payload Dispatcher service should use 353this API to register a handler for Secure-EL1 and optionally for non-secure 354interrupts. This API also requires the caller to specify the routing model for 355the type of interrupt. 356 357.. code:: c 358 359 int32_t register_interrupt_type_handler(uint32_t type, 360 interrupt_type_handler handler, 361 uint64_t flags); 362 363The ``type`` parameter can be one of the three interrupt types listed above i.e. 364``INTR_TYPE_S_EL1``, ``INTR_TYPE_NS`` & ``INTR_TYPE_EL3``. The ``flags`` parameter 365is as described in Section 2. 366 367The function will return ``0`` upon a successful registration. It will return 368``-EALREADY`` in case a handler for the interrupt type has already been 369registered. If the ``type`` is unrecognised or the ``flags`` or the ``handler`` are 370invalid it will return ``-EINVAL``. 371 372Interrupt routing is governed by the configuration of the ``SCR_EL3.FIQ/IRQ`` bits 373prior to entry into a lower exception level in either security state. The 374context management library maintains a copy of the ``SCR_EL3`` system register for 375each security state in the ``cpu_context`` structure of each CPU. It exports the 376following APIs to let EL3 Runtime Firmware program and retrieve the routing 377model for each security state for the current CPU. The value of ``SCR_EL3`` stored 378in the ``cpu_context`` is used by the ``el3_exit()`` function to program the 379``SCR_EL3`` register prior to returning from the EL3 exception level. 380 381.. code:: c 382 383 uint32_t cm_get_scr_el3(uint32_t security_state); 384 void cm_write_scr_el3_bit(uint32_t security_state, 385 uint32_t bit_pos, 386 uint32_t value); 387 388``cm_get_scr_el3()`` returns the value of the ``SCR_EL3`` register for the specified 389security state of the current CPU. ``cm_write_scr_el3()`` writes a ``0`` or ``1`` to 390the bit specified by ``bit_pos``. ``register_interrupt_type_handler()`` invokes 391``set_routing_model()`` API which programs the ``SCR_EL3`` according to the routing 392model using the ``cm_get_scr_el3()`` and ``cm_write_scr_el3_bit()`` APIs. 393 394It is worth noting that in the current implementation of the framework, the EL3 395runtime firmware is responsible for programming the routing model. The SPD is 396responsible for ensuring that the routing model has been adhered to upon 397receiving an interrupt. 398 399.. _spd-int-registration: 400 401Secure payload dispatcher 402~~~~~~~~~~~~~~~~~~~~~~~~~ 403 404A SPD service is responsible for determining and maintaining the interrupt 405routing model supported by itself and the Secure Payload. It is also responsible 406for ferrying interrupts between secure and non-secure software depending upon 407the routing model. It could determine the routing model at build time or at 408runtime. It must use this information to register a handler for each interrupt 409type using the ``register_interrupt_type_handler()`` API in EL3 runtime firmware. 410 411If the routing model is not known to the SPD service at build time, then it must 412be provided by the SP as the result of its initialisation. The SPD should 413program the routing model only after SP initialisation has completed e.g. in the 414SPD initialisation function pointed to by the ``bl32_init`` variable. 415 416The SPD should determine the mechanism to pass control to the Secure Payload 417after receiving an interrupt from the EL3 runtime firmware. This information 418could either be provided to the SPD service at build time or by the SP at 419runtime. 420 421Test secure payload dispatcher behavior 422~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 423 424**Note:** where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being 425``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``. 426 427The TSPD only handles Secure-EL1 interrupts and is provided with the following 428routing model at build time. 429 430- Secure-EL1 interrupts are routed to EL3 when execution is in non-secure 431 state and are routed to the FEL when execution is in the secure state 432 i.e **CSS=0, TEL3=0** & **CSS=1, TEL3=1** for Secure-EL1 interrupts 433 434- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is zero, the default routing 435 model is used for non-secure interrupts. They are routed to the FEL in 436 either security state i.e **CSS=0, TEL3=0** & **CSS=1, TEL3=0** for 437 Non-secure interrupts. 438 439- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, then the 440 non secure interrupts are routed to EL3 when execution is in secure state 441 i.e **CSS=0, TEL3=1** for non-secure interrupts. This effectively preempts 442 Secure-EL1. The default routing model is used for non secure interrupts in 443 non-secure state. i.e **CSS=1, TEL3=0**. 444 445It performs the following actions in the ``tspd_init()`` function to fulfill the 446requirements mentioned earlier. 447 448#. It passes control to the Test Secure Payload to perform its 449 initialisation. The TSP provides the address of the vector table 450 ``tsp_vectors`` in the SP which also includes the handler for Secure-EL1 451 interrupts in the ``sel1_intr_entry`` field. The TSPD passes control to the TSP at 452 this address when it receives a Secure-EL1 interrupt. 453 454 The handover agreement between the TSP and the TSPD requires that the TSPD 455 masks all interrupts (``PSTATE.DAIF`` bits) when it calls 456 ``tsp_sel1_intr_entry()``. The TSP has to preserve the callee saved general 457 purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use 458 ``x0-x18`` to enable its C runtime. 459 460#. The TSPD implements a handler function for Secure-EL1 interrupts. This 461 function is registered with the EL3 runtime firmware using the 462 ``register_interrupt_type_handler()`` API as follows 463 464 .. code:: c 465 466 /* Forward declaration */ 467 interrupt_type_handler tspd_secure_el1_interrupt_handler; 468 int32_t rc, flags = 0; 469 set_interrupt_rm_flag(flags, NON_SECURE); 470 rc = register_interrupt_type_handler(INTR_TYPE_S_EL1, 471 tspd_secure_el1_interrupt_handler, 472 flags); 473 if (rc) 474 panic(); 475 476#. When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, the TSPD 477 implements a handler function for non-secure interrupts. This function is 478 registered with the EL3 runtime firmware using the 479 ``register_interrupt_type_handler()`` API as follows 480 481 .. code:: c 482 483 /* Forward declaration */ 484 interrupt_type_handler tspd_ns_interrupt_handler; 485 int32_t rc, flags = 0; 486 set_interrupt_rm_flag(flags, SECURE); 487 rc = register_interrupt_type_handler(INTR_TYPE_NS, 488 tspd_ns_interrupt_handler, 489 flags); 490 if (rc) 491 panic(); 492 493.. _sp-int-registration: 494 495Secure payload 496~~~~~~~~~~~~~~ 497 498A Secure Payload must implement an interrupt handling framework at Secure-EL1 499(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload 500execution will alternate between the below cases. 501 502#. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt 503 type is targeted to the FEL, then it will be routed to the Secure-EL1 504 exception vector table. This is defined as the **asynchronous mode** of 505 handling interrupts. This mode applies to both Secure-EL1 and non-secure 506 interrupts. 507 508#. In the code where both interrupts are disabled, if an interrupt type is 509 targeted to the FEL, then execution will eventually migrate to the 510 non-secure state. Any non-secure interrupts will be handled as described 511 in the routing model where **CSS=1 and TEL3=0**. Secure-EL1 interrupts 512 will be routed to EL3 (as per the routing model where **CSS=1 and 513 TEL3=1**) where the SPD service will hand them to the SP. This is defined 514 as the **synchronous mode** of handling interrupts. 515 516The interrupt handling framework implemented by the SP should support one or 517both these interrupt handling models depending upon the chosen routing model. 518 519The following list briefly describes how the choice of a valid routing model 520(see `Valid routing models`_) effects the implementation of the Secure-EL1 521IHF. If the choice of the interrupt routing model is not known to the SPD 522service at compile time, then the SP should pass this information to the SPD 523service at runtime during its initialisation phase. 524 525As mentioned earlier, an Arm GICv2 system is considered and it is assumed that 526the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal 527is used to generate non-secure interrupts in either security state. 528 529Secure payload IHF design w.r.t secure-EL1 interrupts 530^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 531 532#. **CSS=0, TEL3=0**. If ``PSTATE.F=0``, Secure-EL1 interrupts will be 533 triggered at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1 534 IHF should implement support for handling FIQ interrupts asynchronously. 535 536 If ``PSTATE.F=1`` then Secure-EL1 interrupts will be handled as per the 537 synchronous interrupt handling model. The SP could implement this scenario 538 by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD 539 service during the registration phase. The SPD service would also need to 540 know the state of the system, general purpose and the ``PSTATE`` registers 541 in which it should arrange to return execution to the SP. The SP should 542 provide this information in an implementation defined way during the 543 registration phase if it is not known to the SPD service at build time. 544 545#. **CSS=1, TEL3=1**. Interrupts are routed to EL3 when execution is in 546 non-secure state. They should be handled through the synchronous interrupt 547 handling model as described in 1. above. 548 549#. **CSS=0, TEL3=1**. Secure-EL1 interrupts are routed to EL3 when execution 550 is in secure state. They will not be visible to the SP. The ``PSTATE.F`` bit 551 in Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will 552 call the handler registered by the SPD service for Secure-EL1 interrupts. 553 Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the 554 synchronous interrupt handling model described in 1. above. 555 556Secure payload IHF design w.r.t non-secure interrupts 557^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 558 559#. **CSS=0, TEL3=0**. If ``PSTATE.I=0``, non-secure interrupts will be 560 triggered at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1 561 IHF should co-ordinate with the SPD service to transfer execution to the 562 non-secure state where the interrupt should be handled e.g the SP could 563 allocate a function identifier to issue a SMC64 or SMC32 to the SPD 564 service which indicates that the SP execution has been preempted by a 565 non-secure interrupt. If this function identifier is not known to the SPD 566 service at compile time then the SP could provide it during the 567 registration phase. 568 569 If ``PSTATE.I=1`` then the non-secure interrupt will pend until execution 570 resumes in the non-secure state. 571 572#. **CSS=0, TEL3=1**. Non-secure interrupts are routed to EL3. They will not 573 be visible to the SP. The ``PSTATE.I`` bit in Secure-EL1/Secure-EL0 will 574 have not effect. The SPD service should register a non-secure interrupt 575 handler which should save the SP state correctly and resume execution in 576 the non-secure state where the interrupt will be handled. The Secure-EL1 577 IHF does not need to take any action. 578 579#. **CSS=1, TEL3=0**. Non-secure interrupts are handled in the FEL in 580 non-secure state (EL1/EL2) and are not visible to the SP. This routing 581 model does not affect the SP behavior. 582 583A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly 584configured at the interrupt controller by the platform port of the EL3 runtime 585firmware. It should configure any additional Secure-EL1 interrupts which the EL3 586runtime firmware is not aware of through its platform port. 587 588Test secure payload behavior 589~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 590 591The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is 592described in Section `Secure Payload Dispatcher`__. It is known to the TSPD 593service at build time. 594 595.. __: #spd-int-registration 596 597The TSP implements an entrypoint (``tsp_sel1_intr_entry()``) for handling Secure-EL1 598interrupts taken in non-secure state and routed through the TSPD service 599(synchronous handling model). It passes the reference to this entrypoint via 600``tsp_vectors`` to the TSPD service. 601 602The TSP also replaces the default exception vector table referenced through the 603``early_exceptions`` variable, with a vector table capable of handling FIQ and IRQ 604exceptions taken at the same (Secure-EL1) exception level. This table is 605referenced through the ``tsp_exceptions`` variable and programmed into the 606VBAR_EL1. It caters for the asynchronous handling model. 607 608The TSP also programs the Secure Physical Timer in the Arm Generic Timer block 609to raise a periodic interrupt (every half a second) for the purpose of testing 610interrupt management across all the software components listed in `Software 611components`_. 612 613Interrupt handling 614------------------ 615 616This section describes in detail the role of each software component (see 617Section `Software components`_) in handling an interrupt of a particular type. 618 619EL3 runtime firmware 620~~~~~~~~~~~~~~~~~~~~ 621 622The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced 623by the ``runtime_exceptions`` variable as follows. 624 625#. IRQ and FIQ exceptions taken from the current exception level with 626 ``SP_EL0`` or ``SP_EL3`` are reported as irrecoverable error conditions. As 627 mentioned earlier, EL3 runtime firmware always executes with the 628 ``PSTATE.I`` and ``PSTATE.F`` bits set. 629 630#. The following text describes how the IRQ and FIQ exceptions taken from a 631 lower exception level using AArch64 or AArch32 are handled. 632 633When an interrupt is generated, the vector for each interrupt type is 634responsible for: 635 636#. Saving the entire general purpose register context (x0-x30) immediately 637 upon exception entry. The registers are saved in the per-cpu ``cpu_context`` 638 data structure referenced by the ``SP_EL3``\ register. 639 640#. Saving the ``ELR_EL3``, ``SP_EL0`` and ``SPSR_EL3`` system registers in the 641 per-cpu ``cpu_context`` data structure referenced by the ``SP_EL3`` register. 642 643#. Switching to the C runtime stack by restoring the ``CTX_RUNTIME_SP`` value 644 from the per-cpu ``cpu_context`` data structure in ``SP_EL0`` and 645 executing the ``msr spsel, #0`` instruction. 646 647#. Determining the type of interrupt. Secure-EL1 interrupts will be signaled 648 at the FIQ vector. Non-secure interrupts will be signaled at the IRQ 649 vector. The platform should implement the following API to determine the 650 type of the pending interrupt. 651 652 .. code:: c 653 654 uint32_t plat_ic_get_interrupt_type(void); 655 656 It should return either ``INTR_TYPE_S_EL1`` or ``INTR_TYPE_NS``. 657 658#. Determining the handler for the type of interrupt that has been generated. 659 The following API has been added for this purpose. 660 661 .. code:: c 662 663 interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type); 664 665 It returns the reference to the registered handler for this interrupt 666 type. The ``handler`` is retrieved from the ``intr_type_desc_t`` structure as 667 described in Section 2. ``NULL`` is returned if no handler has been 668 registered for this type of interrupt. This scenario is reported as an 669 irrecoverable error condition. 670 671#. Calling the registered handler function for the interrupt type generated. 672 The ``id`` parameter is set to ``INTR_ID_UNAVAILABLE`` currently. The id along 673 with the current security state and a reference to the ``cpu_context_t`` 674 structure for the current security state are passed to the handler function 675 as its arguments. 676 677 The handler function returns a reference to the per-cpu ``cpu_context_t`` 678 structure for the target security state. 679 680#. Calling ``el3_exit()`` to return from EL3 into a lower exception level in 681 the security state determined by the handler routine. The ``el3_exit()`` 682 function is responsible for restoring the register context from the 683 ``cpu_context_t`` data structure for the target security state. 684 685Secure payload dispatcher 686~~~~~~~~~~~~~~~~~~~~~~~~~ 687 688Interrupt entry 689^^^^^^^^^^^^^^^ 690 691The SPD service begins handling an interrupt when the EL3 runtime firmware calls 692the handler function for that type of interrupt. The SPD service is responsible 693for the following: 694 695#. Validating the interrupt. This involves ensuring that the interrupt was 696 generated according to the interrupt routing model specified by the SPD 697 service during registration. It should use the security state of the 698 exception level (passed in the ``flags`` parameter of the handler) where 699 the interrupt was taken from to determine this. If the interrupt is not 700 recognised then the handler should treat it as an irrecoverable error 701 condition. 702 703 An SPD service can register a handler for Secure-EL1 and/or Non-secure 704 interrupts. A non-secure interrupt should never be routed to EL3 from 705 from non-secure state. Also if a routing model is chosen where Secure-EL1 706 interrupts are routed to S-EL1 when execution is in Secure state, then a 707 S-EL1 interrupt should never be routed to EL3 from secure state. The handler 708 could use the security state flag to check this. 709 710#. Determining whether a context switch is required. This depends upon the 711 routing model and interrupt type. For non secure and S-EL1 interrupt, 712 if the security state of the execution context where the interrupt was 713 generated is not the same as the security state required for handling 714 the interrupt, a context switch is required. The following 2 cases 715 require a context switch from secure to non-secure or vice-versa: 716 717 #. A Secure-EL1 interrupt taken from the non-secure state should be 718 routed to the Secure Payload. 719 720 #. A non-secure interrupt taken from the secure state should be routed 721 to the last known non-secure exception level. 722 723 The SPD service must save the system register context of the current 724 security state. It must then restore the system register context of the 725 target security state. It should use the ``cm_set_next_eret_context()`` API 726 to ensure that the next ``cpu_context`` to be restored is of the target 727 security state. 728 729 If the target state is secure then execution should be handed to the SP as 730 per the synchronous interrupt handling model it implements. A Secure-EL1 731 interrupt can be routed to EL3 while execution is in the SP. This implies 732 that SP execution can be preempted while handling an interrupt by a 733 another higher priority Secure-EL1 interrupt or a EL3 interrupt. The SPD 734 service should be able to handle this preemption or manage secure interrupt 735 priorities before handing control to the SP. 736 737#. Setting the return value of the handler to the per-cpu ``cpu_context`` if 738 the interrupt has been successfully validated and ready to be handled at a 739 lower exception level. 740 741The routing model allows non-secure interrupts to interrupt Secure-EL1 when in 742secure state if it has been configured to do so. The SPD service and the SP 743should implement a mechanism for routing these interrupts to the last known 744exception level in the non-secure state. The former should save the SP context, 745restore the non-secure context and arrange for entry into the non-secure state 746so that the interrupt can be handled. 747 748Interrupt exit 749^^^^^^^^^^^^^^ 750 751When the Secure Payload has finished handling a Secure-EL1 interrupt, it could 752return control back to the SPD service through a SMC32 or SMC64. The SPD service 753should handle this secure monitor call so that execution resumes in the 754exception level and the security state from where the Secure-EL1 interrupt was 755originally taken. 756 757Test secure payload dispatcher Secure-EL1 interrupt handling 758^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 759 760The example TSPD service registers a handler for Secure-EL1 interrupts taken 761from the non-secure state. During execution in S-EL1, the TSPD expects that the 762Secure-EL1 interrupts are handled in S-EL1 by TSP. Its handler 763``tspd_secure_el1_interrupt_handler()`` expects only to be invoked for Secure-EL1 764originating from the non-secure state. It takes the following actions upon being 765invoked. 766 767#. It uses the security state provided in the ``flags`` parameter to ensure 768 that the secure interrupt originated from the non-secure state. It asserts 769 if this is not the case. 770 771#. It saves the system register context for the non-secure state by calling 772 ``cm_el1_sysregs_context_save(NON_SECURE);``. 773 774#. It sets the ``ELR_EL3`` system register to ``tsp_sel1_intr_entry`` and sets the 775 ``SPSR_EL3.DAIF`` bits in the secure CPU context. It sets ``x0`` to 776 ``TSP_HANDLE_SEL1_INTR_AND_RETURN``. If the TSP was preempted earlier by a non 777 secure interrupt during ``yielding`` SMC processing, save the registers that 778 will be trashed, which is the ``ELR_EL3`` and ``SPSR_EL3``, in order to be able 779 to re-enter TSP for Secure-EL1 interrupt processing. It does not need to 780 save any other secure context since the TSP is expected to preserve it 781 (see section `Test secure payload dispatcher behavior`_). 782 783#. It restores the system register context for the secure state by calling 784 ``cm_el1_sysregs_context_restore(SECURE);``. 785 786#. It ensures that the secure CPU context is used to program the next 787 exception return from EL3 by calling ``cm_set_next_eret_context(SECURE);``. 788 789#. It returns the per-cpu ``cpu_context`` to indicate that the interrupt can 790 now be handled by the SP. ``x1`` is written with the value of ``elr_el3`` 791 register for the non-secure state. This information is used by the SP for 792 debugging purposes. 793 794The figure below describes how the interrupt handling is implemented by the TSPD 795when a Secure-EL1 interrupt is generated when execution is in the non-secure 796state. 797 798|Image 1| 799 800The TSP issues an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier to 801signal completion of interrupt handling. 802 803The TSPD service takes the following actions in ``tspd_smc_handler()`` function 804upon receiving an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier: 805 806#. It ensures that the call originated from the secure state otherwise 807 execution returns to the non-secure state with ``SMC_UNK`` in ``x0``. 808 809#. It restores the saved ``ELR_EL3`` and ``SPSR_EL3`` system registers back to 810 the secure CPU context (see step 3 above) in case the TSP had been preempted 811 by a non secure interrupt earlier. 812 813#. It restores the system register context for the non-secure state by 814 calling ``cm_el1_sysregs_context_restore(NON_SECURE)``. 815 816#. It ensures that the non-secure CPU context is used to program the next 817 exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``. 818 819#. ``tspd_smc_handler()`` returns a reference to the non-secure ``cpu_context`` 820 as the return value. 821 822Test secure payload dispatcher non-secure interrupt handling 823^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 824 825The TSP in Secure-EL1 can be preempted by a non-secure interrupt during 826``yielding`` SMC processing or by a higher priority EL3 interrupt during 827Secure-EL1 interrupt processing. When ``EL3_EXCEPTION_HANDLING`` is ``0``, only 828non-secure interrupts can cause preemption of TSP since there are no EL3 829interrupts in the system. With ``EL3_EXCEPTION_HANDLING=1`` however, any EL3 830interrupt may preempt Secure execution. 831 832It should be noted that while TSP is preempted, the TSPD only allows entry into 833the TSP either for Secure-EL1 interrupt handling or for resuming the preempted 834``yielding`` SMC in response to the ``TSP_FID_RESUME`` SMC from the normal world. 835(See Section `Implication of preempted SMC on Non-Secure Software`_). 836 837The non-secure interrupt triggered in Secure-EL1 during ``yielding`` SMC 838processing can be routed to either EL3 or Secure-EL1 and is controlled by build 839option ``TSP_NS_INTR_ASYNC_PREEMPT`` (see Section `Test secure payload 840dispatcher behavior`_). If the build option is set, the TSPD will set the 841routing model for the non-secure interrupt to be routed to EL3 from secure state 842i.e. **TEL3=1, CSS=0** and registers ``tspd_ns_interrupt_handler()`` as the 843non-secure interrupt handler. The ``tspd_ns_interrupt_handler()`` on being 844invoked ensures that the interrupt originated from the secure state and disables 845routing of non-secure interrupts from secure state to EL3. This is to prevent 846further preemption (by a non-secure interrupt) when TSP is reentered for 847handling Secure-EL1 interrupts that triggered while execution was in the normal 848world. The ``tspd_ns_interrupt_handler()`` then invokes 849``tspd_handle_sp_preemption()`` for further handling. 850 851If the ``TSP_NS_INTR_ASYNC_PREEMPT`` build option is zero (default), the default 852routing model for non-secure interrupt in secure state is in effect 853i.e. **TEL3=0, CSS=0**. During ``yielding`` SMC processing, the IRQ 854exceptions are unmasked i.e. ``PSTATE.I=0``, and a non-secure interrupt will 855trigger at Secure-EL1 IRQ exception vector. The TSP saves the general purpose 856register context and issues an SMC with ``TSP_PREEMPTED`` as the function 857identifier to signal preemption of TSP. The TSPD SMC handler, 858``tspd_smc_handler()``, ensures that the SMC call originated from the 859secure state otherwise execution returns to the non-secure state with 860``SMC_UNK`` in ``x0``. It then invokes ``tspd_handle_sp_preemption()`` for 861further handling. 862 863The ``tspd_handle_sp_preemption()`` takes the following actions upon being 864invoked: 865 866#. It saves the system register context for the secure state by calling 867 ``cm_el1_sysregs_context_save(SECURE)``. 868 869#. It restores the system register context for the non-secure state by 870 calling ``cm_el1_sysregs_context_restore(NON_SECURE)``. 871 872#. It ensures that the non-secure CPU context is used to program the next 873 exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``. 874 875#. ``SMC_PREEMPTED`` is set in x0 and return to non secure state after 876 restoring non secure context. 877 878The Normal World is expected to resume the TSP after the ``yielding`` SMC 879preemption by issuing an SMC with ``TSP_FID_RESUME`` as the function identifier 880(see section `Implication of preempted SMC on Non-Secure Software`_). The TSPD 881service takes the following actions in ``tspd_smc_handler()`` function upon 882receiving this SMC: 883 884#. It ensures that the call originated from the non secure state. An 885 assertion is raised otherwise. 886 887#. Checks whether the TSP needs a resume i.e check if it was preempted. It 888 then saves the system register context for the non-secure state by calling 889 ``cm_el1_sysregs_context_save(NON_SECURE)``. 890 891#. Restores the secure context by calling 892 ``cm_el1_sysregs_context_restore(SECURE)`` 893 894#. It ensures that the secure CPU context is used to program the next 895 exception return from EL3 by calling ``cm_set_next_eret_context(SECURE)``. 896 897#. ``tspd_smc_handler()`` returns a reference to the secure ``cpu_context`` as the 898 return value. 899 900The figure below describes how the TSP/TSPD handle a non-secure interrupt when 901it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the 902``TSP_NS_INTR_ASYNC_PREEMPT`` build flag is 0. 903 904|Image 2| 905 906Secure payload 907~~~~~~~~~~~~~~ 908 909The SP should implement one or both of the synchronous and asynchronous 910interrupt handling models depending upon the interrupt routing model it has 911chosen (as described in section `Secure Payload`__). 912 913.. __: #sp-int-registration 914 915In the synchronous model, it should begin handling a Secure-EL1 interrupt after 916receiving control from the SPD service at an entrypoint agreed upon during build 917time or during the registration phase. Before handling the interrupt, the SP 918should save any Secure-EL1 system register context which is needed for resuming 919normal execution in the SP later e.g. ``SPSR_EL1``, ``ELR_EL1``. After handling 920the interrupt, the SP could return control back to the exception level and 921security state where the interrupt was originally taken from. The SP should use 922an SMC32 or SMC64 to ask the SPD service to do this. 923 924In the asynchronous model, the Secure Payload is responsible for handling 925non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception 926vector table when ``PSTATE.I`` and ``PSTATE.F`` bits are 0. As described earlier, 927when a non-secure interrupt is generated, the SP should coordinate with the SPD 928service to pass control back to the non-secure state in the last known exception 929level. This will allow the non-secure interrupt to be handled in the non-secure 930state. 931 932Test secure payload behavior 933^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 934 935The TSPD hands control of a Secure-EL1 interrupt to the TSP at the 936``tsp_sel1_intr_entry()``. The TSP handles the interrupt while ensuring that the 937handover agreement described in Section `Test secure payload dispatcher 938behavior`_ is maintained. It updates some statistics by calling 939``tsp_update_sync_sel1_intr_stats()``. It then calls 940``tsp_common_int_handler()`` which. 941 942#. Checks whether the interrupt is the secure physical timer interrupt. It 943 uses the platform API ``plat_ic_get_pending_interrupt_id()`` to get the 944 interrupt number. If it is not the secure physical timer interrupt, then 945 that means that a higher priority interrupt has preempted it. Invoke 946 ``tsp_handle_preemption()`` to handover control back to EL3 by issuing 947 an SMC with ``TSP_PREEMPTED`` as the function identifier. 948 949#. Handles the secure timer interrupt interrupt by acknowledging it using the 950 ``plat_ic_acknowledge_interrupt()`` platform API, calling 951 ``tsp_generic_timer_handler()`` to reprogram the secure physical generic 952 timer and calling the ``plat_ic_end_of_interrupt()`` platform API to signal 953 end of interrupt processing. 954 955The TSP passes control back to the TSPD by issuing an SMC64 with 956``TSP_HANDLED_S_EL1_INTR`` as the function identifier. 957 958The TSP handles interrupts under the asynchronous model as follows. 959 960#. Secure-EL1 interrupts are handled by calling the ``tsp_common_int_handler()`` 961 function. The function has been described above. 962 963#. Non-secure interrupts are handled by calling the ``tsp_common_int_handler()`` 964 function which ends up invoking ``tsp_handle_preemption()`` and issuing an 965 SMC64 with ``TSP_PREEMPTED`` as the function identifier. Execution resumes at 966 the instruction that follows this SMC instruction when the TSPD hands control 967 to the TSP in response to an SMC with ``TSP_FID_RESUME`` as the function 968 identifier from the non-secure state (see section `Test secure payload 969 dispatcher non-secure interrupt handling`_). 970 971Other considerations 972-------------------- 973 974Implication of preempted SMC on Non-Secure Software 975~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 976 977A ``yielding`` SMC call to Secure payload can be preempted by a non-secure 978interrupt and the execution can return to the non-secure world for handling 979the interrupt (For details on ``yielding`` SMC refer `SMC calling convention`_). 980In this case, the SMC call has not completed its execution and the execution 981must return back to the secure payload to resume the preempted SMC call. 982This can be achieved by issuing an SMC call which instructs to resume the 983preempted SMC. 984 985A ``fast`` SMC cannot be preempted and hence this case will not happen for 986a fast SMC call. 987 988In the Test Secure Payload implementation, ``TSP_FID_RESUME`` is designated 989as the resume SMC FID. It is important to note that ``TSP_FID_RESUME`` is a 990``yielding`` SMC which means it too can be be preempted. The typical non 991secure software sequence for issuing a ``yielding`` SMC would look like this, 992assuming ``P.STATE.I=0`` in the non secure state : 993 994.. code:: c 995 996 int rc; 997 rc = smc(TSP_YIELD_SMC_FID, ...); /* Issue a Yielding SMC call */ 998 /* The pending non-secure interrupt is handled by the interrupt handler 999 and returns back here. */ 1000 while (rc == SMC_PREEMPTED) { /* Check if the SMC call is preempted */ 1001 rc = smc(TSP_FID_RESUME); /* Issue resume SMC call */ 1002 } 1003 1004The ``TSP_YIELD_SMC_FID`` is any ``yielding`` SMC function identifier and the smc() 1005function invokes a SMC call with the required arguments. The pending non-secure 1006interrupt causes an IRQ exception and the IRQ handler registered at the 1007exception vector handles the non-secure interrupt and returns. The return value 1008from the SMC call is tested for ``SMC_PREEMPTED`` to check whether it is 1009preempted. If it is, then the resume SMC call ``TSP_FID_RESUME`` is issued. The 1010return value of the SMC call is tested again to check if it is preempted. 1011This is done in a loop till the SMC call succeeds or fails. If a ``yielding`` 1012SMC is preempted, until it is resumed using ``TSP_FID_RESUME`` SMC and 1013completed, the current TSPD prevents any other SMC call from re-entering 1014TSP by returning ``SMC_UNK`` error. 1015 1016-------------- 1017 1018*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* 1019 1020.. _Porting Guide: ../getting_started/porting-guide.rst 1021.. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html 1022 1023.. |Image 1| image:: diagrams/sec-int-handling.png?raw=true 1024.. |Image 2| image:: diagrams/non-sec-int-handling.png?raw=true 1025
