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 /**
 204  * irq_get_by_index - Get/request an irq by integer index.
 205  *
 206  * This looks up and requests an irq. The index is relative to the client
 207  * device; each device is assumed to have n irqs associated with it somehow,
 208  * and this function finds and requests one of them. The mapping of client
 209  * device irq indices to provider irqs may be via device-tree
 210  * properties, board-provided mapping tables, or some other mechanism.
 211  *
 212  * @dev:        The client device.
 213  * @index:      The index of the irq to request, within the client's list of
 214  *              irqs.
 215  * @irq:        A pointer to a irq struct to initialise.
 216  * @return 0 if OK, or a negative error code.
 217  */
 218 int irq_get_by_index(struct udevice *dev, int index, struct irq *irq);
 219
 220 /**
 221  * irq_request - Request a irq by provider-specific ID.
 222  *
 223  * This requests a irq using a provider-specific ID. Generally, this function
 224  * should not be used, since irq_get_by_index/name() provide an interface that
 225  * better separates clients from intimate knowledge of irq providers.
 226  * However, this function may be useful in core SoC-specific code.
 227  *
 228  * @dev:        The irq provider device.
 229  * @irq:        A pointer to a irq struct to initialise. The caller must
 230  *              have already initialised any field in this struct which the
 231  *              irq provider uses to identify the irq.
 232  * @return 0 if OK, or a negative error code.
 233  */
 234 int irq_request(struct udevice *dev, struct irq *irq);
 235
 236 /**
 237  * irq_free - Free a previously requested irq.
 238  *
 239  * @irq:        A irq struct that was previously successfully requested by
 240  *              irq_request/get_by_*().
 241  * @return 0 if OK, or a negative error code.
 242  */
 243 int irq_free(struct irq *irq);
 244
 245 /**
 246  * irq_first_device_type() - Get a particular interrupt controller
 247  *
 248  * On success this returns an activated interrupt device.
 249  *
 250  * @type: Type to find
 251  * @devp: Returns the device, if found
 252  * @return 0 if OK, -ENODEV if not found, other -ve error if uclass failed to
 253  *      probe
 254  */
 255 int irq_first_device_type(enum irq_dev_t type, struct udevice **devp);
 256
 257 /**
 258  * irq_get_acpi() - Get the ACPI info for an irq
 259  *
 260  * This converts a irq to an ACPI structure for adding to the ACPI
 261  * tables.
 262  *
 263  * @irq:        irq to convert
 264  * @acpi_irq:   Output ACPI interrupt information
 265  * @return ACPI pin number or -ve on error
 266  */
 267 int irq_get_acpi(const struct irq *irq, struct acpi_irq *acpi_irq);
 268
 269 #endif