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