docs/components/platform-interrupt-controller-API.rst

4 This document lists the optional platform interrupt controller API that
5 abstracts the runtime configuration and control of interrupt controller from the
6 generic code. The mandatory APIs are described in the
17 This API should return the priority of the interrupt the PE is currently
21 In the case of Arm standard platforms using GIC, the *Running Priority Register*
22 is read to determine the priority of the interrupt.
32 The API should return whether the interrupt ID (first parameter) is categorized
35 the system.
45 The API should return whether the interrupt ID (first parameter) is categorized
58 The API should return whether the interrupt ID (first parameter) is categorized
71 This API should return the *active* status of the interrupt ID specified by the
74 In case of Arm standard platforms using GIC, the implementation of the API reads
75 the GIC *Set Active Register* to read and return the active status of the
86 This API should enable the interrupt ID specified by the first parameter,
87 ``id``. PEs in the system are expected to receive only enabled interrupts.
89 In case of Arm standard platforms using GIC, the implementation of the API
91 then writes to GIC *Set Enable Register* to enable the interrupt.
101 This API should disable the interrupt ID specified by the first parameter,
102 ``id``. PEs in the system are not expected to receive disabled interrupts.
104 In case of Arm standard platforms using GIC, the implementation of the API
105 writes to GIC *Clear Enable Register* to disable the interrupt, and inserts
117 This API should set the priority of the interrupt specified by first parameter
118 ``id`` to the value set by the second parameter ``priority``.
120 In case of Arm standard platforms using GIC, the implementation of the API
131 This API should return whether the platform supports a given interrupt type. The
135 In case of Arm standard platforms using GICv3, the implementation of the API
138 In case of Arm standard platforms using GICv2, the API always return *true* for
139 ``INTR_TYPE_NS``. Return value for other types depends on the value of build
167 This API should set the interrupt specified by first parameter ``id`` to the
171 - ``INTR_TYPE_NS``: interrupt is meant to be consumed by the Non-secure world.
177 In case of Arm standard platforms using GIC, the implementation of the API
178 writes to the GIC *Group Register* and *Group Modifier Register* (only GICv3) to
179 assign the interrupt to the right group.
193 - When the build option ``GICV2_G0_FOR_EL3`` is set to ``0`` (the default),
207 the ID of the SGI. The second parameter, ``target``, must be the MPIDR of the
210 In case of Arm standard platforms using GIC, the implementation of the API
212 to appropriate *SGI Register* in order to raise the EL3 SGI.
224 This API should set the routing mode of Share Peripheral Interrupt (SPI)
225 specified by first parameter ``id`` to that specified by the second parameter
230 - ``INTR_ROUTING_MODE_ANY`` means the interrupt can be routed to any PE in the
233 - ``INTR_ROUTING_MODE_PE`` means the interrupt is routed to the PE whose MPIDR
234   value is specified by the parameter ``mpidr``.
236 In case of Arm standard platforms using GIC, the implementation of the API
237 writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set
238 the routing.
248 This API should set the interrupt specified by first parameter ``id`` to
251 In case of Arm standard platforms using GIC, the implementation of the API
253 and writes to the GIC *Set Pending Register* to set the interrupt pending
264 This API should clear the *Pending* status of the interrupt specified by first
267 In case of Arm standard platforms using GIC, the implementation of the API
268 writes to the GIC *Clear Pending Register* to clear the interrupt pending
279 This API should set the priority mask (first parameter) in the interrupt
280 controller such that only interrupts of higher priority than the supplied one
281 may be signalled to the PE. The API should return the current priority value
284 In case of Arm standard platforms using GIC, the implementation of the API
286 then writes to the GIC *Priority Mask Register*, and make sure memory updates
297 This API performs the operations of plat_ic_set_priority_mask along with
298 calling the errata workaround gicv3_apply_errata_wa_2384374(). This is
300 the current priority value that it's overwriting.
302 In case of Arm standard platforms using GIC, the implementation of the API
304 to the GIC *Priority Mask Register*, and make sure memory updates
318 This API should extract and return the interrupt number from the raw value
319 obtained by the acknowledging the interrupt (read using
320 ``plat_ic_acknowledge_interrupt()``). If the interrupt ID is invalid, this API
323 In case of Arm standard platforms using GIC, the implementation of the API
324 masks out the interrupt ID field from the acknowledged value from GIC.