[src/trunk]: src/share/man/man9 Document xc_barrier.

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

details:   https://anonhg.NetBSD.org/src/rev/961f18a2ca98
branches:  trunk
changeset: 465611:961f18a2ca98
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Nov 30 02:22:23 2019 +0000

description:
Document xc_barrier.

diffstat:

 share/man/man9/xcall.9 |  33 ++++++++++++++++++++++++++++++---
 1 files changed, 30 insertions(+), 3 deletions(-)

diffs (74 lines):

diff -r 32b2e9c276b7 -r 961f18a2ca98 share/man/man9/xcall.9
--- a/share/man/man9/xcall.9    Sat Nov 30 00:38:51 2019 +0000
+++ b/share/man/man9/xcall.9    Sat Nov 30 02:22:23 2019 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: xcall.9,v 1.15 2019/10/06 17:21:28 uwe Exp $
+.\"     $NetBSD: xcall.9,v 1.16 2019/11/30 02:22:23 riastradh Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,14 +27,15 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd February 1, 2018
+.Dd November 29, 2019
 .Dt XCALL 9
 .Os
 .Sh NAME
 .Nm xcall ,
 .Nm xc_broadcast ,
 .Nm xc_unicast ,
-.Nm xc_wait
+.Nm xc_wait ,
+.Nm xc_barrier
 .Nd cross-call interface
 .Sh SYNOPSIS
 .In sys/xcall.h
@@ -45,6 +46,8 @@
 .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"
+.Ft void
+.Fn xc_barrier "u_int flags"
 .Sh DESCRIPTION
 The machine-independent
 .Nm
@@ -143,6 +146,29 @@
 for the corresponding cross-call to complete.
 .Fn xc_wait
 should be called from a thread context.
+.It Fn xc_barrier "flags"
+Issue a broadcast cross-call that does nothing, using
+.Fa flags ,
+and wait for it to complete.
+This has two effects:
+.Bl -dash -compact
+.It
+This waits for the interrupt priority level to transition to
+.Dv IPL_NONE
+at least once on all CPUs.
+.It
+This functions like a memory barrier that forces all prior operations
+in program order to globally happen before all subsequent operations in
+program order, as witnessed by every CPU.
+.El
+.Pp
+.Fn xc_barrier
+is much more expensive than
+.Xr membar_ops 3 ,
+so it should be used sparingly, only to publish information
+infrequently \(em for example, during module load and unload \(em when
+the cost of a memory barrier on the consumer side would be
+prohibitive.
 .El
 .Sh CODE REFERENCES
 The
@@ -151,6 +177,7 @@
 .Pa sys/kern/subr_xcall.c .
 .\" .Sh EXAMPLES
 .Sh SEE ALSO
+.Xr membar_ops 3 ,
 .Xr kpreempt 9 ,
 .Xr percpu 9 ,
 .Xr softint 9