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 11struct acpi_irq; 12struct ofnode_phandle_args; 13 14/* 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 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 */ 32struct 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 */ 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); 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 filled 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 */ 152static 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 */ 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 172 * Return: 0 if OK, -EINVAL if @irq is invalid 173 */ 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 180 * Return: 0 181 */ 182int irq_snapshot_polarities(struct udevice *dev); 183 184/** 185 * irq_restore_polarities() - restore IRQ polarities 186 * 187 * @dev: IRQ device 188 * Return: 0 189 */ 190int 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 */ 201int irq_read_and_clear(struct irq *irq); 202 203struct 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 */ 229int 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 */ 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. 261 * Return: 0 if OK, or a negative error code. 262 */ 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_*(). 270 * Return: 0 if OK, or a negative error code. 271 */ 272int 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 */ 284int 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 */ 296int irq_get_acpi(const struct irq *irq, struct acpi_irq *acpi_irq); 297 298#endif 299