1.\" $NetBSD: xcall.9,v 1.6 2010/05/16 05:18:35 jruoho 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 May 16, 2010 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.Sh NOTES 85Functions being called should be relatively lightweight. 86They may block on locks, but carefully and minimally, to not interfere 87with other cross calls in the system. 88.Sh FUNCTIONS 89.Bl -tag -width compact 90.It Fn xc_broadcast "flags" "func" "arg1" "arg2" 91Call 92.Fo "(*func)" 93.Fa "arg1" 94.Fa "arg2" 95.Fc 96on all CPUs in the system. 97Return a 98.Vt uint64_t 99.Dq ticket 100to 101.Fn xc_wait 102on for the cross-call to complete. 103.Fa flags 104should be 0. 105.Fn xc_broadcast 106should not be called from interrupt context. 107.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci" 108Like 109.Fn xc_broadcast , 110but call 111.Fn "(*func)" 112on only the CPU indicated by 113.Fa ci . 114.Fn xc_unicast 115also returns a 116.Dq ticket . 117.It Fn xc_wait "where" 118Wait on the 119.Dq ticket 120returned by a prior 121.Fn xc_broadcast 122or 123.Fn xc_unicast 124for the corresponding cross-call to complete. 125.El 126.Sh CODE REFERENCES 127This section describes places within the 128.Nx 129source tree where actual code implementing the 130.Nm 131interface 132can be found. 133All pathnames are relative to 134.Pa /usr/src . 135.Pp 136The 137.Nm 138interface is implemented within the file 139.Pa sys/kern/subr_xcall.c . 140.\" .Sh EXAMPLES 141.Sh SEE ALSO 142.Xr kpreempt 9 , 143.Xr percpu 9 144.Sh HISTORY 145The 146.Nm 147interface first appeared in 148.Nx 5.0 . 149.Sh AUTHORS 150.An Andrew Doran Aq ad@NetBSD.org 151