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