1 Platform Interrupt Controller API documentation 2 =============================================== 3 4 .. section-numbering:: 5 :suffix: . 6 7 .. contents:: 8 9 This document lists the optional platform interrupt controller API that 10 abstracts the runtime configuration and control of interrupt controller from the 11 generic code. The mandatory APIs are described in the `porting guide`__. 12 13 .. __: porting-guide.rst#interrupt-management-framework-in-bl31 14 15 Function: unsigned int plat_ic_get_running_priority(void); [optional] 16 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 17 18 :: 19 20 Argument : void 21 Return : unsigned int 22 23 This API should return the priority of the interrupt the PE is currently 24 servicing. This must be be called only after an interrupt has already been 25 acknowledged via. ``plat_ic_acknowledge_interrupt``. 26 27 In the case of ARM standard platforms using GIC, the *Running Priority Register* 28 is read to determine the priority of the interrupt. 29 30 Function: int plat_ic_is_spi(unsigned int id); [optional] 31 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 32 33 :: 34 35 Argument : unsigned int 36 Return : int 37 38 The API should return whether the interrupt ID (first parameter) is categorized 39 as a Shared Peripheral Interrupt. Shared Peripheral Interrupts are typically 40 associated to system-wide peripherals, and these interrupts can target any PE in 41 the system. 42 43 Function: int plat_ic_is_ppi(unsigned int id); [optional] 44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 45 46 :: 47 48 Argument : unsigned int 49 Return : int 50 51 The API should return whether the interrupt ID (first parameter) is categorized 52 as a Private Peripheral Interrupt. Private Peripheral Interrupts are typically 53 associated with peripherals that are private to each PE. Interrupts from private 54 peripherals target to that PE only. 55 56 Function: int plat_ic_is_sgi(unsigned int id); [optional] 57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 58 59 :: 60 61 Argument : unsigned int 62 Return : int 63 64 The API should return whether the interrupt ID (first parameter) is categorized 65 as a Software Generated Interrupt. Software Generated Interrupts are raised by 66 explicit programming by software, and are typically used in inter-PE 67 communication. Secure SGIs are reserved for use by Secure world software. 68 69 Function: unsigned int plat_ic_get_interrupt_active(unsigned int id); [optional] 70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 71 72 :: 73 74 Argument : unsigned int 75 Return : int 76 77 This API should return the *active* status of the interrupt ID specified by the 78 first parameter, ``id``. 79 80 In case of ARM standard platforms using GIC, the implementation of the API reads 81 the GIC *Set Active Register* to read and return the active status of the 82 interrupt. 83 84 Function: void plat_ic_enable_interrupt(unsigned int id); [optional] 85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 86 87 :: 88 89 Argument : unsigned int 90 Return : void 91 92 This API should enable the interrupt ID specified by the first parameter, 93 ``id``. PEs in the system are expected to receive only enabled interrupts. 94 95 In case of ARM standard platforms using GIC, the implementation of the API 96 inserts barrier to make memory updates visible before enabling interrupt, and 97 then writes to GIC *Set Enable Register* to enable the interrupt. 98 99 Function: void plat_ic_disable_interrupt(unsigned int id); [optional] 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 102 :: 103 104 Argument : unsigned int 105 Return : void 106 107 This API should disable the interrupt ID specified by the first parameter, 108 ``id``. PEs in the system are not expected to receive disabled interrupts. 109 110 In case of ARM standard platforms using GIC, the implementation of the API 111 writes to GIC *Clear Enable Register* to disable the interrupt, and inserts 112 barrier to make memory updates visible afterwards. 113 114 Function: void plat_ic_set_interrupt_priority(unsigned int id, unsigned int priority); [optional] 115 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 116 117 :: 118 119 Argument : unsigned int 120 Argument : unsigned int 121 Return : void 122 123 This API should set the priority of the interrupt specified by first parameter 124 ``id`` to the value set by the second parameter ``priority``. 125 126 In case of ARM standard platforms using GIC, the implementation of the API 127 writes to GIC *Priority Register* set interrupt priority. 128 129 Function: int plat_ic_has_interrupt_type(unsigned int type); [optional] 130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 131 132 :: 133 134 Argument : unsigned int 135 Return : int 136 137 This API should return whether the platform supports a given interrupt type. The 138 parameter ``type`` shall be one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, or 139 ``INTR_TYPE_NS``. 140 141 In case of ARM standard platforms using GICv3, the implementation of the API 142 returns ``1`` for all interrupt types. 143 144 In case of ARM standard platforms using GICv2, the API always return ``1`` for 145 ``INTR_TYPE_NS``. Return value for other types depends on the value of build 146 option ``GICV2_G0_FOR_EL3``: 147 148 - For interrupt type ``INTR_TYPE_EL3``: 149 150 - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns ``0``, indicating no support 151 for EL3 interrupts. 152 153 - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns ``1``, indicating support for 154 EL3 interrupts. 155 156 - For interrupt type ``INTR_TYPE_S_EL1``: 157 158 - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns ``1``, indicating support for 159 Secure EL1 interrupts. 160 161 - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns ``0``, indicating no support 162 for Secure EL1 interrupts. 163 164 Function: void plat_ic_set_interrupt_type(unsigned int id, unsigned int type); [optional] 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 166 167 :: 168 169 Argument : unsigned int 170 Argument : unsigned int 171 Return : void 172 173 This API should set the interrupt specified by first parameter ``id`` to the 174 type specified by second parameter ``type``. The ``type`` parameter can be 175 one of: 176 177 - ``INTR_TYPE_NS``: interrupt is meant to be consumed by the Non-secure world. 178 179 - ``INTR_TYPE_S_EL1``: interrupt is meant to be consumed by Secure EL1. 180 181 - ``INTR_TYPE_EL3``: interrupt is meant to be consumed by EL3. 182 183 In case of ARM standard platforms using GIC, the implementation of the API 184 writes to the GIC *Group Register* and *Group Modifier Register* (only GICv3) to 185 assign the interrupt to the right group. 186 187 For GICv3: 188 189 - ``INTR_TYPE_NS`` maps to Group 1 interrupt. 190 191 - ``INTR_TYPE_S_EL1`` maps to Secure Group 1 interrupt. 192 193 - ``INTR_TYPE_EL3`` maps to Secure Group 0 interrupt. 194 195 For GICv2: 196 197 - ``INTR_TYPE_NS`` maps to Group 1 interrupt. 198 199 - When the build option ``GICV2_G0_FOR_EL3`` is set to ``0`` (the default), 200 ``INTR_TYPE_S_EL1`` maps to Group 0. Otherwise, ``INTR_TYPE_EL3`` maps to 201 Group 0 interrupt. 202 203 Function: void plat_ic_raise_el3_sgi(int sgi_num, u_register_t target); [optional] 204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 205 206 :: 207 208 Argument : int 209 Argument : u_register_t 210 Return : void 211 212 This API should raise an EL3 SGI. The first parameter, ``sgi_num``, specifies 213 the ID of the SGI. The second parameter, ``target``, must be the MPIDR of the 214 target PE. 215 216 In case of ARM standard platforms using GIC, the implementation of the API 217 inserts barrier to make memory updates visible before raising SGI, then writes 218 to appropriate *SGI Register* in order to raise the EL3 SGI. 219 220 Function: void plat_ic_set_spi_routing(unsigned int id, unsigned int routing_mode, u_register_t mpidr); [optional] 221 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 222 223 :: 224 225 Argument : unsigned int 226 Argument : unsigned int 227 Argument : u_register_t 228 Return : void 229 230 This API should set the routing mode of Share Peripheral Interrupt (SPI) 231 specified by first parameter ``id`` to that specified by the second parameter 232 ``routing_mode``. 233 234 The ``routing_mode`` parameter can be one of: 235 236 - ``INTR_ROUTING_MODE_ANY`` means the interrupt can be routed to any PE in the 237 system. The ``mpidr`` parameter is ignored in this case. 238 239 - ``INTR_ROUTING_MODE_PE`` means the interrupt is routed to the PE whose MPIDR 240 value is specified by the parameter ``mpidr``. 241 242 In case of ARM standard platforms using GIC, the implementation of the API 243 writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set 244 the routing. 245 246 Function: void plat_ic_set_interrupt_pending(unsigned int id); [optional] 247 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 248 249 :: 250 251 Argument : unsigned int 252 Return : void 253 254 This API should set the interrupt specified by first parameter ``id`` to 255 *Pending*. 256 257 In case of ARM standard platforms using GIC, the implementation of the API 258 inserts barrier to make memory updates visible before setting interrupt pending, 259 and writes to the GIC *Set Pending Register* to set the interrupt pending 260 status. 261 262 Function: void plat_ic_clear_interrupt_pending(unsigned int id); [optional] 263 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 264 265 :: 266 267 Argument : unsigned int 268 Return : void 269 270 This API should clear the *Pending* status of the interrupt specified by first 271 parameter ``id``. 272 273 In case of ARM standard platforms using GIC, the implementation of the API 274 writes to the GIC *Clear Pending Register* to clear the interrupt pending 275 status, and inserts barrier to make memory updates visible afterwards. 276 277 Function: unsigned int plat_ic_set_priority_mask(unsigned int id); [optional] 278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 279 280 :: 281 282 Argument : unsigned int 283 Return : int 284 285 This API should set the priority mask (first parameter) in the interrupt 286 controller such that only interrupts of higher priority than the supplied one 287 may be signalled to the PE. The API should return the current priority value 288 that it's overwriting. 289 290 In case of ARM standard platforms using GIC, the implementation of the API 291 inserts to order memory updates before updating mask, then writes to the GIC 292 *Priority Mask Register*, and make sure memory updates are visible before 293 potential trigger due to mask update. 294 295 ---- 296 297 *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* 298
