[src/trunk]: src/share/man/man9 Per rmind@'s suggestion, describe the cross-c...

[dyoung <dyoung%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/51f1dc630157
branches:  trunk
changeset: 751041:51f1dc630157
user:      dyoung <dyoung%NetBSD.org@localhost>
date:      Fri Jan 22 23:27:01 2010 +0000

description:
Per rmind@'s suggestion, describe the cross-call implementation in more
detail (by pulling more text from sys/kern/subr_xcall.c).

Mention that a cross-call can be preempted, and xref kpreempt(9).

diffstat:

 share/man/man9/xc.9 |  28 +++++++++++++++++++++++++---
 1 files changed, 25 insertions(+), 3 deletions(-)

diffs (56 lines):

diff -r c0d3d328c7f3 -r 51f1dc630157 share/man/man9/xc.9
--- a/share/man/man9/xc.9       Fri Jan 22 23:14:28 2010 +0000
+++ b/share/man/man9/xc.9       Fri Jan 22 23:27:01 2010 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: xc.9,v 1.1 2010/01/22 20:43:48 dyoung Exp $
+.\"     $NetBSD: xc.9,v 1.2 2010/01/22 23:27:01 dyoung Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -72,6 +72,22 @@
 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"
@@ -93,7 +109,12 @@
 Always call
 .Fn xc_broadcast
 from thread context.
-Treat this as an expensive operation.
+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 ,
@@ -129,7 +150,8 @@
 .Pa sys/kern/subr_xcall.c .
 .\" .Sh EXAMPLES
 .Sh SEE ALSO
-.Xr percpu 9
+.Xr percpu 9 ,
+.Xr kpreempt 9
 .Sh HISTORY
 The
 .Nm