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