irq.h 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298
  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. #ifndef __irq_H
  8. #define __irq_H
  9. struct acpi_irq;
  10. struct ofnode_phandle_args;
  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. * struct irq - A single irq line handled by an interrupt controller
  23. *
  24. * @dev: IRQ device that handles this irq
  25. * @id: ID to identify this irq with the device
  26. * @flags: Flags associated with this interrupt (IRQ_TYPE_...)
  27. */
  28. struct irq {
  29. struct udevice *dev;
  30. ulong id;
  31. ulong flags;
  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. * set_polarity() - Set the IRQ polarity
  49. *
  50. * @dev: IRQ device
  51. * @irq: Interrupt number to set
  52. * @active_low: true if active low, false for active high
  53. * @return 0 if OK, -EINVAL if @irq is invalid
  54. */
  55. int (*set_polarity)(struct udevice *dev, uint irq, bool active_low);
  56. /**
  57. * snapshot_polarities() - record IRQ polarities for later restore
  58. *
  59. * @dev: IRQ device
  60. * @return 0
  61. */
  62. int (*snapshot_polarities)(struct udevice *dev);
  63. /**
  64. * restore_polarities() - restore IRQ polarities
  65. *
  66. * @dev: IRQ device
  67. * @return 0
  68. */
  69. int (*restore_polarities)(struct udevice *dev);
  70. /**
  71. * read_and_clear() - get the value of an interrupt and clear it
  72. *
  73. * Clears the interrupt if pending
  74. *
  75. * @irq: IRQ line
  76. * @return 0 if interrupt is not pending, 1 if it was (and so has been
  77. * cleared), -ve on error
  78. */
  79. int (*read_and_clear)(struct irq *irq);
  80. /**
  81. * of_xlate - Translate a client's device-tree (OF) irq specifier.
  82. *
  83. * The irq core calls this function as the first step in implementing
  84. * a client's irq_get_by_*() call.
  85. *
  86. * If this function pointer is set to NULL, the irq core will use a
  87. * default implementation, which assumes #interrupt-cells = <1>, and
  88. * that the DT cell contains a simple integer irq ID.
  89. *
  90. * @irq: The irq struct to hold the translation result.
  91. * @args: The irq specifier values from device tree.
  92. * @return 0 if OK, or a negative error code.
  93. */
  94. int (*of_xlate)(struct irq *irq, struct ofnode_phandle_args *args);
  95. /**
  96. * request - Request a translated irq.
  97. *
  98. * The irq core calls this function as the second step in
  99. * implementing a client's irq_get_by_*() call, following a successful
  100. * xxx_xlate() call, or as the only step in implementing a client's
  101. * irq_request() call.
  102. *
  103. * @irq: The irq struct to request; this has been filled in by
  104. * a previoux xxx_xlate() function call, or by the caller
  105. * of irq_request().
  106. * @return 0 if OK, or a negative error code.
  107. */
  108. int (*request)(struct irq *irq);
  109. /**
  110. * free - Free a previously requested irq.
  111. *
  112. * This is the implementation of the client irq_free() API.
  113. *
  114. * @irq: The irq to free.
  115. * @return 0 if OK, or a negative error code.
  116. */
  117. int (*free)(struct irq *irq);
  118. #if CONFIG_IS_ENABLED(ACPIGEN)
  119. /**
  120. * get_acpi() - Get the ACPI info for an irq
  121. *
  122. * This converts a irq to an ACPI structure for adding to the ACPI
  123. * tables.
  124. *
  125. * @irq: irq to convert
  126. * @acpi_irq: Output ACPI interrupt information
  127. * @return ACPI pin number or -ve on error
  128. */
  129. int (*get_acpi)(const struct irq *irq, struct acpi_irq *acpi_irq);
  130. #endif
  131. };
  132. #define irq_get_ops(dev) ((struct irq_ops *)(dev)->driver->ops)
  133. /**
  134. * irq_is_valid() - Check if an IRQ is valid
  135. *
  136. * @irq: IRQ description containing device and ID, e.g. previously
  137. * returned by irq_get_by_index()
  138. * Return: true if valid, false if not
  139. */
  140. static inline bool irq_is_valid(const struct irq *irq)
  141. {
  142. return irq->dev != NULL;
  143. }
  144. /**
  145. * irq_route_pmc_gpio_gpe() - Get the GPIO for an event
  146. *
  147. * @dev: IRQ device
  148. * @pmc_gpe_num: Event number to check
  149. * @returns GPIO for the event, or -ENOENT if none
  150. */
  151. int irq_route_pmc_gpio_gpe(struct udevice *dev, uint pmc_gpe_num);
  152. /**
  153. * irq_set_polarity() - Set the IRQ polarity
  154. *
  155. * @dev: IRQ device
  156. * @irq: Interrupt number to set
  157. * @active_low: true if active low, false for active high
  158. * Return: 0 if OK, -EINVAL if @irq is invalid
  159. */
  160. int irq_set_polarity(struct udevice *dev, uint irq, bool active_low);
  161. /**
  162. * irq_snapshot_polarities() - record IRQ polarities for later restore
  163. *
  164. * @dev: IRQ device
  165. * Return: 0
  166. */
  167. int irq_snapshot_polarities(struct udevice *dev);
  168. /**
  169. * irq_restore_polarities() - restore IRQ polarities
  170. *
  171. * @dev: IRQ device
  172. * Return: 0
  173. */
  174. int irq_restore_polarities(struct udevice *dev);
  175. /**
  176. * read_and_clear() - get the value of an interrupt and clear it
  177. *
  178. * Clears the interrupt if pending
  179. *
  180. * @dev: IRQ device
  181. * Return: 0 if interrupt is not pending, 1 if it was (and so has been
  182. * cleared), -ve on error
  183. */
  184. int irq_read_and_clear(struct irq *irq);
  185. struct phandle_2_arg;
  186. /**
  187. * irq_get_by_phandle() - Get an irq by its phandle information (of-platadata)
  188. *
  189. * This function is used when of-platdata is enabled.
  190. *
  191. * This looks up an irq using the phandle info. With dtoc, each phandle in the
  192. * 'interrupts-extended ' property is transformed into an idx representing the
  193. * device. For example:
  194. *
  195. * interrupts-extended = <&acpi_gpe 0x3c 0>;
  196. *
  197. * might result in:
  198. *
  199. * .interrupts_extended = {6, {0x3c, 0}},},
  200. *
  201. * indicating that the irq is udevice idx 6 in dt-plat.c with a arguments of
  202. * 0x3c and 0.This function can return a valid irq given the above
  203. * information. In this example it would return an irq containing the
  204. * 'acpi_gpe' device and the irq ID 0x3c.
  205. *
  206. * @dev: Device containing the phandle
  207. * @cells: Phandle info
  208. * @irq: A pointer to a irq struct to initialise
  209. * Return: 0 if OK, or a negative error code
  210. */
  211. int irq_get_by_phandle(struct udevice *dev, const struct phandle_2_arg *cells,
  212. struct irq *irq);
  213. /**
  214. * irq_get_by_index - Get/request an irq by integer index.
  215. *
  216. * This looks up and requests an irq. The index is relative to the client
  217. * device; each device is assumed to have n irqs associated with it somehow,
  218. * and this function finds and requests one of them. The mapping of client
  219. * device irq indices to provider irqs may be via device-tree
  220. * properties, board-provided mapping tables, or some other mechanism.
  221. *
  222. * @dev: The client device.
  223. * @index: The index of the irq to request, within the client's list of
  224. * irqs.
  225. * @irq: A pointer to a irq struct to initialise.
  226. * Return: 0 if OK, or a negative error code.
  227. */
  228. int irq_get_by_index(struct udevice *dev, int index, struct irq *irq);
  229. /**
  230. * irq_request - Request a irq by provider-specific ID.
  231. *
  232. * This requests a irq using a provider-specific ID. Generally, this function
  233. * should not be used, since irq_get_by_index/name() provide an interface that
  234. * better separates clients from intimate knowledge of irq providers.
  235. * However, this function may be useful in core SoC-specific code.
  236. *
  237. * @dev: The irq provider device.
  238. * @irq: A pointer to a irq struct to initialise. The caller must
  239. * have already initialised any field in this struct which the
  240. * irq provider uses to identify the irq.
  241. * Return: 0 if OK, or a negative error code.
  242. */
  243. int irq_request(struct udevice *dev, struct irq *irq);
  244. /**
  245. * irq_free - Free a previously requested irq.
  246. *
  247. * @irq: A irq struct that was previously successfully requested by
  248. * irq_request/get_by_*().
  249. * Return: 0 if OK, or a negative error code.
  250. */
  251. int irq_free(struct irq *irq);
  252. /**
  253. * irq_first_device_type() - Get a particular interrupt controller
  254. *
  255. * On success this returns an activated interrupt device.
  256. *
  257. * @type: Type to find
  258. * @devp: Returns the device, if found
  259. * Return: 0 if OK, -ENODEV if not found, other -ve error if uclass failed to
  260. * probe
  261. */
  262. int irq_first_device_type(enum irq_dev_t type, struct udevice **devp);
  263. /**
  264. * irq_get_acpi() - Get the ACPI info for an irq
  265. *
  266. * This converts a irq to an ACPI structure for adding to the ACPI
  267. * tables.
  268. *
  269. * @irq: irq to convert
  270. * @acpi_irq: Output ACPI interrupt information
  271. * Return: ACPI pin number or -ve on error
  272. */
  273. int irq_get_acpi(const struct irq *irq, struct acpi_irq *acpi_irq);
  274. #endif