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