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

Qais Yousef
2015-11-03T11:13:54Z

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@imgtec.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
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