Module Name: src
Committed By: rmind
Date: Sat Jan 23 00:03:38 UTC 2010
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: xcall.9
Removed Files:
src/share/man/man9: xc.9
Log Message:
Rename xc(9) to xcall(9). OK dyo...@.
To generate a diff of this commit:
cvs rdiff -u -r1.1369 -r1.1370 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.307 -r1.308 src/share/man/man9/Makefile
cvs rdiff -u -r1.2 -r0 src/share/man/man9/xc.9
cvs rdiff -u -r0 -r1.1 src/share/man/man9/xcall.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1369 src/distrib/sets/lists/comp/mi:1.1370
--- src/distrib/sets/lists/comp/mi:1.1369 Fri Jan 22 23:14:28 2010
+++ src/distrib/sets/lists/comp/mi Sat Jan 23 00:03:38 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1369 2010/01/22 23:14:28 dyoung Exp $
+# $NetBSD: mi,v 1.1370 2010/01/23 00:03:38 rmind Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -9603,8 +9603,7 @@
./usr/share/man/cat9/wsmouse.0 comp-sys-catman .cat
./usr/share/man/cat9/wsmouse_input.0 comp-sys-catman .cat
./usr/share/man/cat9/wsmousedevprint.0 comp-sys-catman .cat
-./usr/share/man/cat9/xc.0 comp-sys-catman .cat
-./usr/share/man/cat9/xc_init_cpu.0 comp-sys-catman .cat
+./usr/share/man/cat9/xcall.0 comp-sys-catman .cat
./usr/share/man/cat9/xc_broadcast.0 comp-sys-catman .cat
./usr/share/man/cat9/xc_unicast.0 comp-sys-catman .cat
./usr/share/man/cat9/xc_wait.0 comp-sys-catman .cat
@@ -15088,8 +15087,7 @@
./usr/share/man/html9/wsmouse.html comp-sys-htmlman html
./usr/share/man/html9/wsmouse_input.html comp-sys-htmlman html
./usr/share/man/html9/wsmousedevprint.html comp-sys-htmlman html
-./usr/share/man/html9/xc.html comp-sys-htmlman html
-./usr/share/man/html9/xc_init_cpu.html comp-sys-htmlman html
+./usr/share/man/html9/xcall.html comp-sys-htmlman html
./usr/share/man/html9/xc_broadcast.html comp-sys-htmlman html
./usr/share/man/html9/xc_unicast.html comp-sys-htmlman html
./usr/share/man/html9/xc_wait.html comp-sys-htmlman html
@@ -20832,8 +20830,7 @@
./usr/share/man/man9/wsmouse.9 comp-sys-man .man
./usr/share/man/man9/wsmouse_input.9 comp-sys-man .man
./usr/share/man/man9/wsmousedevprint.9 comp-sys-man .man
-./usr/share/man/man9/xc.9 comp-sys-man .man
-./usr/share/man/man9/xc_init_cpu.9 comp-sys-man .man
+./usr/share/man/man9/xcall.9 comp-sys-man .man
./usr/share/man/man9/xc_broadcast.9 comp-sys-man .man
./usr/share/man/man9/xc_unicast.9 comp-sys-man .man
./usr/share/man/man9/xc_wait.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.307 src/share/man/man9/Makefile:1.308
--- src/share/man/man9/Makefile:1.307 Fri Jan 22 23:14:29 2010
+++ src/share/man/man9/Makefile Sat Jan 23 00:03:38 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.307 2010/01/22 23:14:29 dyoung Exp $
+# $NetBSD: Makefile,v 1.308 2010/01/23 00:03:38 rmind Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -56,7 +56,7 @@
ubc.9 usbdi.9 uvm.9 vmem.9 \
wdc.9 workqueue.9 \
wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9 \
- xc.9
+ xcall.9
MAN+= boothowto.9
MLINKS+=boothowto.9 BOOT_FLAG.9
@@ -858,10 +858,9 @@
wskbd.9 wskbddevprint.9
MLINKS+=wsmouse.9 wsmouse_input.9 \
wsmouse.9 wsmousedevprint.9
-MLINKS+=xc.9 xc_init_cpu.9 \
- xc.9 xc_broadcast.9 \
- xc.9 xc_unicast.9 \
- xc.9 xc_wait.9
+MLINKS+=xcall.9 xc_broadcast.9 \
+ xcall.9 xc_unicast.9 \
+ xcall.9 xc_wait.9
SUBDIR= man9.i386 man9.sun3
Added files:
Index: src/share/man/man9/xcall.9
diff -u /dev/null src/share/man/man9/xcall.9:1.1
--- /dev/null Sat Jan 23 00:03:38 2010
+++ src/share/man/man9/xcall.9 Sat Jan 23 00:03:38 2010
@@ -0,0 +1,168 @@
+.\" $NetBSD: xcall.9,v 1.1 2010/01/23 00:03:38 rmind Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Andrew Doran.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd January 22, 2010
+.Dt XC 9
+.Os
+.Sh NAME
+.Nm XC ,
+.Nm xc_init_cpu ,
+.Nm xc_broadcast ,
+.Nm xc_unicast ,
+.Nm xc_wait
+.Nd Cross-call interface
+.Sh SYNOPSIS
+.In sys/xcall.h
+.Vt typedef void (*xcfunc_t)(void *, void *);
+.Ft void
+.Fn xc_init_cpu "struct cpu_info *ci"
+.Ft uint64_t
+.Fn xc_broadcast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2"
+.Ft uint64_t
+.Fn xc_unicast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" "struct cpu_info *ci"
+.Ft void
+.Fn xc_wait "uint64_t where"
+.Sh DESCRIPTION
+The machine-independent
+.Nm
+interface allows any CPU in the system to request that an arbitrary
+function be executed on any other CPU.
+.Pp
+Sometimes it is necessary to modify hardware state that is tied
+directly to individual CPUs
+.Po
+such as a CPU's local timer
+.Pc ,
+and these updates can not be done remotely by another CPU.
+The LWP requesting the update may be unable to guarantee that it
+will be running on the CPU where the update must occur, when the
+update occurs.
+.Pp
+Additionally, it's sometimes necessary to modify per-CPU software
+state from a remote CPU.
+Where these update operations are so rare or the access to the
+per-CPU data so frequent that the cost of using locking or atomic
+operations to provide coherency is prohibitive, another way must
+be found.
+.Pp
+Cross calls help to solve these types of problem.
+.Pp
+.Nm
+provides a slow mechanism for making
+.Dq "low priority"
+cross calls.
+The function to be executed runs on the remote CPU within a bound
+kthread.
+No queueing is provided, and the implementation uses global state.
+The function being called may block briefly on locks, but in doing
+so must be careful to not interfere with other cross calls in the
+system.
+The function is called with thread context and not from a soft
+interrupt, so it can ensure that it is not interrupting other code
+running on the CPU, and so has exclusive access to the CPU.
+Since this facility is heavyweight, it's expected that it will not
+be used often.
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn xc_init_cpu "ci"
+Initialize the cross-call subsystem.
+Called once for each CPU in the system as it is attached.
+.It Fn xc_broadcast "flags" "func" "arg1" "arg2"
+Call
+.Fo "(*func)"
+.Fa "arg1"
+.Fa "arg2"
+.Fc
+on all CPUs in the system.
+Return a
+.Vt uint64_t
+.Dq ticket
+to
+.Fn xc_wait
+on for the cross-call to complete.
+Always call
+.Fn xc_broadcast
+from thread context.
+Because
+.Fn (*func)
+is run at a low priority, it can be preempted.
+Treat
+.Fn xc_broadcast
+as an expensive operation.
+.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci"
+Like
+.Fn xc_broadcast ,
+but call
+.Fn "(*func)"
+on only the CPU indicated by
+.Fa ci .
+.Fn xc_unicast
+also returns a
+.Dq ticket .
+.It Fn xc_wait "where"
+Wait on the
+.Dq ticket
+returned by a prior
+.Fn xc_broadcast
+or
+.Fn xc_unicast
+for the corresponding cross-call to complete.
+.El
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing the
+.Nm
+interface
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The
+.Nm
+interface is implemented within the file
+.Pa sys/kern/subr_xcall.c .
+.\" .Sh EXAMPLES
+.Sh SEE ALSO
+.Xr percpu 9 ,
+.Xr kpreempt 9
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 5.0 .
+.Sh AUTHORS
+.An Andrew Doran Aq a...@netbsd.org
+.Sh CAVEATS
+Cross calls must not allocate memory, as the pagedaemon uses them
+.Po
+and memory allocation may need to wait on the pagedaemon
+.Pc .
+.\" .Sh BUGS
+.\" .Sh SECURITY CONSIDERATIONS
