From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754028AbbKCLNy (ORCPT ); Tue, 3 Nov 2015 06:13:54 -0500 Received: from mailapp01.imgtec.com ([195.59.15.196]:38609 "EHLO mailapp01.imgtec.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753902AbbKCLNq (ORCPT ); Tue, 3 Nov 2015 06:13:46 -0500 From: Qais Yousef To: CC: , , , , , , Qais Yousef , "Jonathan Corbet" , Subject: [PATCH 14/14] Docs: IRQ: Add new IRQ-ipi.txt Date: Tue, 3 Nov 2015 11:13:01 +0000 Message-ID: <1446549181-31788-15-git-send-email-qais.yousef@imgtec.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1446549181-31788-1-git-send-email-qais.yousef@imgtec.com> References: <1446549181-31788-1-git-send-email-qais.yousef@imgtec.com> MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [192.168.154.94] Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 Cc: Jonathan Corbet 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