dm: irq: Add support for requesting interrupts

At present driver model supports the IRQ uclass but there is no way to
request a particular interrupt for a driver.

Add a mechanism, similar to clock and reset, to read the interrupts
required by a device from the device tree and to request those interrupts.

U-Boot itself does not have interrupt-driven handlers, so just provide a
means to read and clear an interrupt. This can be useful to handle
peripherals which must use an interrupt to determine when data is
available, for example.

Bring over the basic binding file as well, from Linux v5.4. Note that the
older binding is not supported in U-Boot; the newer 'special form' must be
used.

Add a simple test of the new functionality.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Bin Meng <bmeng.cn@gmail.com>

1 files changed, 115 insertions, 0 deletions

diff --git a/include/irq.h b/include/irq.h
index 8b4e2ecfc0..b71afe9bee 100644
--- a/include/irq.h
+++ b/include/irq.h
@@ -20,7 +20,20 @@ enum irq_dev_t {
 };
 
 /**
+ * struct irq - A single irq line handled by an interrupt controller
+ *
+ * @dev: IRQ device that handles this irq
+ * @id: ID to identify this irq with the device
+ */
+struct irq {
+	struct udevice *dev;
+	ulong id;
+};
+
+/**
  * struct irq_ops - Operations for the IRQ
+ *
+ * Each IRQ device can handle mulitple IRQ lines
  */
 struct irq_ops {
 	/**
@@ -57,6 +70,55 @@ struct irq_ops {
 	 * @return 0
 	 */
 	int (*restore_polarities)(struct udevice *dev);
+
+	/**
+	 * read_and_clear() - get the value of an interrupt and clear it
+	 *
+	 * Clears the interrupt if pending
+	 *
+	 * @irq: IRQ line
+	 * @return 0 if interrupt is not pending, 1 if it was (and so has been
+	 *	cleared), -ve on error
+	 */
+	int (*read_and_clear)(struct irq *irq);
+	/**
+	 * of_xlate - Translate a client's device-tree (OF) irq specifier.
+	 *
+	 * The irq core calls this function as the first step in implementing
+	 * a client's irq_get_by_*() call.
+	 *
+	 * If this function pointer is set to NULL, the irq core will use a
+	 * default implementation, which assumes #interrupt-cells = <1>, and
+	 * that the DT cell contains a simple integer irq ID.
+	 *
+	 * @irq:	The irq struct to hold the translation result.
+	 * @args:	The irq specifier values from device tree.
+	 * @return 0 if OK, or a negative error code.
+	 */
+	int (*of_xlate)(struct irq *irq, struct ofnode_phandle_args *args);
+	/**
+	 * request - Request a translated irq.
+	 *
+	 * The irq core calls this function as the second step in
+	 * implementing a client's irq_get_by_*() call, following a successful
+	 * xxx_xlate() call, or as the only step in implementing a client's
+	 * irq_request() call.
+	 *
+	 * @irq:	The irq struct to request; this has been fille in by
+	 *		a previoux xxx_xlate() function call, or by the caller
+	 *		of irq_request().
+	 * @return 0 if OK, or a negative error code.
+	 */
+	int (*request)(struct irq *irq);
+	/**
+	 * free - Free a previously requested irq.
+	 *
+	 * This is the implementation of the client irq_free() API.
+	 *
+	 * @irq:	The irq to free.
+	 * @return 0 if OK, or a negative error code.
+	 */
+	int (*free)(struct irq *irq);
 };
 
 #define irq_get_ops(dev)	((struct irq_ops *)(dev)->driver->ops)
@@ -97,6 +159,59 @@ int irq_snapshot_polarities(struct udevice *dev);
 int irq_restore_polarities(struct udevice *dev);
 
 /**
+ * read_and_clear() - get the value of an interrupt and clear it
+ *
+ * Clears the interrupt if pending
+ *
+ * @dev: IRQ device
+ * @return 0 if interrupt is not pending, 1 if it was (and so has been
+ *	cleared), -ve on error
+ */
+int irq_read_and_clear(struct irq *irq);
+
+/**
+ * irq_get_by_index - Get/request an irq by integer index.
+ *
+ * This looks up and requests an irq. The index is relative to the client
+ * device; each device is assumed to have n irqs associated with it somehow,
+ * and this function finds and requests one of them. The mapping of client
+ * device irq indices to provider irqs may be via device-tree
+ * properties, board-provided mapping tables, or some other mechanism.
+ *
+ * @dev:	The client device.
+ * @index:	The index of the irq to request, within the client's list of
+ *		irqs.
+ * @irq:	A pointer to a irq struct to initialise.
+ * @return 0 if OK, or a negative error code.
+ */
+int irq_get_by_index(struct udevice *dev, int index, struct irq *irq);
+
+/**
+ * irq_request - Request a irq by provider-specific ID.
+ *
+ * This requests a irq using a provider-specific ID. Generally, this function
+ * should not be used, since irq_get_by_index/name() provide an interface that
+ * better separates clients from intimate knowledge of irq providers.
+ * However, this function may be useful in core SoC-specific code.
+ *
+ * @dev:	The irq provider device.
+ * @irq:	A pointer to a irq struct to initialise. The caller must
+ *		have already initialised any field in this struct which the
+ *		irq provider uses to identify the irq.
+ * @return 0 if OK, or a negative error code.
+ */
+int irq_request(struct udevice *dev, struct irq *irq);
+
+/**
+ * irq_free - Free a previously requested irq.
+ *
+ * @irq:	A irq struct that was previously successfully requested by
+ *		irq_request/get_by_*().
+ * @return 0 if OK, or a negative error code.
+ */
+int irq_free(struct irq *irq);
+
+/**
  * irq_first_device_type() - Get a particular interrupt controller
  *
  * On success this returns an activated interrupt device.