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
7:ref:`Porting Guide <porting_guide_imf_in_bl31>`.
8
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
19acknowledged via ``plat_ic_acknowledge_interrupt``.
20
21In the case of Arm standard platforms using GIC, the *Running Priority Register*
22is read to determine the priority of the interrupt.
23
24Function: 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
63Function: 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
74In case of Arm standard platforms using GIC, the implementation of the API reads
75the GIC *Set Active Register* to read and return the active status of the
76interrupt.
77
78Function: 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
89In case of Arm standard platforms using GIC, the implementation of the API
90inserts 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
104In case of Arm standard platforms using GIC, the implementation of the API
105writes to GIC *Clear Enable Register* to disable the interrupt, and inserts
106barrier to make memory updates visible afterwards.
107
108Function: 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
120In case of Arm standard platforms using GIC, the implementation of the API
121writes to GIC *Priority Register* set interrupt priority.
122
123Function: int plat_ic_has_interrupt_type(unsigned int type); [optional]
124~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125
126::
127
128    Argument : unsigned int
129    Return   : int
130
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
135In case of Arm standard platforms using GICv3, the implementation of the API
136returns ``1`` for all interrupt types.
137
138In case of Arm standard platforms using GICv2, the API always return ``1`` for
139``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
144  - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns ``0``, indicating no support
145    for EL3 interrupts.
146
147  - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns ``1``, indicating support for
148    EL3 interrupts.
149
150- For interrupt type ``INTR_TYPE_S_EL1``:
151
152  - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns ``1``, indicating support for
153    Secure EL1 interrupts.
154
155  - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns ``0``, indicating no support
156    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
177In case of Arm standard platforms using GIC, the implementation of the API
178writes 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
197Function: 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
210In case of Arm standard platforms using GIC, the implementation of the API
211inserts barrier to make memory updates visible before raising SGI, then writes
212to appropriate *SGI Register* in order to raise the EL3 SGI.
213
214Function: 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
236In case of Arm standard platforms using GIC, the implementation of the API
237writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set
238the routing.
239
240Function: 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
251In case of Arm standard platforms using GIC, the implementation of the API
252inserts 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
267In case of Arm standard platforms using GIC, the implementation of the API
268writes to the GIC *Clear Pending Register* to clear the interrupt pending
269status, and inserts barrier to make memory updates visible afterwards.
270
271Function: 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
284In case of Arm standard platforms using GIC, the implementation of the API
285inserts 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
289.. _plat_ic_get_interrupt_id:
290
291Function: 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
304In case of Arm standard platforms using GIC, the implementation of the API
305masks out the interrupt ID field from the acknowledged value from GIC.
306
307--------------
308
309*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.*
310