blob: 795c085625ccf3dcdb303f4d011996d18b9900f5 [file] [log] [blame]
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +01001Platform 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
Jeenu Viswambharan522a4652017-09-22 08:32:09 +010030Function: 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
Jeenu Viswambharan24e70292017-09-22 08:32:09 +010069Function: 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
Jeenu Viswambharan0fcdfff2017-09-22 08:32:09 +010084Function: 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
Jeenu Viswambharan447b89d2017-09-22 08:32:09 +0100114Function: 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
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100129Function: 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
Jeenu Viswambharanab14e9b2017-09-22 08:32:09 +0100203Function: 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
Jeenu Viswambharandce70b32017-09-22 08:32:09 +0100220Function: 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
Jeenu Viswambharaneb1c12c2017-09-22 08:32:09 +0100246Function: 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
Jeenu Viswambharan62505072017-09-22 08:32:09 +0100277Function: 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
Jeenu Viswambharanb1e957e2017-09-22 08:32:09 +0100295----
296
297*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.*