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