1.\" $NetBSD: xcall.9,v 1.12 2018/02/01 03:15:28 ozaki-r 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 compact 98.It Fn xc_broadcast "flags" "func" "arg1" "arg2" 99Call 100.Fo "(*func)" 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.Fo XC_HIGHPRI_IPL 116.Fa ipl 117.Fc 118for a "high priority" call, and 0 for a "low priority" call. 119.Dv XC_HIGHPRI 120uses an 121.Dv IPL_SOFTSERIAL 122software interrupt while 123.Fn XC_HIGHPRI_IPL 124uses a software interrupt with an IPL specified by 125.Fa ipl . 126.Fn xc_broadcast 127should not be called from interrupt context. 128.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci" 129Like 130.Fn xc_broadcast , 131but call 132.Fn "(*func)" 133on only the CPU indicated by 134.Fa ci . 135.Fn xc_unicast 136also returns a 137.Dq ticket . 138.It Fn xc_wait "where" 139Wait on the 140.Dq ticket 141returned by a prior 142.Fn xc_broadcast 143or 144.Fn xc_unicast 145for the corresponding cross-call to complete. 146.Fn xc_wait 147should be called from a thread context. 148.El 149.Sh CODE REFERENCES 150The 151.Nm 152interface is implemented within the file 153.Pa sys/kern/subr_xcall.c . 154.\" .Sh EXAMPLES 155.Sh SEE ALSO 156.Xr kpreempt 9 , 157.Xr percpu 9 , 158.Xr softint 9 159.Sh HISTORY 160The 161.Nm 162interface first appeared in 163.Nx 5.0 . 164.Sh AUTHORS 165.An Andrew Doran Aq Mt ad@NetBSD.org 166