1Platform Interrupt Controller API documentation 2=============================================== 3 4.. section-numbering:: 5 :suffix: . 6 7.. contents:: 8 9This document lists the optional platform interrupt controller API that 10abstracts the runtime configuration and control of interrupt controller from the 11generic code. The mandatory APIs are described in the `porting guide`__. 12 13.. __: porting-guide.rst#interrupt-management-framework-in-bl31 14 15Function: unsigned int plat_ic_get_running_priority(void); [optional] 16~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 17 18:: 19 20 Argument : void 21 Return : unsigned int 22 23This API should return the priority of the interrupt the PE is currently 24servicing. This must be be called only after an interrupt has already been 25acknowledged via. ``plat_ic_acknowledge_interrupt``. 26 27In the case of ARM standard platforms using GIC, the *Running Priority Register* 28is read to determine the priority of the interrupt. 29 30Function: int plat_ic_is_spi(unsigned int id); [optional] 31~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 32 33:: 34 35 Argument : unsigned int 36 Return : int 37 38The API should return whether the interrupt ID (first parameter) is categorized 39as a Shared Peripheral Interrupt. Shared Peripheral Interrupts are typically 40associated to system-wide peripherals, and these interrupts can target any PE in 41the system. 42 43Function: int plat_ic_is_ppi(unsigned int id); [optional] 44~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 45 46:: 47 48 Argument : unsigned int 49 Return : int 50 51The API should return whether the interrupt ID (first parameter) is categorized 52as a Private Peripheral Interrupt. Private Peripheral Interrupts are typically 53associated with peripherals that are private to each PE. Interrupts from private 54peripherals target to that PE only. 55 56Function: int plat_ic_is_sgi(unsigned int id); [optional] 57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 58 59:: 60 61 Argument : unsigned int 62 Return : int 63 64The API should return whether the interrupt ID (first parameter) is categorized 65as a Software Generated Interrupt. Software Generated Interrupts are raised by 66explicit programming by software, and are typically used in inter-PE 67communication. Secure SGIs are reserved for use by Secure world software. 68 69Function: unsigned int plat_ic_get_interrupt_active(unsigned int id); [optional] 70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 71 72:: 73 74 Argument : unsigned int 75 Return : int 76 77This API should return the *active* status of the interrupt ID specified by the 78first parameter, ``id``. 79 80In case of ARM standard platforms using GIC, the implementation of the API reads 81the GIC *Set Active Register* to read and return the active status of the 82interrupt. 83 84Function: void plat_ic_enable_interrupt(unsigned int id); [optional] 85~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 86 87:: 88 89 Argument : unsigned int 90 Return : void 91 92This 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 95In case of ARM standard platforms using GIC, the implementation of the API 96inserts barrier to make memory updates visible before enabling interrupt, and 97then writes to GIC *Set Enable Register* to enable the interrupt. 98 99Function: void plat_ic_disable_interrupt(unsigned int id); [optional] 100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 102:: 103 104 Argument : unsigned int 105 Return : void 106 107This 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 110In case of ARM standard platforms using GIC, the implementation of the API 111writes to GIC *Clear Enable Register* to disable the interrupt, and inserts 112barrier to make memory updates visible afterwards. 113 114Function: 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 123This API should set the priority of the interrupt specified by first parameter 124``id`` to the value set by the second parameter ``priority``. 125 126In case of ARM standard platforms using GIC, the implementation of the API 127writes to GIC *Priority Register* set interrupt priority. 128 129Function: int plat_ic_has_interrupt_type(unsigned int type); [optional] 130~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 131 132:: 133 134 Argument : unsigned int 135 Return : int 136 137This API should return whether the platform supports a given interrupt type. The 138parameter ``type`` shall be one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, or 139``INTR_TYPE_NS``. 140 141In case of ARM standard platforms using GICv3, the implementation of the API 142returns ``1`` for all interrupt types. 143 144In 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 146option ``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 164Function: 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 173This API should set the interrupt specified by first parameter ``id`` to the 174type specified by second parameter ``type``. The ``type`` parameter can be 175one 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 183In case of ARM standard platforms using GIC, the implementation of the API 184writes to the GIC *Group Register* and *Group Modifier Register* (only GICv3) to 185assign the interrupt to the right group. 186 187For 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 195For 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 203Function: 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 212This API should raise an EL3 SGI. The first parameter, ``sgi_num``, specifies 213the ID of the SGI. The second parameter, ``target``, must be the MPIDR of the 214target PE. 215 216In case of ARM standard platforms using GIC, the implementation of the API 217inserts barrier to make memory updates visible before raising SGI, then writes 218to appropriate *SGI Register* in order to raise the EL3 SGI. 219 220Function: 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 230This API should set the routing mode of Share Peripheral Interrupt (SPI) 231specified by first parameter ``id`` to that specified by the second parameter 232``routing_mode``. 233 234The ``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 242In case of ARM standard platforms using GIC, the implementation of the API 243writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set 244the routing. 245 246Function: void plat_ic_set_interrupt_pending(unsigned int id); [optional] 247~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 248 249:: 250 251 Argument : unsigned int 252 Return : void 253 254This API should set the interrupt specified by first parameter ``id`` to 255*Pending*. 256 257In case of ARM standard platforms using GIC, the implementation of the API 258inserts barrier to make memory updates visible before setting interrupt pending, 259and writes to the GIC *Set Pending Register* to set the interrupt pending 260status. 261 262Function: void plat_ic_clear_interrupt_pending(unsigned int id); [optional] 263~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 264 265:: 266 267 Argument : unsigned int 268 Return : void 269 270This API should clear the *Pending* status of the interrupt specified by first 271parameter ``id``. 272 273In case of ARM standard platforms using GIC, the implementation of the API 274writes to the GIC *Clear Pending Register* to clear the interrupt pending 275status, and inserts barrier to make memory updates visible afterwards. 276 277Function: unsigned int plat_ic_set_priority_mask(unsigned int id); [optional] 278~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 279 280:: 281 282 Argument : unsigned int 283 Return : int 284 285This API should set the priority mask (first parameter) in the interrupt 286controller such that only interrupts of higher priority than the supplied one 287may be signalled to the PE. The API should return the current priority value 288that it's overwriting. 289 290In case of ARM standard platforms using GIC, the implementation of the API 291inserts to order memory updates before updating mask, then writes to the GIC 292*Priority Mask Register*, and make sure memory updates are visible before 293potential trigger due to mask update. 294 295---- 296 297*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* 298