blob: 5638c10128e9c3cfda63539d131d7375966dfed0 [file] [log] [blame]
Simon Glass79d66a62019-12-06 21:41:58 -07001/* 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
Simon Glassf4955132020-07-07 13:11:41 -060011struct acpi_irq;
12struct ofnode_phandle_args;
13
Simon Glassba876072020-02-06 09:54:57 -070014/*
15 * Interrupt controller types available. You can find a particular one with
16 * irq_first_device_type()
17 */
18enum 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
Simon Glass79d66a62019-12-06 21:41:58 -070025/**
Simon Glass02554352020-02-06 09:55:00 -070026 * 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
Simon Glassf4955132020-07-07 13:11:41 -060030 * @flags: Flags associated with this interrupt (IRQ_TYPE_...)
Simon Glass02554352020-02-06 09:55:00 -070031 */
32struct irq {
33 struct udevice *dev;
34 ulong id;
Simon Glassf4955132020-07-07 13:11:41 -060035 ulong flags;
Simon Glass02554352020-02-06 09:55:00 -070036};
37
38/**
Simon Glass79d66a62019-12-06 21:41:58 -070039 * struct irq_ops - Operations for the IRQ
Simon Glass02554352020-02-06 09:55:00 -070040 *
41 * Each IRQ device can handle mulitple IRQ lines
Simon Glass79d66a62019-12-06 21:41:58 -070042 */
43struct 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);
Simon Glass02554352020-02-06 09:55:00 -070078
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 *
Paul Barker99a4e582023-08-14 20:13:35 +0100112 * @irq: The irq struct to request; this has been filled in by
Simon Glass02554352020-02-06 09:55:00 -0700113 * 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);
Simon Glassf4955132020-07-07 13:11:41 -0600127
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
Simon Glass79d66a62019-12-06 21:41:58 -0700141};
142
143#define irq_get_ops(dev) ((struct irq_ops *)(dev)->driver->ops)
144
145/**
Simon Glassf4955132020-07-07 13:11:41 -0600146 * 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()
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100150 * Return: true if valid, false if not
Simon Glassf4955132020-07-07 13:11:41 -0600151 */
152static inline bool irq_is_valid(const struct irq *irq)
153{
154 return irq->dev != NULL;
155}
156
157/**
Simon Glass79d66a62019-12-06 21:41:58 -0700158 * 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 */
164int 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
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100172 * Return: 0 if OK, -EINVAL if @irq is invalid
Simon Glass79d66a62019-12-06 21:41:58 -0700173 */
174int 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
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100180 * Return: 0
Simon Glass79d66a62019-12-06 21:41:58 -0700181 */
182int irq_snapshot_polarities(struct udevice *dev);
183
184/**
185 * irq_restore_polarities() - restore IRQ polarities
186 *
187 * @dev: IRQ device
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100188 * Return: 0
Simon Glass79d66a62019-12-06 21:41:58 -0700189 */
190int irq_restore_polarities(struct udevice *dev);
191
Simon Glassba876072020-02-06 09:54:57 -0700192/**
Simon Glass02554352020-02-06 09:55:00 -0700193 * read_and_clear() - get the value of an interrupt and clear it
194 *
195 * Clears the interrupt if pending
196 *
197 * @dev: IRQ device
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100198 * Return: 0 if interrupt is not pending, 1 if it was (and so has been
Simon Glass02554352020-02-06 09:55:00 -0700199 * cleared), -ve on error
200 */
201int irq_read_and_clear(struct irq *irq);
202
Simon Glass3e57ad92021-08-07 07:24:11 -0600203struct 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
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100227 * Return: 0 if OK, or a negative error code
Simon Glass3e57ad92021-08-07 07:24:11 -0600228 */
229int irq_get_by_phandle(struct udevice *dev, const struct phandle_2_arg *cells,
230 struct irq *irq);
231
Simon Glass02554352020-02-06 09:55:00 -0700232/**
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.
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100245 * Return: 0 if OK, or a negative error code.
Simon Glass02554352020-02-06 09:55:00 -0700246 */
247int 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.
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100261 * Return: 0 if OK, or a negative error code.
Simon Glass02554352020-02-06 09:55:00 -0700262 */
263int 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_*().
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100270 * Return: 0 if OK, or a negative error code.
Simon Glass02554352020-02-06 09:55:00 -0700271 */
272int irq_free(struct irq *irq);
273
274/**
Simon Glassba876072020-02-06 09:54:57 -0700275 * 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
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100281 * Return: 0 if OK, -ENODEV if not found, other -ve error if uclass failed to
Simon Glassba876072020-02-06 09:54:57 -0700282 * probe
283 */
284int irq_first_device_type(enum irq_dev_t type, struct udevice **devp);
285
Simon Glassf4955132020-07-07 13:11:41 -0600286/**
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
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100294 * Return: ACPI pin number or -ve on error
Simon Glassf4955132020-07-07 13:11:41 -0600295 */
296int irq_get_acpi(const struct irq *irq, struct acpi_irq *acpi_irq);
297
Simon Glass79d66a62019-12-06 21:41:58 -0700298#endif