1 ARM Trusted Firmware Interrupt Management Design guide 2 ====================================================== 3 4 Contents : 5 6 1. [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 16 2. [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 36 1. Introduction 37 ---------------- 38 This document describes the design of the Interrupt management framework in ARM 39 Trusted Firmware. This section briefly describes the requirements from this 40 framework. It also briefly explains some concepts and assumptions. They will 41 help in understanding the implementation of the framework explained in 42 subsequent sections. 43 44 This framework is responsible for managing interrupts routed to EL3. It also 45 allows EL3 software to configure the interrupt routing behavior. Its main 46 objective is to implement the following two requirements. 47 48 1. 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 57 2. 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 67 The framework makes the following assumptions to simplify its implementation. 68 69 1. 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 73 2. 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 79 The framework categorises an interrupt to be one of the following depending upon 80 the exception level(s) it is handled in. 81 82 1. 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 86 2. 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 91 3. 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 95 In the current implementation of the framework, all secure interrupts are 96 treated as Secure EL1 interrupts. It will be possible for EL3 software to 97 configure a secure interrupt as an EL3 interrupt in future implementations. The 98 following constants define the various interrupt types in the framework 99 implementation. 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 107 A type of interrupt can be either generated as an FIQ or an IRQ. The target 108 exception level of an interrupt type is configured through the FIQ and IRQ bits 109 in the Secure Configuration Register at EL3 (`SCR_EL3.FIQ` and `SCR_EL3.IRQ` 110 bits). When `SCR_EL3.FIQ`=1, FIQs are routed to EL3. Otherwise they are routed 111 to 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 113 FEL. This register is configured independently by EL3 software for each security 114 state prior to entry into a lower exception level in that security state. 115 116 A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as 117 its target exception level for each security state. It is represented by a 118 single bit for each security state. A value of `0` means that the interrupt 119 should be routed to the FEL. A value of `1` means that the interrupt should be 120 routed to EL3. A routing model is applicable only when execution is not in EL3. 121 122 The default routing model for an interrupt type is to route it to the FEL in 123 either security state. 124 125 #### 1.2.3 Valid routing models 126 The framework considers certain routing models for each type of interrupt to be 127 incorrect as they conflict with the requirements mentioned in Section 1. The 128 following sub-sections describe all the possible routing models and specify 129 which ones are valid or invalid. Only the Secure-EL1 and Non-secure interrupt 130 types are considered as EL3 interrupts are currently unsupported (See 1.1). The 131 terminology used in the following sub-sections is explained below. 132 133 1. __CSS__. Current Security State. `0` when secure and `1` when non-secure 134 135 2. __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 141 1. __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 145 2. __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 149 3. __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 154 4. __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 161 1. __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 168 2. __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 175 3. __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 179 4. __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 186 The framework is meant to work with any interrupt controller implemented by a 187 platform. A interrupt controller could generate a type of interrupt as either an 188 FIQ or IRQ signal to the CPU depending upon the current security state.The 189 mapping between the type and signal is known only to the platform. The framework 190 uses this information to determine whether the IRQ or the FIQ bit should be 191 programmed in `SCR_EL3` while applying the routing model for a type of 192 interrupt. The platform provides this information through the 193 `plat_interrupt_type_to_line()` API (described in the [Porting 194 Guide]). For example, on the FVP port when the platform uses an ARM GICv2 195 interrupt controller, Secure-EL1 interrupts are signalled through the FIQ signal 196 while Non-secure interrupts are signalled through the IRQ signal. This applies 197 when execution is in either security state. 198 199 200 2. Interrupt management 201 ----------------------- 202 The following sections describe how interrupts are managed by the interrupt 203 handling framework. This entails: 204 205 1. Providing an interface to allow registration of a handler and specification 206 of the routing model for a type of interrupt. 207 208 2. Implementing support to hand control of an interrupt type to its registered 209 handler when the interrupt is generated. 210 211 Both aspects of interrupt management involve various components in the secure 212 software stack spanning from EL3 to Secure-EL1. These components are described 213 in the section 2.1. The framework stores information associated with each type 214 of interrupt in the following data structure. 215 216 ``` 217 typedef 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 224 The `flags` field stores the routing model for the interrupt type in 225 bits[1:0]. Bit[0] stores the routing model when execution is in the secure 226 state. Bit[1] stores the routing model when execution is in the non-secure 227 state. As mentioned in Section 1.2.2, a value of `0` implies that the interrupt 228 should be targeted to the FEL. A value of `1` implies that it should be targeted 229 to 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` 231 parameter. 232 233 The `scr_el3[2]` field also stores the routing model but as a mapping of the 234 model in the `flags` field to the corresponding bit in the `SCR_EL3` for each 235 security state. 236 237 The framework also depends upon the platform port to configure the interrupt 238 controller to distinguish between secure and non-secure interrupts. The platform 239 is expected to be aware of the secure devices present in the system and their 240 associated interrupt numbers. It should configure the interrupt controller to 241 enable the secure interrupts, ensure that their priority is always higher than 242 the non-secure interrupts and target them to the primary CPU. It should also 243 export the interface described in the [Porting Guide] to enable 244 handling of interrupts. 245 246 In the remainder of this document, for the sake of simplicity it is assumed that 247 the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal is 248 used to generate non-secure interrupts in either security state. 249 250 ### 2.1 Software components 251 Roles and responsibilities for interrupt management are sub-divided between the 252 following components of software running in EL3 and Secure-EL1. Each component is 253 briefly described below. 254 255 1. EL3 Runtime Firmware. This component is common to all ports of the ARM 256 Trusted Firmware. 257 258 2. 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 273 3. 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 284 This section describes in detail the role of each software component (see 2.1) 285 during the registration of a handler for an interrupt type. 286 287 288 #### 2.2.1 EL3 runtime firmware 289 This 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 296 The 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 298 the number of the highest priority pending interrupt of the type that this 299 handler was registered for. When the flag is not defined `id` contains 300 `INTR_ID_UNAVAILABLE`. 301 302 The `flags` parameter contains miscellaneous information as follows. 303 304 1. 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 311 2. Reserved, bits[31:1]. The remaining bits are reserved for future use. 312 313 The `handle` parameter points to the `cpu_context` structure of the current CPU 314 for the security state specified in the `flags` parameter. 315 316 Once the handler routine completes, execution will return to either the secure 317 or 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 319 should treat all error conditions as critical errors and take appropriate action 320 within its implementation e.g. use assertion failures. 321 322 The runtime firmware provides the following API for registering a handler for a 323 particular type of interrupt. A Secure Payload Dispatcher service should use 324 this API to register a handler for Secure-EL1 and optionally for non-secure 325 interrupts. This API also requires the caller to specify the routing model for 326 the 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 333 The `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). 335 The `flags` parameter is as described in Section 2. 336 337 The function will return `0` upon a successful registration. It will return 338 `-EALREADY` in case a handler for the interrupt type has already been 339 registered. If the `type` is unrecognised or the `flags` or the `handler` are 340 invalid 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 343 Interrupt routing is governed by the configuration of the `SCR_EL3.FIQ/IRQ` bits 344 prior to entry into a lower exception level in either security state. The 345 context management library maintains a copy of the `SCR_EL3` system register for 346 each security state in the `cpu_context` structure of each CPU. It exports the 347 following APIs to let EL3 Runtime Firmware program and retrieve the routing 348 model for each security state for the current CPU. The value of `SCR_EL3` stored 349 in 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 358 security state of the current CPU. `cm_write_scr_el3()` writes a `0` or `1` to 359 the bit specified by `bit_pos`. `register_interrupt_type_handler()` invokes 360 `set_routing_model()` API which programs the `SCR_EL3` according to the routing 361 model using the `cm_get_scr_el3()` and `cm_write_scr_el3_bit()` APIs. 362 363 It is worth noting that in the current implementation of the framework, the EL3 364 runtime firmware is responsible for programming the routing model. The SPD is 365 responsible for ensuring that the routing model has been adhered to upon 366 receiving an interrupt. 367 368 #### 2.2.2 Secure payload dispatcher 369 A SPD service is responsible for determining and maintaining the interrupt 370 routing model supported by itself and the Secure Payload. It is also responsible 371 for ferrying interrupts between secure and non-secure software depending upon 372 the routing model. It could determine the routing model at build time or at 373 runtime. It must use this information to register a handler for each interrupt 374 type using the `register_interrupt_type_handler()` API in EL3 runtime firmware. 375 376 If the routing model is not known to the SPD service at build time, then it must 377 be provided by the SP as the result of its initialisation. The SPD should 378 program the routing model only after SP initialisation has completed e.g. in the 379 SPD initialisation function pointed to by the `bl32_init` variable. 380 381 The SPD should determine the mechanism to pass control to the Secure Payload 382 after receiving an interrupt from the EL3 runtime firmware. This information 383 could either be provided to the SPD service at build time or by the SP at 384 runtime. 385 386 #### 2.2.2.1 Test secure payload dispatcher behavior 387 The TSPD only handles Secure-EL1 interrupts and is provided with the following 388 routing 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 398 It performs the following actions in the `tspd_init()` function to fulfill the 399 requirements mentioned earlier. 400 401 1. 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 413 2. 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 427 A Secure Payload must implement an interrupt handling framework at Secure-EL1 428 (Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload 429 execution will alternate between the below cases. 430 431 1. 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 437 2. 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 445 The interrupt handling framework implemented by the SP should support one or 446 both these interrupt handling models depending upon the chosen routing model. 447 448 The 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 450 the interrupt routing model is not known to the SPD service at compile time, 451 then the SP should pass this information to the SPD service at runtime during 452 its initialisation phase. 453 454 As mentioned earlier, it is assumed that the FIQ signal is used to generate 455 Secure-EL1 interrupts and the IRQ signal is used to generate non-secure 456 interrupts in either security state. 457 458 ##### 2.2.3.1 Secure payload IHF design w.r.t secure-EL1 interrupts 459 1. __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 472 2. __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 476 3. __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 485 1. __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 498 2. __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 505 3. __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 510 A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly 511 configured at the interrupt controller by the platform port of the EL3 runtime 512 firmware. It should configure any additional Secure-EL1 interrupts which the EL3 513 runtime firmware is not aware of through its platform port. 514 515 #### 2.2.3.3 Test secure payload behavior 516 The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is 517 described in Section 2.2.2. It is known to the TSPD service at build time. 518 519 The TSP implements an entrypoint (`tsp_fiq_entry()`) for handling Secure-EL1 520 interrupts 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 524 The 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 526 exceptions taken at the same (Secure-EL1) exception level. This table is 527 referenced through the `tsp_exceptions` variable and programmed into the 528 VBAR_EL1. It caters for the asynchronous handling model. 529 530 The TSP also programs the Secure Physical Timer in the ARM Generic Timer block 531 to raise a periodic interrupt (every half a second) for the purpose of testing 532 interrupt management across all the software components listed in 2.1 533 534 535 ### 2.3 Interrupt handling 536 This section describes in detail the role of each software component (see 537 Section 2.1) in handling an interrupt of a particular type. 538 539 #### 2.3.1 EL3 runtime firmware 540 The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced 541 by the `runtime_exceptions` variable as follows. 542 543 1. 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 548 2. The following text describes how the IRQ and FIQ exceptions taken from a 549 lower exception level using AArch64 or AArch32 are handled. 550 551 When an interrupt is generated, the vector for each interrupt type is 552 responsible for: 553 554 1. 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 558 2. 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 561 3. 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 565 4. 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 574 5. 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 585 6. 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 595 7. 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 604 The SPD service begins handling an interrupt when the EL3 runtime firmware calls 605 the handler function for that type of interrupt. The SPD service is responsible 606 for the following: 607 608 1. 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 642 2. 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 670 3. 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 674 The routing model allows non-secure interrupts to be taken to Secure-EL1 when in 675 secure state. The SPD service and the SP should implement a mechanism for 676 routing these interrupts to the last known exception level in the non-secure 677 state. The former should save the SP context, restore the non-secure context and 678 arrange for entry into the non-secure state so that the interrupt can be 679 handled. 680 681 ##### 2.3.2.2 Interrupt exit 682 When the Secure Payload has finished handling a Secure-EL1 interrupt, it could 683 return control back to the SPD service through a SMC32 or SMC64. The SPD service 684 should handle this secure monitor call so that execution resumes in the 685 exception level and the security state from where the Secure-EL1 interrupt was 686 originally taken. 687 688 ##### 2.3.2.3 Test secure payload dispatcher behavior 689 The example TSPD service registers a handler for Secure-EL1 interrupts taken 690 from the non-secure state. Its handler `tspd_secure_el1_interrupt_handler()` 691 takes the following actions upon being invoked. 692 693 1. 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 697 2. 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 701 3. It saves the system register context for the non-secure state by calling 702 `cm_el1_sysregs_context_save(NON_SECURE);`. 703 704 4. 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 710 5. It restores the system register context for the secure state by calling 711 `cm_el1_sysregs_context_restore(SECURE);`. 712 713 6. 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 716 7. 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 721 The figure below describes how the interrupt handling is implemented by the TSPD 722 when a Secure-EL1 interrupt is generated when execution is in the non-secure 723 state. 724 725  726 727 The TSP issues an SMC with `TSP_HANDLED_S_EL1_FIQ` as the function identifier to 728 signal completion of interrupt handling. 729 730 The TSP issues an SMC with `TSP_PREEMPTED` as the function identifier to signal 731 generation of a non-secure interrupt in Secure-EL1. 732 733 The TSPD service takes the following actions in `tspd_smc_handler()` function 734 upon receiving an SMC with `TSP_HANDLED_S_EL1_FIQ` and `TSP_PREEMPTED` as the 735 function identifiers: 736 737 1. 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 740 2. 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 746 3. 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 750 4. 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 757 5. 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 761 6. `tspd_smc_handler()` returns a reference to the non-secure `cpu_context` 762 as the return value. 763 764 As mentioned in 4. above, if a non-secure interrupt preempts the TSP execution 765 then the non-secure software issues an SMC with `TSP_FID_RESUME` as the function 766 identifier to resume TSP execution. The TSPD service takes the following actions 767 in `tspd_smc_handler()` function upon receiving this SMC: 768 769 1. It ensures that the call originated from the non secure state. An 770 assertion is raised otherwise. 771 772 2. 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 776 3. Restores the secure context by calling 777 `cm_el1_sysregs_context_restore(SECURE)` 778 779 4. 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 782 5. `tspd_smc_handler()` returns a reference to the secure `cpu_context` as the 783 return value. 784 785 The figure below describes how the TSP/TSPD handle a non-secure interrupt when 786 it is generated during execution in the TSP with `PSTATE.I` = 0. 787 788  789 790 791 #### 2.3.3 Secure payload 792 The SP should implement one or both of the synchronous and asynchronous 793 interrupt handling models depending upon the interrupt routing model it has 794 chosen (as described in 2.2.3). 795 796 In the synchronous model, it should begin handling a Secure-EL1 interrupt after 797 receiving control from the SPD service at an entrypoint agreed upon during build 798 time or during the registration phase. Before handling the interrupt, the SP 799 should save any Secure-EL1 system register context which is needed for resuming 800 normal execution in the SP later e.g. `SPSR_EL1, `ELR_EL1`. After handling the 801 interrupt, the SP could return control back to the exception level and security 802 state where the interrupt was originally taken from. The SP should use an SMC32 803 or SMC64 to ask the SPD service to do this. 804 805 In the asynchronous model, the Secure Payload is responsible for handling 806 non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception 807 vector table when `PSTATE.I` and `PSTATE.F` bits are 0. As described earlier, 808 when a non-secure interrupt is generated, the SP should coordinate with the SPD 809 service to pass control back to the non-secure state in the last known exception 810 level. This will allow the non-secure interrupt to be handled in the non-secure 811 state. 812 813 ##### 2.3.3.1 Test secure payload behavior 814 The 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 816 handover agreement described in Section 2.2.2.1 is maintained. It updates some 817 statistics by calling `tsp_update_sync_fiq_stats()`. It then calls 818 `tsp_fiq_handler()` which. 819 820 1. 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 824 2. 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 830 The TSP passes control back to the TSPD by issuing an SMC64 with 831 `TSP_HANDLED_S_EL1_FIQ` as the function identifier. 832 833 The TSP handles interrupts under the asynchronous model as follows. 834 835 1. Secure-EL1 interrupts are handled by calling the `tsp_fiq_handler()` 836 function. The function has been described above. 837 838 2. 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
