1.\" $NetBSD: xcall.9,v 1.10 2013/11/26 20:48:25 rmind 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 November 26, 2013 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 90.Dv IPL_SOFTSERIAL 91software interrupt context, possibly interrupting other lower-priority 92code running on the CPU. 93.Sh NOTES 94Functions being called should be relatively lightweight. 95They may block on locks, but carefully and minimally, to not interfere 96with other cross calls in the system. 97.Sh FUNCTIONS 98.Bl -tag -width compact 99.It Fn xc_broadcast "flags" "func" "arg1" "arg2" 100Call 101.Fo "(*func)" 102.Fa "arg1" 103.Fa "arg2" 104.Fc 105on all CPUs in the system. 106Return a 107.Vt uint64_t 108.Dq ticket 109to 110.Fn xc_wait 111on for the cross-call to complete. 112.Fa flags 113should be 114.Dv XC_HIGHPRI 115for a "high priority" call, and 0 for a "low priority" call. 116.Fn xc_broadcast 117should not be called from interrupt context. 118.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci" 119Like 120.Fn xc_broadcast , 121but call 122.Fn "(*func)" 123on only the CPU indicated by 124.Fa ci . 125.Fn xc_unicast 126also returns a 127.Dq ticket . 128.It Fn xc_wait "where" 129Wait on the 130.Dq ticket 131returned by a prior 132.Fn xc_broadcast 133or 134.Fn xc_unicast 135for the corresponding cross-call to complete. 136.Fn xc_wait 137should be called from a thread context. 138.El 139.Sh CODE REFERENCES 140The 141.Nm 142interface is implemented within the file 143.Pa sys/kern/subr_xcall.c . 144.\" .Sh EXAMPLES 145.Sh SEE ALSO 146.Xr kpreempt 9 , 147.Xr percpu 9 148.Sh HISTORY 149The 150.Nm 151interface first appeared in 152.Nx 5.0 . 153.Sh AUTHORS 154.An Andrew Doran Aq Mt ad@NetBSD.org 155