1ARM Trusted Firmware Interrupt Management Design guide 2====================================================== 3 4Contents : 5 61. [Introduction](#1-introduction) 7 * [Assumptions](#11-assumptions) 8 * [Concepts](#12-concepts) 9 - [Interrupt Types](#121-interrupt-types) 10 - [Routing Model](#122-routing-model) 11 - [Valid Routing Models](#123-valid-routing-models) 12 + [Secure-EL1 Interrupts](#1231-secure-el1-interrupts) 13 + [Non-secure Interrupts](#1232-non-secure-interrupts) 14 - [Mapping of Interrupt Type to Signal](#124-mapping-of-interrupt-type-to-signal) 15 162. [Interrupt Management](#2-interrupt-management) 17 * [Software Components](#21-software-components) 18 * [Interrupt Registration](#22-interrupt-registration) 19 - [EL3 Runtime Firmware](#221-el3-runtime-firmware) 20 - [Secure Payload Dispatcher](#222-secure-payload-dispatcher) 21 + [Test Secure Payload Dispatcher behavior](#2221-test-secure-payload-dispatcher-behavior) 22 - [Secure Payload](#223-secure-payload) 23 + [Secure Payload IHF design w.r.t Secure-EL1 interrupts](#2231-secure-payload-ihf-design-wrt-secure-el1-interrupts) 24 + [Secure Payload IHF design w.r.t Non-secure interrupts](#2232-secure-payload-ihf-design-wrt-non-secure-interrupts) 25 + [Test Secure Payload behavior](#2233-test-secure-payload-behavior) 26 * [Interrupt Handling](#23-interrupt-handling) 27 - [EL3 Runtime Firmware](#231-el3-runtime-firmware) 28 - [Secure Payload Dispatcher](#232-secure-payload-dispatcher) 29 + [Interrupt Entry](#2321-interrupt-entry) 30 + [Interrupt Exit](#2322-interrupt-exit) 31 + [Test Secure Payload Dispatcher behavior](#2323-test-secure-payload-dispatcher-behavior) 32 - [Secure Payload](#233-secure-payload) 33 + [Test Secure Payload behavior](#2331-test-secure-payload-behavior) 34 35 361. Introduction 37---------------- 38This document describes the design of the Interrupt management framework in ARM 39Trusted Firmware. This section briefly describes the requirements from this 40framework. It also briefly explains some concepts and assumptions. They will 41help in understanding the implementation of the framework explained in 42subsequent sections. 43 44This framework is responsible for managing interrupts routed to EL3. It also 45allows EL3 software to configure the interrupt routing behavior. Its main 46objective is to implement the following two requirements. 47 481. It should be possible to route interrupts meant to be handled by secure 49 software (Secure interrupts) to EL3, when execution is in non-secure state 50 (normal world). The framework should then take care of handing control of 51 the interrupt to either software in EL3 or Secure-EL1 depending upon the 52 software configuration and the GIC implementation. This requirement ensures 53 that secure interrupts are under the control of the secure software with 54 respect to their delivery and handling without the possibility of 55 intervention from non-secure software. 56 572. It should be possible to route interrupts meant to be handled by 58 non-secure software (Non-secure interrupts) to the last executed exception 59 level in the normal world when the execution is in secure world at 60 exception levels lower than EL3. This could be done with or without the 61 knowledge of software executing in Secure-EL1/Secure-EL0. The choice of 62 approach should be governed by the secure software. This requirement 63 ensures that non-secure software is able to execute in tandem with the 64 secure software without overriding it. 65 66### 1.1 Assumptions 67The framework makes the following assumptions to simplify its implementation. 68 691. All secure interrupts are handled in Secure-EL1. They can be delivered to 70 Secure-EL1 via EL3 but they cannot be handled in EL3. It will be possible 71 to extend the framework to handle secure interrupts in EL3 in the future. 72 732. Interrupt exceptions (`PSTATE.I` and `F` bits) are masked during execution 74 in EL3. 75 76### 1.2 Concepts 77 78#### 1.2.1 Interrupt types 79The framework categorises an interrupt to be one of the following depending upon 80the exception level(s) it is handled in. 81 821. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or 83 Secure-EL1 depending upon the security state of the current execution 84 context. It is always handled in Secure-EL1. 85 862. Non-secure interrupt. This type of interrupt can be routed to EL3, 87 Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the 88 current execution context. It is always handled in either Non-secure EL1 89 or EL2. 90 913. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1 92 depending upon the security state of the current execution context. It is 93 always handled in EL3. 94 95In the current implementation of the framework, all secure interrupts are 96treated as Secure EL1 interrupts. It will be possible for EL3 software to 97configure a secure interrupt as an EL3 interrupt in future implementations. The 98following constants define the various interrupt types in the framework 99implementation. 100 101 #define INTR_TYPE_S_EL1 0 102 #define INTR_TYPE_EL3 1 103 #define INTR_TYPE_NS 2 104 105 106#### 1.2.2 Routing model 107A type of interrupt can be either generated as an FIQ or an IRQ. The target 108exception level of an interrupt type is configured through the FIQ and IRQ bits 109in the Secure Configuration Register at EL3 (`SCR_EL3.FIQ` and `SCR_EL3.IRQ` 110bits). When `SCR_EL3.FIQ`=1, FIQs are routed to EL3. Otherwise they are routed 111to the First Exception Level (FEL) capable of handling interrupts. When 112`SCR_EL3.IRQ`=1, IRQs are routed to EL3. Otherwise they are routed to the 113FEL. This register is configured independently by EL3 software for each security 114state prior to entry into a lower exception level in that security state. 115 116A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as 117its target exception level for each security state. It is represented by a 118single bit for each security state. A value of `0` means that the interrupt 119should be routed to the FEL. A value of `1` means that the interrupt should be 120routed to EL3. A routing model is applicable only when execution is not in EL3. 121 122The default routing model for an interrupt type is to route it to the FEL in 123either security state. 124 125#### 1.2.3 Valid routing models 126The framework considers certain routing models for each type of interrupt to be 127incorrect as they conflict with the requirements mentioned in Section 1. The 128following sub-sections describe all the possible routing models and specify 129which ones are valid or invalid. Only the Secure-EL1 and Non-secure interrupt 130types are considered as EL3 interrupts are currently unsupported (See 1.1). The 131terminology used in the following sub-sections is explained below. 132 1331. __CSS__. Current Security State. `0` when secure and `1` when non-secure 134 1352. __TEL3__. Target Exception Level 3. `0` when targeted to the FEL. `1` when 136 targeted to EL3. 137 138 139##### 1.2.3.1 Secure-EL1 interrupts 140 1411. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in 142 secure state. This is a valid routing model as secure software is in 143 control of handling secure interrupts. 144 1452. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure 146 state. This is a valid routing model as secure software in EL3 can 147 handover the interrupt to Secure-EL1 for handling. 148 1493. __CSS=1, TEL3=0__. Interrupt is routed to the FEL when execution is in 150 non-secure state. This is an invalid routing model as a secure interrupt 151 is not visible to the secure software which violates the motivation behind 152 the ARM Security Extensions. 153 1544. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in 155 non-secure state. This is a valid routing model as secure software in EL3 156 can handover the interrupt to Secure-EL1 for handling. 157 158 159##### 1.2.3.2 Non-secure interrupts 160 1611. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in 162 secure state. This allows the secure software to trap non-secure 163 interrupts, perform its bookeeping and hand the interrupt to the 164 non-secure software through EL3. This is a valid routing model as secure 165 software is in control of how its execution is pre-empted by non-secure 166 interrupts. 167 1682. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure 169 state. This is a valid routing model as secure software in EL3 can save 170 the state of software in Secure-EL1/Secure-EL0 before handing the 171 interrupt to non-secure software. This model requires additional 172 coordination between Secure-EL1 and EL3 software to ensure that the 173 former's state is correctly saved by the latter. 174 1753. __CSS=1, TEL3=0__. Interrupt is routed to FEL when execution is in 176 non-secure state. This is an valid routing model as a non-secure interrupt 177 is handled by non-secure software. 178 1794. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in 180 non-secure state. This is an invalid routing model as there is no valid 181 reason to route the interrupt to EL3 software and then hand it back to 182 non-secure software for handling. 183 184 185#### 1.2.4 Mapping of interrupt type to signal 186The framework is meant to work with any interrupt controller implemented by a 187platform. A interrupt controller could generate a type of interrupt as either an 188FIQ or IRQ signal to the CPU depending upon the current security state.The 189mapping between the type and signal is known only to the platform. The framework 190uses this information to determine whether the IRQ or the FIQ bit should be 191programmed in `SCR_EL3` while applying the routing model for a type of 192interrupt. The platform provides this information through the 193`plat_interrupt_type_to_line()` API (described in the [Porting 194Guide]). For example, on the FVP port when the platform uses an ARM GICv2 195interrupt controller, Secure-EL1 interrupts are signalled through the FIQ signal 196while Non-secure interrupts are signalled through the IRQ signal. This applies 197when execution is in either security state. 198 199 2002. Interrupt management 201----------------------- 202The following sections describe how interrupts are managed by the interrupt 203handling framework. This entails: 204 2051. Providing an interface to allow registration of a handler and specification 206 of the routing model for a type of interrupt. 207 2082. Implementing support to hand control of an interrupt type to its registered 209 handler when the interrupt is generated. 210 211Both aspects of interrupt management involve various components in the secure 212software stack spanning from EL3 to Secure-EL1. These components are described 213in the section 2.1. The framework stores information associated with each type 214of interrupt in the following data structure. 215 216``` 217typedef struct intr_type_desc { 218 interrupt_type_handler_t handler; 219 uint32_t flags; 220 uint32_t scr_el3[2]; 221} intr_type_desc_t; 222``` 223 224The `flags` field stores the routing model for the interrupt type in 225bits[1:0]. Bit[0] stores the routing model when execution is in the secure 226state. Bit[1] stores the routing model when execution is in the non-secure 227state. As mentioned in Section 1.2.2, a value of `0` implies that the interrupt 228should be targeted to the FEL. A value of `1` implies that it should be targeted 229to EL3. The remaining bits are reserved and SBZ. The helper macro 230`set_interrupt_rm_flag()` should be used to set the bits in the `flags` 231parameter. 232 233The `scr_el3[2]` field also stores the routing model but as a mapping of the 234model in the `flags` field to the corresponding bit in the `SCR_EL3` for each 235security state. 236 237The framework also depends upon the platform port to configure the interrupt 238controller to distinguish between secure and non-secure interrupts. The platform 239is expected to be aware of the secure devices present in the system and their 240associated interrupt numbers. It should configure the interrupt controller to 241enable the secure interrupts, ensure that their priority is always higher than 242the non-secure interrupts and target them to the primary CPU. It should also 243export the interface described in the [Porting Guide] to enable 244handling of interrupts. 245 246In the remainder of this document, for the sake of simplicity it is assumed that 247the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal is 248used to generate non-secure interrupts in either security state. 249 250### 2.1 Software components 251Roles and responsibilities for interrupt management are sub-divided between the 252following components of software running in EL3 and Secure-EL1. Each component is 253briefly described below. 254 2551. EL3 Runtime Firmware. This component is common to all ports of the ARM 256 Trusted Firmware. 257 2582. Secure Payload Dispatcher (SPD) service. This service interfaces with the 259 Secure Payload (SP) software which runs in exception levels lower than EL3 260 i.e. Secure-EL1/Secure-EL0. It is responsible for switching execution 261 between software running in secure and non-secure states at exception 262 levels lower than EL3. A switch is triggered by a Secure Monitor Call from 263 either state. It uses the APIs exported by the Context management library 264 to implement this functionality. Switching execution between the two 265 security states is a requirement for interrupt management as well. This 266 results in a significant dependency on the SPD service. ARM Trusted 267 firmware implements an example Test Secure Payload Dispatcher (TSPD) 268 service. 269 270 An SPD service plugs into the EL3 runtime firmware and could be common to 271 some ports of the ARM Trusted Firmware. 272 2733. Secure Payload (SP). On a production system, the Secure Payload corresponds 274 to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the 275 SPD service to manage communication with non-secure software. ARM Trusted 276 Firmware implements an example secure payload called Test Secure Payload 277 (TSP) which runs only in Secure-EL1. 278 279 A Secure payload implementation could be common to some ports of the ARM 280 Trusted Firmware just like the SPD service. 281 282 283### 2.2 Interrupt registration 284This section describes in detail the role of each software component (see 2.1) 285during the registration of a handler for an interrupt type. 286 287 288#### 2.2.1 EL3 runtime firmware 289This component declares the following prototype for a handler of an interrupt type. 290 291 typedef uint64_t (*interrupt_type_handler_t)(uint32_t id, 292 uint32_t flags, 293 void *handle, 294 void *cookie); 295 296The value of the `id` parameter depends upon the definition of the 297`IMF_READ_INTERRUPT_ID` build time flag. When the flag is defined, `id` contains 298the number of the highest priority pending interrupt of the type that this 299handler was registered for. When the flag is not defined `id` contains 300`INTR_ID_UNAVAILABLE`. 301 302The `flags` parameter contains miscellaneous information as follows. 303 3041. Security state, bit[0]. This bit indicates the security state of the lower 305 exception level when the interrupt was generated. A value of `1` means 306 that it was in the non-secure state. A value of `0` indicates that it was 307 in the secure state. This bit can be used by the handler to ensure that 308 interrupt was generated and routed as per the routing model specified 309 during registration. 310 3112. Reserved, bits[31:1]. The remaining bits are reserved for future use. 312 313The `handle` parameter points to the `cpu_context` structure of the current CPU 314for the security state specified in the `flags` parameter. 315 316Once the handler routine completes, execution will return to either the secure 317or non-secure state. The handler routine should return a pointer to 318`cpu_context` structure of the current CPU for the the target security state. It 319should treat all error conditions as critical errors and take appropriate action 320within its implementation e.g. use assertion failures. 321 322The runtime firmware provides the following API for registering a handler for a 323particular type of interrupt. A Secure Payload Dispatcher service should use 324this API to register a handler for Secure-EL1 and optionally for non-secure 325interrupts. This API also requires the caller to specify the routing model for 326the type of interrupt. 327 328 int32_t register_interrupt_type_handler(uint32_t type, 329 interrupt_type_handler handler, 330 uint64_t flags); 331 332 333The `type` parameter can be one of the three interrupt types listed above i.e. 334`INTR_TYPE_S_EL1`, `INTR_TYPE_NS` & `INTR_TYPE_EL3` (currently unimplemented). 335The `flags` parameter is as described in Section 2. 336 337The function will return `0` upon a successful registration. It will return 338`-EALREADY` in case a handler for the interrupt type has already been 339registered. If the `type` is unrecognised or the `flags` or the `handler` are 340invalid it will return `-EINVAL`. It will return `-ENOTSUP` if the specified 341`type` is not supported by the framework i.e. `INTR_TYPE_EL3`. 342 343Interrupt routing is governed by the configuration of the `SCR_EL3.FIQ/IRQ` bits 344prior to entry into a lower exception level in either security state. The 345context management library maintains a copy of the `SCR_EL3` system register for 346each security state in the `cpu_context` structure of each CPU. It exports the 347following APIs to let EL3 Runtime Firmware program and retrieve the routing 348model for each security state for the current CPU. The value of `SCR_EL3` stored 349in the `cpu_context` is used by the `el3_exit()` function to program the 350`SCR_EL3` register prior to returning from the EL3 exception level. 351 352 uint32_t cm_get_scr_el3(uint32_t security_state); 353 void cm_write_scr_el3_bit(uint32_t security_state, 354 uint32_t bit_pos, 355 uint32_t value); 356 357`cm_get_scr_el3()` returns the value of the `SCR_EL3` register for the specified 358security state of the current CPU. `cm_write_scr_el3()` writes a `0` or `1` to 359the bit specified by `bit_pos`. `register_interrupt_type_handler()` invokes 360`set_routing_model()` API which programs the `SCR_EL3` according to the routing 361model using the `cm_get_scr_el3()` and `cm_write_scr_el3_bit()` APIs. 362 363It is worth noting that in the current implementation of the framework, the EL3 364runtime firmware is responsible for programming the routing model. The SPD is 365responsible for ensuring that the routing model has been adhered to upon 366receiving an interrupt. 367 368#### 2.2.2 Secure payload dispatcher 369A SPD service is responsible for determining and maintaining the interrupt 370routing model supported by itself and the Secure Payload. It is also responsible 371for ferrying interrupts between secure and non-secure software depending upon 372the routing model. It could determine the routing model at build time or at 373runtime. It must use this information to register a handler for each interrupt 374type using the `register_interrupt_type_handler()` API in EL3 runtime firmware. 375 376If the routing model is not known to the SPD service at build time, then it must 377be provided by the SP as the result of its initialisation. The SPD should 378program the routing model only after SP initialisation has completed e.g. in the 379SPD initialisation function pointed to by the `bl32_init` variable. 380 381The SPD should determine the mechanism to pass control to the Secure Payload 382after receiving an interrupt from the EL3 runtime firmware. This information 383could either be provided to the SPD service at build time or by the SP at 384runtime. 385 386#### 2.2.2.1 Test secure payload dispatcher behavior 387The TSPD only handles Secure-EL1 interrupts and is provided with the following 388routing model at build time. 389 390* Secure-EL1 interrupts are routed to EL3 when execution is in non-secure 391 state and are routed to the FEL when execution is in the secure state 392 i.e __CSS=0, TEL3=0__ & __CSS=1, TEL3=1__ for Secure-EL1 interrupts 393 394* The default routing model is used for non-secure interrupts i.e they are 395 routed to the FEL in either security state i.e __CSS=0, TEL3=0__ & 396 __CSS=1, TEL3=0__ for Non-secure interrupts 397 398It performs the following actions in the `tspd_init()` function to fulfill the 399requirements mentioned earlier. 400 4011. It passes control to the Test Secure Payload to perform its 402 initialisation. The TSP provides the address of the vector table 403 `tsp_vectors` in the SP which also includes the handler for Secure-EL1 404 interrupts in the `fiq_entry` field. The TSPD passes control to the TSP at 405 this address when it receives a Secure-EL1 interrupt. 406 407 The handover agreement between the TSP and the TSPD requires that the TSPD 408 masks all interrupts (`PSTATE.DAIF` bits) when it calls 409 `tsp_fiq_entry()`. The TSP has to preserve the callee saved general 410 purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use 411 `x0-x18` to enable its C runtime. 412 4132. The TSPD implements a handler function for Secure-EL1 interrupts. It 414 registers it with the EL3 runtime firmware using the 415 `register_interrupt_type_handler()` API as follows 416 417 /* Forward declaration */ 418 interrupt_type_handler tspd_secure_el1_interrupt_handler; 419 int32_t rc, flags = 0; 420 set_interrupt_rm_flag(flags, NON_SECURE); 421 rc = register_interrupt_type_handler(INTR_TYPE_S_EL1, 422 tspd_secure_el1_interrupt_handler, 423 flags); 424 assert(rc == 0); 425 426#### 2.2.3 Secure payload 427A Secure Payload must implement an interrupt handling framework at Secure-EL1 428(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload 429execution will alternate between the below cases. 430 4311. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt 432 type is targeted to the FEL, then it will be routed to the Secure-EL1 433 exception vector table. This is defined as the asynchronous model of 434 handling interrupts. This mode applies to both Secure-EL1 and non-secure 435 interrupts. 436 4372. In the code where both interrupts are disabled, if an interrupt type is 438 targeted to the FEL, then execution will eventually migrate to the 439 non-secure state. Any non-secure interrupts will be handled as described 440 in the routing model where __CSS=1 and TEL3=0__. Secure-EL1 interrupts 441 will be routed to EL3 (as per the routing model where __CSS=1 and 442 TEL3=1__) where the SPD service will hand them to the SP. This is defined 443 as the synchronous mode of handling interrupts. 444 445The interrupt handling framework implemented by the SP should support one or 446both these interrupt handling models depending upon the chosen routing model. 447 448The following list briefly describes how the choice of a valid routing model 449(See 1.2.3) effects the implementation of the Secure-EL1 IHF. If the choice of 450the interrupt routing model is not known to the SPD service at compile time, 451then the SP should pass this information to the SPD service at runtime during 452its initialisation phase. 453 454As mentioned earlier, it is assumed that the FIQ signal is used to generate 455Secure-EL1 interrupts and the IRQ signal is used to generate non-secure 456interrupts in either security state. 457 458##### 2.2.3.1 Secure payload IHF design w.r.t secure-EL1 interrupts 4591. __CSS=0, TEL3=0__. If `PSTATE.F=0`, Secure-EL1 interrupts will be 460 trigerred at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1 461 IHF should implement support for handling FIQ interrupts asynchronously. 462 463 If `PSTATE.F=1` then Secure-EL1 interrupts will be handled as per the 464 synchronous interrupt handling model. The SP could implement this scenario 465 by exporting a seperate entrypoint for Secure-EL1 interrupts to the SPD 466 service during the registration phase. The SPD service would also need to 467 know the state of the system, general purpose and the `PSTATE` registers 468 in which it should arrange to return execution to the SP. The SP should 469 provide this information in an implementation defined way during the 470 registration phase if it is not known to the SPD service at build time. 471 4722. __CSS=1, TEL3=1__. Interrupts are routed to EL3 when execution is in 473 non-secure state. They should be handled through the synchronous interrupt 474 handling model as described in 1. above. 475 4763. __CSS=0, TEL3=1__. Secure interrupts are routed to EL3 when execution is in 477 secure state. They will not be visible to the SP. The `PSTATE.F` bit in 478 Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will 479 call the handler registered by the SPD service for Secure-EL1 480 interrupts. Secure-EL1 IHF should then handle all Secure-EL1 interrupt 481 through the synchronous interrupt handling model described in 1. above. 482 483 484##### 2.2.3.2 Secure payload IHF design w.r.t non-secure interrupts 4851. __CSS=0, TEL3=0__. If `PSTATE.I=0`, non-secure interrupts will be 486 trigerred at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1 487 IHF should co-ordinate with the SPD service to transfer execution to the 488 non-secure state where the interrupt should be handled e.g the SP could 489 allocate a function identifier to issue a SMC64 or SMC32 to the SPD 490 service which indicates that the SP execution has been pre-empted by a 491 non-secure interrupt. If this function identifier is not known to the SPD 492 service at compile time then the SP could provide it during the 493 registration phase. 494 495 If `PSTATE.I=1` then the non-secure interrupt will pend until execution 496 resumes in the non-secure state. 497 4982. __CSS=0, TEL3=1__. Non-secure interrupts are routed to EL3. They will not 499 be visible to the SP. The `PSTATE.I` bit in Secure-EL1/Secure-EL0 will 500 have not effect. The SPD service should register a non-secure interrupt 501 handler which should save the SP state correctly and resume execution in 502 the non-secure state where the interrupt will be handled. The Secure-EL1 503 IHF does not need to take any action. 504 5053. __CSS=1, TEL3=0__. Non-secure interrupts are handled in the FEL in 506 non-secure state (EL1/EL2) and are not visible to the SP. This routing 507 model does not affect the SP behavior. 508 509 510A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly 511configured at the interrupt controller by the platform port of the EL3 runtime 512firmware. It should configure any additional Secure-EL1 interrupts which the EL3 513runtime firmware is not aware of through its platform port. 514 515#### 2.2.3.3 Test secure payload behavior 516The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is 517described in Section 2.2.2. It is known to the TSPD service at build time. 518 519The TSP implements an entrypoint (`tsp_fiq_entry()`) for handling Secure-EL1 520interrupts taken in non-secure state and routed through the TSPD service 521(synchronous handling model). It passes the reference to this entrypoint via 522`tsp_vectors` to the TSPD service. 523 524The TSP also replaces the default exception vector table referenced through the 525`early_exceptions` variable, with a vector table capable of handling FIQ and IRQ 526exceptions taken at the same (Secure-EL1) exception level. This table is 527referenced through the `tsp_exceptions` variable and programmed into the 528VBAR_EL1. It caters for the asynchronous handling model. 529 530The TSP also programs the Secure Physical Timer in the ARM Generic Timer block 531to raise a periodic interrupt (every half a second) for the purpose of testing 532interrupt management across all the software components listed in 2.1 533 534 535### 2.3 Interrupt handling 536This section describes in detail the role of each software component (see 537Section 2.1) in handling an interrupt of a particular type. 538 539#### 2.3.1 EL3 runtime firmware 540The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced 541by the `runtime_exceptions` variable as follows. 542 5431. IRQ and FIQ exceptions taken from the current exception level with 544 `SP_EL0` or `SP_EL3` are reported as irrecoverable error conditions. As 545 mentioned earlier, EL3 runtime firmware always executes with the 546 `PSTATE.I` and `PSTATE.F` bits set. 547 5482. The following text describes how the IRQ and FIQ exceptions taken from a 549 lower exception level using AArch64 or AArch32 are handled. 550 551When an interrupt is generated, the vector for each interrupt type is 552responsible for: 553 5541. Saving the entire general purpose register context (x0-x30) immediately 555 upon exception entry. The registers are saved in the per-cpu `cpu_context` 556 data structure referenced by the `SP_EL3`register. 557 5582. Saving the `ELR_EL3`, `SP_EL0` and `SPSR_EL3` system registers in the 559 per-cpu `cpu_context` data structure referenced by the `SP_EL3` register. 560 5613. Switching to the C runtime stack by restoring the `CTX_RUNTIME_SP` value 562 from the per-cpu `cpu_context` data structure in `SP_EL0` and 563 executing the `msr spsel, #0` instruction. 564 5654. Determining the type of interrupt. Secure-EL1 interrupts will be signalled 566 at the FIQ vector. Non-secure interrupts will be signalled at the IRQ 567 vector. The platform should implement the following API to determine the 568 type of the pending interrupt. 569 570 uint32_t plat_ic_get_interrupt_type(void); 571 572 It should return either `INTR_TYPE_S_EL1` or `INTR_TYPE_NS`. 573 5745. Determining the handler for the type of interrupt that has been generated. 575 The following API has been added for this purpose. 576 577 interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type); 578 579 It returns the reference to the registered handler for this interrupt 580 type. The `handler` is retrieved from the `intr_type_desc_t` structure as 581 described in Section 2. `NULL` is returned if no handler has been 582 registered for this type of interrupt. This scenario is reported as an 583 irrecoverable error condition. 584 5856. Calling the registered handler function for the interrupt type generated. 586 The firmware also determines the interrupt id if the IMF_READ_INTERRUPT_ID 587 build time flag is set. The id is set to `INTR_ID_UNAVAILABLE` if the flag 588 is not set. The id along with the current security state and a reference to 589 the `cpu_context_t` structure for the current security state are passed to 590 the handler function as its arguments. 591 592 The handler function returns a reference to the per-cpu `cpu_context_t` 593 structure for the target security state. 594 5957. Calling `el3_exit()` to return from EL3 into a lower exception level in 596 the security state determined by the handler routine. The `el3_exit()` 597 function is responsible for restoring the register context from the 598 `cpu_context_t` data structure for the target security state. 599 600 601#### 2.3.2 Secure payload dispatcher 602 603##### 2.3.2.1 Interrupt entry 604The SPD service begins handling an interrupt when the EL3 runtime firmware calls 605the handler function for that type of interrupt. The SPD service is responsible 606for the following: 607 6081. Validating the interrupt. This involves ensuring that the interrupt was 609 generating according to the interrupt routing model specified by the SPD 610 service during registration. It should use the interrupt id and the 611 security state of the exception level (passed in the `flags` parameter of 612 the handler) where the interrupt was taken from to determine this. If the 613 interrupt is not recognised then the handler should treat it as an 614 irrecoverable error condition. 615 616 A SPD service can register a handler for Secure-EL1 and/or Non-secure 617 interrupts. The following text describes further error scenarios keeping 618 this in mind: 619 620 1. __SPD service has registered a handler for Non-secure interrupts__: 621 When an interrupt is received by the handler, it could check its id 622 to ensure it has been configured as a non-secure interrupt at the 623 interrupt controller. A secure interrupt should never be handed to 624 the non-secure interrupt handler. A non-secure interrupt should 625 never be routed to EL3 when execution is in non-secure state. The 626 handler could check the security state flag to ensure this. 627 628 2. __SPD service has registered a handler for Secure-EL1 interrupts__: 629 When an interrupt is received by the handler, it could check its id 630 to ensure it has been configured as a secure interrupt at the 631 interrupt controller. A non-secure interrupt should never be handed 632 to the secure interrupt handler. If the routing model chosen is such 633 that Secure-EL1 interrupts are not routed to EL3 when execution is 634 in non-secure state, then a Secure-EL1 interrupt generated in the 635 secure state would be invalid. The handler could use the security 636 state flag to check this. 637 638 The SPD service should use the platform API: 639 `plat_ic_get_interrupt_type()` to determine the type of interrupt for the 640 specified id. 641 6422. Determining whether the security state of the exception level for handling 643 the interrupt is the same as the security state of the exception level 644 where the interrupt was generated. This depends upon the routing model and 645 type of the interrupt. The SPD should use this information to determine if 646 a context switch is required. The following two cases would require a 647 context switch from secure to non-secure or vice-versa. 648 649 1. A Secure-EL1 interrupt taken from the non-secure state should be 650 routed to the Secure Payload. 651 652 2. A non-secure interrupt taken from the secure state should be routed 653 to the last known non-secure exception level. 654 655 The SPD service must save the system register context of the current 656 security state. It must then restore the system register context of the 657 target security state. It should use the `cm_set_next_eret_context()` API 658 to ensure that the next `cpu_context` to be restored is of the target 659 security state. 660 661 If the target state is secure then execution should be handed to the SP as 662 per the synchronous interrupt handling model it implements. A Secure-EL1 663 interrupt can be routed to EL3 while execution is in the SP. This implies 664 that SP execution can be preempted while handling an interrupt by a 665 another higher priority Secure-EL1 interrupt (or a EL3 interrupt in the 666 future). The SPD service should manage secure interrupt priorities before 667 handing control to the SP to prevent this type of preemption which can 668 leave the system in an inconsistent state. 669 6703. Setting the return value of the handler to the per-cpu `cpu_context` if 671 the interrupt has been successfully validated and ready to be handled at a 672 lower exception level. 673 674The routing model allows non-secure interrupts to be taken to Secure-EL1 when in 675secure state. The SPD service and the SP should implement a mechanism for 676routing these interrupts to the last known exception level in the non-secure 677state. The former should save the SP context, restore the non-secure context and 678arrange for entry into the non-secure state so that the interrupt can be 679handled. 680 681##### 2.3.2.2 Interrupt exit 682When the Secure Payload has finished handling a Secure-EL1 interrupt, it could 683return control back to the SPD service through a SMC32 or SMC64. The SPD service 684should handle this secure monitor call so that execution resumes in the 685exception level and the security state from where the Secure-EL1 interrupt was 686originally taken. 687 688##### 2.3.2.3 Test secure payload dispatcher behavior 689The example TSPD service registers a handler for Secure-EL1 interrupts taken 690from the non-secure state. Its handler `tspd_secure_el1_interrupt_handler()` 691takes the following actions upon being invoked. 692 6931. It uses the `id` parameter to query the interrupt controller to ensure 694 that the interrupt is a Secure-EL1 interrupt. It asserts if this is not 695 the case. 696 6972. It uses the security state provided in the `flags` parameter to ensure 698 that the secure interrupt originated from the non-secure state. It asserts 699 if this is not the case. 700 7013. It saves the system register context for the non-secure state by calling 702 `cm_el1_sysregs_context_save(NON_SECURE);`. 703 7044. It sets the `ELR_EL3` system register to `tsp_fiq_entry` and sets the 705 `SPSR_EL3.DAIF` bits in the secure CPU context. It sets `x0` to 706 `TSP_HANDLE_FIQ_AND_RETURN`. If the TSP was in the middle of handling a 707 standard SMC, then the `ELR_EL3` and `SPSR_EL3` registers in the secure CPU 708 context are saved first. 709 7105. It restores the system register context for the secure state by calling 711 `cm_el1_sysregs_context_restore(SECURE);`. 712 7136. It ensures that the secure CPU context is used to program the next 714 exception return from EL3 by calling `cm_set_next_eret_context(SECURE);`. 715 7167. It returns the per-cpu `cpu_context` to indicate that the interrupt can 717 now be handled by the SP. `x1` is written with the value of `elr_el3` 718 register for the non-secure state. This information is used by the SP for 719 debugging purposes. 720 721The figure below describes how the interrupt handling is implemented by the TSPD 722when a Secure-EL1 interrupt is generated when execution is in the non-secure 723state. 724 725 726 727The TSP issues an SMC with `TSP_HANDLED_S_EL1_FIQ` as the function identifier to 728signal completion of interrupt handling. 729 730The TSP issues an SMC with `TSP_PREEMPTED` as the function identifier to signal 731generation of a non-secure interrupt in Secure-EL1. 732 733The TSPD service takes the following actions in `tspd_smc_handler()` function 734upon receiving an SMC with `TSP_HANDLED_S_EL1_FIQ` and `TSP_PREEMPTED` as the 735function identifiers: 736 7371. It ensures that the call originated from the secure state otherwise 738 execution returns to the non-secure state with `SMC_UNK` in `x0`. 739 7402. If the function identifier is `TSP_HANDLED_S_EL1_FIQ`, it restores the 741 saved `ELR_EL3` and `SPSR_EL3` system registers back to the secure CPU 742 context (see step 4 above) in case the TSP had been preempted by a non 743 secure interrupt earlier. It does not save the secure context since the 744 TSP is expected to preserve it (see Section 2.2.2.1) 745 7463. If the function identifier is `TSP_PREEMPTED`, it saves the system 747 register context for the secure state by calling 748 `cm_el1_sysregs_context_save(SECURE)`. 749 7504. It restores the system register context for the non-secure state by 751 calling `cm_el1_sysregs_context_restore(NON_SECURE)`. It sets `x0` to 752 `SMC_PREEMPTED` if the incoming function identifier is 753 `TSP_PREEMPTED`. The Normal World is expected to resume the TSP after the 754 non-secure interrupt handling by issuing an SMC with `TSP_FID_RESUME` as 755 the function identifier. 756 7575. It ensures that the non-secure CPU context is used to program the next 758 exception return from EL3 by calling 759 `cm_set_next_eret_context(NON_SECURE)`. 760 7616. `tspd_smc_handler()` returns a reference to the non-secure `cpu_context` 762 as the return value. 763 764As mentioned in 4. above, if a non-secure interrupt preempts the TSP execution 765then the non-secure software issues an SMC with `TSP_FID_RESUME` as the function 766identifier to resume TSP execution. The TSPD service takes the following actions 767in `tspd_smc_handler()` function upon receiving this SMC: 768 7691. It ensures that the call originated from the non secure state. An 770 assertion is raised otherwise. 771 7722. Checks whether the TSP needs a resume i.e check if it was preempted. It 773 then saves the system register context for the secure state by calling 774 `cm_el1_sysregs_context_save(NON_SECURE)`. 775 7763. Restores the secure context by calling 777 `cm_el1_sysregs_context_restore(SECURE)` 778 7794. It ensures that the secure CPU context is used to program the next 780 exception return from EL3 by calling `cm_set_next_eret_context(SECURE)`. 781 7825. `tspd_smc_handler()` returns a reference to the secure `cpu_context` as the 783 return value. 784 785The figure below describes how the TSP/TSPD handle a non-secure interrupt when 786it is generated during execution in the TSP with `PSTATE.I` = 0. 787 788 789 790 791#### 2.3.3 Secure payload 792The SP should implement one or both of the synchronous and asynchronous 793interrupt handling models depending upon the interrupt routing model it has 794chosen (as described in 2.2.3). 795 796In the synchronous model, it should begin handling a Secure-EL1 interrupt after 797receiving control from the SPD service at an entrypoint agreed upon during build 798time or during the registration phase. Before handling the interrupt, the SP 799should save any Secure-EL1 system register context which is needed for resuming 800normal execution in the SP later e.g. `SPSR_EL1, `ELR_EL1`. After handling the 801interrupt, the SP could return control back to the exception level and security 802state where the interrupt was originally taken from. The SP should use an SMC32 803or SMC64 to ask the SPD service to do this. 804 805In the asynchronous model, the Secure Payload is responsible for handling 806non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception 807vector table when `PSTATE.I` and `PSTATE.F` bits are 0. As described earlier, 808when a non-secure interrupt is generated, the SP should coordinate with the SPD 809service to pass control back to the non-secure state in the last known exception 810level. This will allow the non-secure interrupt to be handled in the non-secure 811state. 812 813##### 2.3.3.1 Test secure payload behavior 814The TSPD hands control of a Secure-EL1 interrupt to the TSP at the 815`tsp_fiq_entry()`. The TSP handles the interrupt while ensuring that the 816handover agreement described in Section 2.2.2.1 is maintained. It updates some 817statistics by calling `tsp_update_sync_fiq_stats()`. It then calls 818`tsp_fiq_handler()` which. 819 8201. Checks whether the interrupt is the secure physical timer interrupt. It 821 uses the platform API `plat_ic_get_pending_interrupt_id()` to get the 822 interrupt number. 823 8242. Handles the interrupt by acknowledging it using the 825 `plat_ic_acknowledge_interrupt()` platform API, calling 826 `tsp_generic_timer_handler()` to reprogram the secure physical generic 827 timer and calling the `plat_ic_end_of_interrupt()` platform API to signal 828 end of interrupt processing. 829 830The TSP passes control back to the TSPD by issuing an SMC64 with 831`TSP_HANDLED_S_EL1_FIQ` as the function identifier. 832 833The TSP handles interrupts under the asynchronous model as follows. 834 8351. Secure-EL1 interrupts are handled by calling the `tsp_fiq_handler()` 836 function. The function has been described above. 837 8382. Non-secure interrupts are handled by issuing an SMC64 with `TSP_PREEMPTED` 839 as the function identifier. Execution resumes at the instruction that 840 follows this SMC instruction when the TSPD hands control to the TSP in 841 response to an SMC with `TSP_FID_RESUME` as the function identifier from 842 the non-secure state (see section 2.3.2.1). 843 844- - - - - - - - - - - - - - - - - - - - - - - - - - 845 846_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._ 847 848[Porting Guide]: ./porting-guide.md 849
