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

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

details:   https://anonhg.NetBSD.org/src/rev/7be5e1f080c8
branches:  trunk
changeset: 744438:7be5e1f080c8
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Feb 01 13:35:11 2020 +0000

description:
Redocument xc_barrier.

Be more clearer, and more correcter, about what it does.

diffstat:

 share/man/man9/xcall.9 |  38 ++++++++++++++++++++++++++------------
 1 files changed, 26 insertions(+), 12 deletions(-)

diffs (70 lines):

diff -r ffa401eeafca -r 7be5e1f080c8 share/man/man9/xcall.9
--- a/share/man/man9/xcall.9    Sat Feb 01 13:26:43 2020 +0000
+++ b/share/man/man9/xcall.9    Sat Feb 01 13:35:11 2020 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: xcall.9,v 1.16 2019/11/30 02:22:23 riastradh Exp $
+.\"     $NetBSD: xcall.9,v 1.17 2020/02/01 13:35:11 riastradh Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 29, 2019
+.Dd February 1, 2020
 .Dt XCALL 9
 .Os
 .Sh NAME
@@ -97,7 +97,7 @@
 They may block on locks, but carefully and minimally, to not interfere
 with other cross calls in the system.
 .Sh FUNCTIONS
-.Bl -tag -width Fn
+.Bl -tag -width abcd
 .It Fn xc_broadcast "flags" "func" "arg1" "arg2"
 Call
 .Pf (* Fa func\| ) Ns Fo ""
@@ -147,19 +147,33 @@
 .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 ,
+Issue a broadcast cross-call that does nothing,
 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
+.Pp
 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.
+.Pp
+This additionally waits for all higher-priority activity on the CPU to
+complete, according to
+.Fa flags :
+.Bl -dash -compact
+.It
+.Fo xc_barrier
+.Li 0
+.Fc
+waits for any pending
+.Xr kpreempt_disable 9
+sections or activity at interrupt priority level above
+.Dv IPL_NONE
+to finish on all CPUs.
+.It
+.Fo xc_barrier
+.Dv XC_HIGHPRI_IPL\| Ns Fn "" ipl
+.Fc
+waits for any pending activity at the software interrupt priority level
+.Fa ipl
+or higher to finish on all CPUs.
 .El
 .Pp
 .Fn xc_barrier