Module Name: src
Committed By: riastradh
Date: Sat Nov 30 02:22:23 UTC 2019
Modified Files:
src/share/man/man9: xcall.9
Log Message:
Document xc_barrier.
To generate a diff of this commit:
cvs rdiff -u -r1.15 -r1.16 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/share/man/man9/xcall.9
diff -u src/share/man/man9/xcall.9:1.15 src/share/man/man9/xcall.9:1.16
--- src/share/man/man9/xcall.9:1.15 Sun Oct 6 17:21:28 2019
+++ src/share/man/man9/xcall.9 Sat Nov 30 02:22:23 2019
@@ -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 @@ or
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 @@ interface is implemented within the file
.Pa sys/kern/subr_xcall.c .
.\" .Sh EXAMPLES
.Sh SEE ALSO
+.Xr membar_ops 3 ,
.Xr kpreempt 9 ,
.Xr percpu 9 ,
.Xr softint 9
