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 /*
  12  * Interrupt controller types available. You can find a particular one with
  13  * irq_first_device_type()
  14  */
  15 enum irq_dev_t {
  16         X86_IRQT_BASE,          /* Base controller */
  17         X86_IRQT_ITSS,          /* ITSS controller, e.g. on APL */
  18         X86_IRQT_ACPI_GPE,      /* ACPI General-Purpose Events controller */
  19         SANDBOX_IRQT_BASE,      /* Sandbox testing */
  20 };
  21
  22 /**
  23  * struct irq - A single irq line handled by an interrupt controller
  24  *
  25  * @dev: IRQ device that handles this irq
  26  * @id: ID to identify this irq with the device
  27  */
  28 struct irq {
  29         struct udevice *dev;
  30         ulong id;
  31 };
  32
  33 /**
  34  * struct irq_ops - Operations for the IRQ
  35  *
  36  * Each IRQ device can handle mulitple IRQ lines
  37  */
  38 struct irq_ops {
  39         /**
  40          * route_pmc_gpio_gpe() - Get the GPIO for an event
  41          *
  42          * @dev: IRQ device
  43          * @pmc_gpe_num: Event number to check
  44          * @returns GPIO for the event, or -ENOENT if none
  45          */
  46         int (*route_pmc_gpio_gpe)(struct udevice *dev, uint pmc_gpe_num);
  47
  48         /**
  49          * set_polarity() - Set the IRQ polarity
  50          *
  51          * @dev: IRQ device
  52          * @irq: Interrupt number to set
  53          * @active_low: true if active low, false for active high
  54          * @return 0 if OK, -EINVAL if @irq is invalid
  55          */
  56         int (*set_polarity)(struct udevice *dev, uint irq, bool active_low);
  57
  58         /**
  59          * snapshot_polarities() - record IRQ polarities for later restore
  60          *
  61          * @dev: IRQ device
  62          * @return 0
  63          */
  64         int (*snapshot_polarities)(struct udevice *dev);
  65
  66         /**
  67          * restore_polarities() - restore IRQ polarities
  68          *
  69          * @dev: IRQ device
  70          * @return 0
  71          */
  72         int (*restore_polarities)(struct udevice *dev);
  73
  74         /**
  75          * read_and_clear() - get the value of an interrupt and clear it
  76          *
  77          * Clears the interrupt if pending
  78          *
  79          * @irq: IRQ line
  80          * @return 0 if interrupt is not pending, 1 if it was (and so has been
  81          *      cleared), -ve on error
  82          */
  83         int (*read_and_clear)(struct irq *irq);
  84         /**
  85          * of_xlate - Translate a client's device-tree (OF) irq specifier.
  86          *
  87          * The irq core calls this function as the first step in implementing
  88          * a client's irq_get_by_*() call.
  89          *
  90          * If this function pointer is set to NULL, the irq core will use a
  91          * default implementation, which assumes #interrupt-cells = <1>, and
  92          * that the DT cell contains a simple integer irq ID.
  93          *
  94          * @irq:        The irq struct to hold the translation result.
  95          * @args:       The irq specifier values from device tree.
  96          * @return 0 if OK, or a negative error code.
  97          */
  98         int (*of_xlate)(struct irq *irq, struct ofnode_phandle_args *args);
  99         /**
 100          * request - Request a translated irq.
 101          *
 102          * The irq core calls this function as the second step in
 103          * implementing a client's irq_get_by_*() call, following a successful
 104          * xxx_xlate() call, or as the only step in implementing a client's
 105          * irq_request() call.
 106          *
 107          * @irq:        The irq struct to request; this has been fille in by
 108          *              a previoux xxx_xlate() function call, or by the caller
 109          *              of irq_request().
 110          * @return 0 if OK, or a negative error code.
 111          */
 112         int (*request)(struct irq *irq);
 113         /**
 114          * free - Free a previously requested irq.
 115          *
 116          * This is the implementation of the client irq_free() API.
 117          *
 118          * @irq:        The irq to free.
 119          * @return 0 if OK, or a negative error code.
 120          */
 121         int (*free)(struct irq *irq);
 122 };
 123
 124 #define irq_get_ops(dev)        ((struct irq_ops *)(dev)->driver->ops)
 125
 126 /**
 127  * irq_route_pmc_gpio_gpe() - Get the GPIO for an event
 128  *
 129  * @dev: IRQ device
 130  * @pmc_gpe_num: Event number to check
 131  * @returns GPIO for the event, or -ENOENT if none
 132  */
 133 int irq_route_pmc_gpio_gpe(struct udevice *dev, uint pmc_gpe_num);
 134
 135 /**
 136  * irq_set_polarity() - Set the IRQ polarity
 137  *
 138  * @dev: IRQ device
 139  * @irq: Interrupt number to set
 140  * @active_low: true if active low, false for active high
 141  * @return 0 if OK, -EINVAL if @irq is invalid
 142  */
 143 int irq_set_polarity(struct udevice *dev, uint irq, bool active_low);
 144
 145 /**
 146  * irq_snapshot_polarities() - record IRQ polarities for later restore
 147  *
 148  * @dev: IRQ device
 149  * @return 0
 150  */
 151 int irq_snapshot_polarities(struct udevice *dev);
 152
 153 /**
 154  * irq_restore_polarities() - restore IRQ polarities
 155  *
 156  * @dev: IRQ device
 157  * @return 0
 158  */
 159 int irq_restore_polarities(struct udevice *dev);
 160
 161 /**
 162  * read_and_clear() - get the value of an interrupt and clear it
 163  *
 164  * Clears the interrupt if pending
 165  *
 166  * @dev: IRQ device
 167  * @return 0 if interrupt is not pending, 1 if it was (and so has been
 168  *      cleared), -ve on error
 169  */
 170 int irq_read_and_clear(struct irq *irq);
 171
 172 /**
 173  * irq_get_by_index - Get/request an irq by integer index.
 174  *
 175  * This looks up and requests an irq. The index is relative to the client
 176  * device; each device is assumed to have n irqs associated with it somehow,
 177  * and this function finds and requests one of them. The mapping of client
 178  * device irq indices to provider irqs may be via device-tree
 179  * properties, board-provided mapping tables, or some other mechanism.
 180  *
 181  * @dev:        The client device.
 182  * @index:      The index of the irq to request, within the client's list of
 183  *              irqs.
 184  * @irq:        A pointer to a irq struct to initialise.
 185  * @return 0 if OK, or a negative error code.
 186  */
 187 int irq_get_by_index(struct udevice *dev, int index, struct irq *irq);
 188
 189 /**
 190  * irq_request - Request a irq by provider-specific ID.
 191  *
 192  * This requests a irq using a provider-specific ID. Generally, this function
 193  * should not be used, since irq_get_by_index/name() provide an interface that
 194  * better separates clients from intimate knowledge of irq providers.
 195  * However, this function may be useful in core SoC-specific code.
 196  *
 197  * @dev:        The irq provider device.
 198  * @irq:        A pointer to a irq struct to initialise. The caller must
 199  *              have already initialised any field in this struct which the
 200  *              irq provider uses to identify the irq.
 201  * @return 0 if OK, or a negative error code.
 202  */
 203 int irq_request(struct udevice *dev, struct irq *irq);
 204
 205 /**
 206  * irq_free - Free a previously requested irq.
 207  *
 208  * @irq:        A irq struct that was previously successfully requested by
 209  *              irq_request/get_by_*().
 210  * @return 0 if OK, or a negative error code.
 211  */
 212 int irq_free(struct irq *irq);
 213
 214 /**
 215  * irq_first_device_type() - Get a particular interrupt controller
 216  *
 217  * On success this returns an activated interrupt device.
 218  *
 219  * @type: Type to find
 220  * @devp: Returns the device, if found
 221  * @return 0 if OK, -ENODEV if not found, other -ve error if uclass failed to
 222  *      probe
 223  */
 224 int irq_first_device_type(enum irq_dev_t type, struct udevice **devp);
 225
 226 #endif