1.\" $NetBSD: ipi.9,v 1.2 2014/05/25 15:51:26 wiz Exp $ 2.\" 3.\" Copyright (c) 2014 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Mindaugas Rasiukevicius. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd May 25, 2014 31.Dt IPI 9 32.Os 33.Sh NAME 34.Nm ipi 35.Nd MI IPI interface 36.Sh SYNOPSIS 37.In sys/ipi.h 38.Vt typedef void (*ipi_func_t)(void *); 39.\" ----- 40.Ft u_int 41.Fn ipi_register "ipi_func_t func" "void *arg" 42.Ft void 43.Fn ipi_unregister "u_int ipi_id" 44.Ft void 45.Fn ipi_trigger "u_int ipi_id" "struct cpu_info *ci" 46.\" ----- 47.Ft void 48.Fn ipi_unicast "ipi_msg_t *msg" "struct cpu_info *ci" 49.Ft void 50.Fn ipi_multicast "ipi_msg_t *msg" "const kcpuset_t *target" 51.Ft void 52.Fn ipi_broadcast "ipi_msg_t *msg" 53.Ft void 54.Fn ipi_wait "ipi_msg_t *msg" 55.\" ----- 56.Sh DESCRIPTION 57The machine-independent 58.Nm 59interface provides capability to send inter-processor interrupts (IPIs) 60amongst CPUs. 61The interface has two mechanisms: asynchronous IPI to invoke functions 62with a constant argument and synchronous IPIs with the cross-call support. 63.Pp 64Other synchronization interfaces are built using the MI IPI interface. 65For a general purpose inter-processor cross-calls or remote 66interrupts, use the 67.Xr xcall 9 68or 69.Xr softint 9 70interfaces. 71.Pp 72The primary use cases of the MI IPIs include the following: 73.Bl -hyphen -compact 74.It 75provide a facility for the 76.Xr softint 9 77subsystem to schedule software interrupts on remote CPUs 78.It 79provide a facility for the 80.Xr xcall 9 81subsystem 82.It 83abstract IPI handling and facilitate machine-dependent code 84.El 85.\" ----- 86.Ss Asynchronous IPI interface 87This interface allows dynamic registration of IPI handlers with a constant 88argument and asynchronous triggering of interrupts. 89.Bl -tag -width compact 90.It Fn ipi_register "func" "arg" 91Register an IPI handler 92.Fa func 93with an arbitrary argument 94.Fa arg . 95Returns a non-zero IPI identifier on success and zero on failure. 96.It Fn ipi_unregister "ipi_id" 97Unregister the IPI handler identified by the 98.Fa ipi_id . 99.It Fn ipi_trigger "ipi_id" "ci" 100Trigger an IPI identified by 101.Fa ipi_id 102on a remote CPU specified by 103.Fa ci . 104This function must be called with the kernel preemption disabled and 105the target CPU must be remote. 106.El 107.\" ----- 108.Ss Synchronous IPI interface 109This interface provides capability to perform cross-calls, i.e. invoke 110an arbitrary function on a remote CPU. 111The invocations are performed synchronously and the caller must wait 112for completion. 113The cross-call is described by an IPI "message". 114The caller has to fill in an 115.Vt ipi_msg_t 116structure which has the following public members: 117.Bd -literal 118 ipi_func_t func; 119 void arg; 120.Ed 121.Pp 122The 123.Ar func 124member specifies a function to invoke and 125.Ar arg 126is the argument to be passed to the function. 127.Pp 128.Bl -tag -width compact 129.It Fn ipi_unicast "msg" "ci" 130Send an IPI to a remote CPU specified by 131.Fa ci . 132.It Fn ipi_multicast "msg" "target" 133Send IPIs to a CPU set specified by 134.Fa target . 135.It Fn ipi_broadcast "msg" 136Send IPIs to all CPUs. 137.It Fn ipi_wait "msg" 138Wait until all IPIs complete. 139.El 140.Pp 141All described functions, except 142.Fn ipi_wait , 143must be called with the kernel preemption disabled. 144All synchronous IPI invocations must be completed (wait for them with the 145.Fn ipi_wait 146function) before the IPI message structure can be destroyed or new 147cross-call requests can be performed. 148.\" ----- 149.Sh NOTES 150Functions being called must be lightweight. 151They run at 152.Dv IPL_HIGH 153and should generally not use any other synchronization interfaces 154such as 155.Xr mutex 9 . 156If spin-locks are used, they must be used carefully and have no contention. 157.\" ----- 158.Sh CODE REFERENCES 159The 160.Nm 161interface is implemented within the file 162.Pa sys/kern/subr_ipi.c . 163.\" ----- 164.Sh SEE ALSO 165.Xr kcpuset 9 , 166.Xr kpreempt 9 , 167.Xr softint 9 , 168.Xr spl 9 , 169.Xr xcall 9 170.Sh HISTORY 171The 172.Nm 173interface first appeared in 174.Nx 7.0 . 175.Sh AUTHORS 176.An Mindaugas Rasiukevicius Aq Mt rmind@NetBSD.org 177