1.\" $NetBSD: xcall.9,v 1.15 2019/10/06 17:21:28 uwe Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Doran. 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 February 1, 2018 31.Dt XCALL 9 32.Os 33.Sh NAME 34.Nm xcall , 35.Nm xc_broadcast , 36.Nm xc_unicast , 37.Nm xc_wait 38.Nd cross-call interface 39.Sh SYNOPSIS 40.In sys/xcall.h 41.Vt typedef void (*xcfunc_t)(void *, void *); 42.Ft uint64_t 43.Fn xc_broadcast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" 44.Ft uint64_t 45.Fn xc_unicast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" "struct cpu_info *ci" 46.Ft void 47.Fn xc_wait "uint64_t where" 48.Sh DESCRIPTION 49The machine-independent 50.Nm 51interface allows any CPU in the system to request that an arbitrary 52function be executed on any other CPU. 53.Pp 54Sometimes it is necessary to modify hardware state that is tied 55directly to individual CPUs 56.Po 57such as a CPU's local timer 58.Pc , 59and these updates can not be done remotely by another CPU. 60The LWP requesting the update may be unable to guarantee that it 61will be running on the CPU where the update must occur, when the 62update occurs. 63.Pp 64Additionally, it is sometimes necessary to modify per-CPU software 65state from a remote CPU. 66Where these update operations are so rare or the access to the 67per-CPU data so frequent that the cost of using locking or atomic 68operations to provide coherency is prohibitive, another way must 69be found. 70.Pp 71Cross calls help to solve these types of problem. 72However, since this facility is heavyweight, it is expected that 73it will not be used often. 74.Pp 75.Nm 76provides a mechanism for making 77.Dq "low priority" 78cross calls. 79The function to be executed runs on the remote CPU within a thread 80context, and not from a software interrupt, so it can ensure that it is 81not interrupting other code running on the CPU, and so has exclusive 82access to the CPU. 83Keep in mind that unless disabled, it may cause a kernel preemption. 84.Pp 85.Nm 86also provides a mechanism for making 87.Dq "high priority" 88cross calls. 89The function to be executed runs on the remote CPU within a 90software interrupt context, possibly interrupting other lower-priority 91code running on the CPU. 92.Sh NOTES 93Functions being called should be relatively lightweight. 94They may block on locks, but carefully and minimally, to not interfere 95with other cross calls in the system. 96.Sh FUNCTIONS 97.Bl -tag -width Fn 98.It Fn xc_broadcast "flags" "func" "arg1" "arg2" 99Call 100.Pf (* Fa func\| ) Ns Fo "" 101.Fa "arg1" 102.Fa "arg2" 103.Fc 104on all CPUs in the system. 105Return a 106.Vt uint64_t 107.Dq ticket 108to 109.Fn xc_wait 110on for the cross-call to complete. 111.Fa flags 112should be 113.Dv XC_HIGHPRI 114or 115.Dv XC_HIGHPRI_IPL\| Ns Fn "" ipl 116for a "high priority" call, and 0 for a "low priority" call. 117.Dv XC_HIGHPRI 118uses an 119.Dv IPL_SOFTSERIAL 120software interrupt while 121.Dv XC_HIGHPRI_IPL 122uses a software interrupt with an IPL specified by 123.Fa ipl . 124.Fn xc_broadcast 125should not be called from interrupt context. 126.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci" 127Like 128.Fn xc_broadcast , 129but call 130.Fa func 131on only the CPU indicated by 132.Fa ci . 133.Fn xc_unicast 134also returns a 135.Dq ticket . 136.It Fn xc_wait "where" 137Wait on the 138.Dq ticket 139returned by a prior 140.Fn xc_broadcast 141or 142.Fn xc_unicast 143for the corresponding cross-call to complete. 144.Fn xc_wait 145should be called from a thread context. 146.El 147.Sh CODE REFERENCES 148The 149.Nm 150interface is implemented within the file 151.Pa sys/kern/subr_xcall.c . 152.\" .Sh EXAMPLES 153.Sh SEE ALSO 154.Xr kpreempt 9 , 155.Xr percpu 9 , 156.Xr softint 9 157.Sh HISTORY 158The 159.Nm 160interface first appeared in 161.Nx 5.0 . 162.Sh AUTHORS 163.An Andrew Doran Aq Mt ad@NetBSD.org 164