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
