blob: 4de39d1e5a9ccd39714d6e4622b5950d13c708a1 [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Platform Interrupt Controller API
2=================================
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +01003
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +01004This document lists the optional platform interrupt controller API that
5abstracts the runtime configuration and control of interrupt controller from the
Paul Beesleyf8640672019-04-12 14:19:42 +01006generic code. The mandatory APIs are described in the
7:ref:`Porting Guide <porting_guide_imf_in_bl31>`.
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +01008
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
Antonio Nino Diaz56b68ad2019-02-28 13:35:21 +000019acknowledged via ``plat_ic_acknowledge_interrupt``.
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +010020
Dan Handley610e7e12018-03-01 18:44:00 +000021In the case of Arm standard platforms using GIC, the *Running Priority Register*
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +010022is read to determine the priority of the interrupt.
23
Jeenu Viswambharan522a4652017-09-22 08:32:09 +010024Function: 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
Jeenu Viswambharan24e70292017-09-22 08:32:09 +010063Function: 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
Dan Handley610e7e12018-03-01 18:44:00 +000074In case of Arm standard platforms using GIC, the implementation of the API reads
Jeenu Viswambharan24e70292017-09-22 08:32:09 +010075the GIC *Set Active Register* to read and return the active status of the
76interrupt.
77
Jeenu Viswambharan0fcdfff2017-09-22 08:32:09 +010078Function: 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
Dan Handley610e7e12018-03-01 18:44:00 +000089In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharan0fcdfff2017-09-22 08:32:09 +010090inserts 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
Dan Handley610e7e12018-03-01 18:44:00 +0000104In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharan0fcdfff2017-09-22 08:32:09 +0100105writes to GIC *Clear Enable Register* to disable the interrupt, and inserts
106barrier to make memory updates visible afterwards.
107
Jeenu Viswambharan447b89d2017-09-22 08:32:09 +0100108Function: 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
Dan Handley610e7e12018-03-01 18:44:00 +0000120In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharan447b89d2017-09-22 08:32:09 +0100121writes to GIC *Priority Register* set interrupt priority.
122
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500123Function: bool plat_ic_has_interrupt_type(unsigned int type); [optional]
124~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100125
126::
127
128 Argument : unsigned int
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500129 Return : bool
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100130
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
Dan Handley610e7e12018-03-01 18:44:00 +0000135In case of Arm standard platforms using GICv3, the implementation of the API
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500136returns *true* for all interrupt types.
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100137
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500138In case of Arm standard platforms using GICv2, the API always return *true* for
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100139``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
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500144 - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns *false*, indicating no support
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100145 for EL3 interrupts.
146
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500147 - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns *true*, indicating support for
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100148 EL3 interrupts.
149
150- For interrupt type ``INTR_TYPE_S_EL1``:
151
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500152 - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns *true*, indicating support for
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100153 Secure EL1 interrupts.
154
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500155 - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns *false*, indicating no support
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100156 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
Dan Handley610e7e12018-03-01 18:44:00 +0000177In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100178writes 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
Jeenu Viswambharanab14e9b2017-09-22 08:32:09 +0100197Function: 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
Dan Handley610e7e12018-03-01 18:44:00 +0000210In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharanab14e9b2017-09-22 08:32:09 +0100211inserts barrier to make memory updates visible before raising SGI, then writes
212to appropriate *SGI Register* in order to raise the EL3 SGI.
213
Jeenu Viswambharandce70b32017-09-22 08:32:09 +0100214Function: 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
Dan Handley610e7e12018-03-01 18:44:00 +0000236In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharandce70b32017-09-22 08:32:09 +0100237writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set
238the routing.
239
Jeenu Viswambharaneb1c12c2017-09-22 08:32:09 +0100240Function: 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
Dan Handley610e7e12018-03-01 18:44:00 +0000251In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharaneb1c12c2017-09-22 08:32:09 +0100252inserts 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
Dan Handley610e7e12018-03-01 18:44:00 +0000267In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharaneb1c12c2017-09-22 08:32:09 +0100268writes to the GIC *Clear Pending Register* to clear the interrupt pending
269status, and inserts barrier to make memory updates visible afterwards.
270
Jeenu Viswambharan62505072017-09-22 08:32:09 +0100271Function: 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
Dan Handley610e7e12018-03-01 18:44:00 +0000284In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharan62505072017-09-22 08:32:09 +0100285inserts 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
Madhukar Pappireddy86350ae2020-07-29 09:37:25 -0500289.. _plat_ic_get_interrupt_id:
290
Jeenu Viswambharan055af4b2017-10-24 15:13:59 +0100291Function: unsigned int plat_ic_get_interrupt_id(unsigned int raw); [optional]
292~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293
294::
295
296 Argument : unsigned int
297 Return : unsigned int
298
299This API should extract and return the interrupt number from the raw value
300obtained by the acknowledging the interrupt (read using
301``plat_ic_acknowledge_interrupt()``). If the interrupt ID is invalid, this API
302should return ``INTR_ID_UNAVAILABLE``.
303
Dan Handley610e7e12018-03-01 18:44:00 +0000304In case of Arm standard platforms using GIC, the implementation of the API
Jeenu Viswambharan055af4b2017-10-24 15:13:59 +0100305masks out the interrupt ID field from the acknowledged value from GIC.
306
Paul Beesleyf8640672019-04-12 14:19:42 +0100307--------------
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +0100308
Madhukar Pappireddy67ac77c2023-09-06 16:50:22 -0500309*Copyright (c) 2017-2023, Arm Limited and Contributors. All rights reserved.*