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