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

From: Qais Yousef <qais.yousef@imgtec.com>
To: <linux-kernel@vger.kernel.org>
Cc: <tglx@linutronix.de>, <jason@lakedaemon.net>,
	<marc.zyngier@arm.com>, <jiang.liu@linux.intel.com>,
	<ralf@linux-mips.org>, <linux-mips@linux-mips.org>,
	Qais Yousef <qais.yousef@imgtec.com>,
	"Jonathan Corbet" <corbet@lwn.net>, <linux-doc@vger.kernel.org>
Subject: [PATCH 14/14] Docs: IRQ: Add new IRQ-ipi.txt
Date: Tue, 3 Nov 2015 11:13:01 +0000	[thread overview]
Message-ID: <1446549181-31788-15-git-send-email-qais.yousef@imgtec.com> (raw)
In-Reply-To: <1446549181-31788-1-git-send-email-qais.yousef@imgtec.com>

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

