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