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