[PATCH 14/14] Docs: IRQ: Add new IRQ-ipi.txt

[Qais Yousef]

The new file describes how to use the new generic IPI support API and implement
the support in the irqchip driver.

Signed-off-by: Qais Yousef <qais.yousef@xxxxxxxxxx>
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: linux-doc@xxxxxxxxxxxxxxx
---
 Documentation/IRQ-ipi.txt | 81 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 Documentation/IRQ-ipi.txt

diff --git a/Documentation/IRQ-ipi.txt b/Documentation/IRQ-ipi.txt
new file mode 100644
index 000000000000..07e5d9abdf38
--- /dev/null
+++ b/Documentation/IRQ-ipi.txt
@@ -0,0 +1,81 @@
+Generic IPI allocation and sending
+
+
+We now have a generic IPI mechanism to allocate and send IPIs which can be used
+to implement ARCH's SMP IPIs or by the driver to exchange IPIs with a coprocessor
+it's talking to.
+
+
+=====
+ API
+=====
+
+Structs:
+
+	-- struct ipi_mask --
+
+	Similar to cpumask but can handle CPUs outside NR_CPU range.
+
+Functions:
+
+	-- irq_reserve_ipi() --
+
+	Dynamically allocate an IPI from an IPI irq_domain registered by the
+	system. An IPI mask must be passed specifying the destination CPUs this
+	IPI will target.
+
+	On success it will return a virq that can be used to send an IPI to one
+	subset of CPUs in the passed IPI mask.
+
+	This function is not exported. Ideally the IPI should be requested from
+	device tree which will use this function indirectly.
+
+	-- irq_send_ipi() --
+
+	To be used by drivers to send an IPI. It takesthe  virq that was
+	returned by irq_reserve_ipi() and an IPI mask containing a subset of the
+	IPI mask used to allocate the IPI.
+
+	This function is exported to allow drivers to use it.
+
+	-- __irq_desc_send_ipi() --
+
+	To be used by ARCH code to send SMP IPIs. It takes a desc instead of virq
+	to save having to do desc lookup on this common case.
+
+	This function is not exported as it's meant for ARCH code use only.
+
+
+=========================================
+ Adding support into your irqchip driver
+=========================================
+
+For this new feature to be used, you need to have an irqchip driver that provides
+an IPI domain.
+
+The IPI domain must be a Hierarchy Domain with IRQ_DOMAIN_FLAG_IPI set and
+domain bust set to DOMAIN_BUS_IPI to allow the system to identify it.
+
+structs:
+
+	-- struct ipi_mapping --
+
+	This struct is provided to aid in creating a CPU to HWIRQ mapping when
+	allocating an IPI and perform the lookup when sending one.
+
+functions:
+
+	-- irq_domain_ops->alloc() --
+
+	This function should be used to implement the hardware specific mechanism
+	to reserve an IPI.
+
+	The generic layer will allocate a virq for each CPU in the IPI mask
+	passed in the call to irq_reserve_ipi() which the driver can freely
+	choose to use or ignore depends if it needs to have a one to one mapping
+	between virq and hwirq or one virq is enough to identify multiple hwirqs.
+
+	-- irqchip->irq_send_ipi() --
+
+	The generic layer will call this irqchip function after doing some sanity
+	checking for the driver to perform the actual IPI kick.
-- 
2.1.0

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/