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