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