Merge https://source.denx.de/u-boot/custodians/u-boot-marvell
[platform/kernel/u-boot.git] / include / irq.h
1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * IRQ is a type of interrupt controller used on recent Intel SoC.
4  *
5  * Copyright 2019 Google LLC
6  */
7
8 #ifndef __irq_H
9 #define __irq_H
10
11 struct acpi_irq;
12 struct ofnode_phandle_args;
13
14 /*
15  * Interrupt controller types available. You can find a particular one with
16  * irq_first_device_type()
17  */
18 enum irq_dev_t {
19         X86_IRQT_BASE,          /* Base controller */
20         X86_IRQT_ITSS,          /* ITSS controller, e.g. on APL */
21         X86_IRQT_ACPI_GPE,      /* ACPI General-Purpose Events controller */
22         SANDBOX_IRQT_BASE,      /* Sandbox testing */
23 };
24
25 /**
26  * struct irq - A single irq line handled by an interrupt controller
27  *
28  * @dev: IRQ device that handles this irq
29  * @id: ID to identify this irq with the device
30  * @flags: Flags associated with this interrupt (IRQ_TYPE_...)
31  */
32 struct irq {
33         struct udevice *dev;
34         ulong id;
35         ulong flags;
36 };
37
38 /**
39  * struct irq_ops - Operations for the IRQ
40  *
41  * Each IRQ device can handle mulitple IRQ lines
42  */
43 struct irq_ops {
44         /**
45          * route_pmc_gpio_gpe() - Get the GPIO for an event
46          *
47          * @dev: IRQ device
48          * @pmc_gpe_num: Event number to check
49          * @returns GPIO for the event, or -ENOENT if none
50          */
51         int (*route_pmc_gpio_gpe)(struct udevice *dev, uint pmc_gpe_num);
52
53         /**
54          * set_polarity() - Set the IRQ polarity
55          *
56          * @dev: IRQ device
57          * @irq: Interrupt number to set
58          * @active_low: true if active low, false for active high
59          * @return 0 if OK, -EINVAL if @irq is invalid
60          */
61         int (*set_polarity)(struct udevice *dev, uint irq, bool active_low);
62
63         /**
64          * snapshot_polarities() - record IRQ polarities for later restore
65          *
66          * @dev: IRQ device
67          * @return 0
68          */
69         int (*snapshot_polarities)(struct udevice *dev);
70
71         /**
72          * restore_polarities() - restore IRQ polarities
73          *
74          * @dev: IRQ device
75          * @return 0
76          */
77         int (*restore_polarities)(struct udevice *dev);
78
79         /**
80          * read_and_clear() - get the value of an interrupt and clear it
81          *
82          * Clears the interrupt if pending
83          *
84          * @irq: IRQ line
85          * @return 0 if interrupt is not pending, 1 if it was (and so has been
86          *      cleared), -ve on error
87          */
88         int (*read_and_clear)(struct irq *irq);
89         /**
90          * of_xlate - Translate a client's device-tree (OF) irq specifier.
91          *
92          * The irq core calls this function as the first step in implementing
93          * a client's irq_get_by_*() call.
94          *
95          * If this function pointer is set to NULL, the irq core will use a
96          * default implementation, which assumes #interrupt-cells = <1>, and
97          * that the DT cell contains a simple integer irq ID.
98          *
99          * @irq:        The irq struct to hold the translation result.
100          * @args:       The irq specifier values from device tree.
101          * @return 0 if OK, or a negative error code.
102          */
103         int (*of_xlate)(struct irq *irq, struct ofnode_phandle_args *args);
104         /**
105          * request - Request a translated irq.
106          *
107          * The irq core calls this function as the second step in
108          * implementing a client's irq_get_by_*() call, following a successful
109          * xxx_xlate() call, or as the only step in implementing a client's
110          * irq_request() call.
111          *
112          * @irq:        The irq struct to request; this has been fille in by
113          *              a previoux xxx_xlate() function call, or by the caller
114          *              of irq_request().
115          * @return 0 if OK, or a negative error code.
116          */
117         int (*request)(struct irq *irq);
118         /**
119          * free - Free a previously requested irq.
120          *
121          * This is the implementation of the client irq_free() API.
122          *
123          * @irq:        The irq to free.
124          * @return 0 if OK, or a negative error code.
125          */
126         int (*free)(struct irq *irq);
127
128 #if CONFIG_IS_ENABLED(ACPIGEN)
129         /**
130          * get_acpi() - Get the ACPI info for an irq
131          *
132          * This converts a irq to an ACPI structure for adding to the ACPI
133          * tables.
134          *
135          * @irq:        irq to convert
136          * @acpi_irq:   Output ACPI interrupt information
137          * @return ACPI pin number or -ve on error
138          */
139         int (*get_acpi)(const struct irq *irq, struct acpi_irq *acpi_irq);
140 #endif
141 };
142
143 #define irq_get_ops(dev)        ((struct irq_ops *)(dev)->driver->ops)
144
145 /**
146  * irq_is_valid() - Check if an IRQ is valid
147  *
148  * @irq:        IRQ description containing device and ID, e.g. previously
149  *              returned by irq_get_by_index()
150  * Return: true if valid, false if not
151  */
152 static inline bool irq_is_valid(const struct irq *irq)
153 {
154         return irq->dev != NULL;
155 }
156
157 /**
158  * irq_route_pmc_gpio_gpe() - Get the GPIO for an event
159  *
160  * @dev: IRQ device
161  * @pmc_gpe_num: Event number to check
162  * @returns GPIO for the event, or -ENOENT if none
163  */
164 int irq_route_pmc_gpio_gpe(struct udevice *dev, uint pmc_gpe_num);
165
166 /**
167  * irq_set_polarity() - Set the IRQ polarity
168  *
169  * @dev: IRQ device
170  * @irq: Interrupt number to set
171  * @active_low: true if active low, false for active high
172  * Return: 0 if OK, -EINVAL if @irq is invalid
173  */
174 int irq_set_polarity(struct udevice *dev, uint irq, bool active_low);
175
176 /**
177  * irq_snapshot_polarities() - record IRQ polarities for later restore
178  *
179  * @dev: IRQ device
180  * Return: 0
181  */
182 int irq_snapshot_polarities(struct udevice *dev);
183
184 /**
185  * irq_restore_polarities() - restore IRQ polarities
186  *
187  * @dev: IRQ device
188  * Return: 0
189  */
190 int irq_restore_polarities(struct udevice *dev);
191
192 /**
193  * read_and_clear() - get the value of an interrupt and clear it
194  *
195  * Clears the interrupt if pending
196  *
197  * @dev: IRQ device
198  * Return: 0 if interrupt is not pending, 1 if it was (and so has been
199  *      cleared), -ve on error
200  */
201 int irq_read_and_clear(struct irq *irq);
202
203 struct phandle_2_arg;
204 /**
205  * irq_get_by_phandle() - Get an irq by its phandle information (of-platadata)
206  *
207  * This function is used when of-platdata is enabled.
208  *
209  * This looks up an irq using the phandle info. With dtoc, each phandle in the
210  * 'interrupts-extended ' property is transformed into an idx representing the
211  * device. For example:
212  *
213  * interrupts-extended = <&acpi_gpe 0x3c 0>;
214  *
215  * might result in:
216  *
217  *      .interrupts_extended = {6, {0x3c, 0}},},
218  *
219  * indicating that the irq is udevice idx 6 in dt-plat.c with a arguments of
220  * 0x3c and 0.This function can return a valid irq given the above
221  * information. In this example it would return an irq containing the
222  * 'acpi_gpe' device and the irq ID 0x3c.
223  *
224  * @dev: Device containing the phandle
225  * @cells: Phandle info
226  * @irq: A pointer to a irq struct to initialise
227  * Return: 0 if OK, or a negative error code
228  */
229 int irq_get_by_phandle(struct udevice *dev, const struct phandle_2_arg *cells,
230                        struct irq *irq);
231
232 /**
233  * irq_get_by_index - Get/request an irq by integer index.
234  *
235  * This looks up and requests an irq. The index is relative to the client
236  * device; each device is assumed to have n irqs associated with it somehow,
237  * and this function finds and requests one of them. The mapping of client
238  * device irq indices to provider irqs may be via device-tree
239  * properties, board-provided mapping tables, or some other mechanism.
240  *
241  * @dev:        The client device.
242  * @index:      The index of the irq to request, within the client's list of
243  *              irqs.
244  * @irq:        A pointer to a irq struct to initialise.
245  * Return: 0 if OK, or a negative error code.
246  */
247 int irq_get_by_index(struct udevice *dev, int index, struct irq *irq);
248
249 /**
250  * irq_request - Request a irq by provider-specific ID.
251  *
252  * This requests a irq using a provider-specific ID. Generally, this function
253  * should not be used, since irq_get_by_index/name() provide an interface that
254  * better separates clients from intimate knowledge of irq providers.
255  * However, this function may be useful in core SoC-specific code.
256  *
257  * @dev:        The irq provider device.
258  * @irq:        A pointer to a irq struct to initialise. The caller must
259  *              have already initialised any field in this struct which the
260  *              irq provider uses to identify the irq.
261  * Return: 0 if OK, or a negative error code.
262  */
263 int irq_request(struct udevice *dev, struct irq *irq);
264
265 /**
266  * irq_free - Free a previously requested irq.
267  *
268  * @irq:        A irq struct that was previously successfully requested by
269  *              irq_request/get_by_*().
270  * Return: 0 if OK, or a negative error code.
271  */
272 int irq_free(struct irq *irq);
273
274 /**
275  * irq_first_device_type() - Get a particular interrupt controller
276  *
277  * On success this returns an activated interrupt device.
278  *
279  * @type: Type to find
280  * @devp: Returns the device, if found
281  * Return: 0 if OK, -ENODEV if not found, other -ve error if uclass failed to
282  *      probe
283  */
284 int irq_first_device_type(enum irq_dev_t type, struct udevice **devp);
285
286 /**
287  * irq_get_acpi() - Get the ACPI info for an irq
288  *
289  * This converts a irq to an ACPI structure for adding to the ACPI
290  * tables.
291  *
292  * @irq:        irq to convert
293  * @acpi_irq:   Output ACPI interrupt information
294  * Return: ACPI pin number or -ve on error
295  */
296 int irq_get_acpi(const struct irq *irq, struct acpi_irq *acpi_irq);
297
298 #endif