Sun Oct 6 17:21:28 2019 UTC ()
Use .Bl -tag -width Fn.  There's no such thing as -width compact
or, rather, there is, but the width specified is that of the word
"compact".


(uwe)
diff -r1.14 -r1.15 src/share/man/man9/xcall.9
cvs diff -r1.14 -r1.15 src/share/man/man9/xcall.9 (switch to unified diff)

--- src/share/man/man9/xcall.9 2019/10/06 17:14:18 1.14
+++ src/share/man/man9/xcall.9 2019/10/06 17:21:28 1.15
@@ -1,163 +1,163 @@ @@ -1,163 +1,163 @@
1.\" $NetBSD: xcall.9,v 1.14 2019/10/06 17:14:18 uwe Exp $ 1.\" $NetBSD: xcall.9,v 1.15 2019/10/06 17:21:28 uwe Exp $
2.\" 2.\"
3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Doran. 7.\" by Andrew Doran.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the 15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution. 16.\" documentation and/or other materials provided with the distribution.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd February 1, 2018 30.Dd February 1, 2018
31.Dt XCALL 9 31.Dt XCALL 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm xcall , 34.Nm xcall ,
35.Nm xc_broadcast , 35.Nm xc_broadcast ,
36.Nm xc_unicast , 36.Nm xc_unicast ,
37.Nm xc_wait 37.Nm xc_wait
38.Nd cross-call interface 38.Nd cross-call interface
39.Sh SYNOPSIS 39.Sh SYNOPSIS
40.In sys/xcall.h 40.In sys/xcall.h
41.Vt typedef void (*xcfunc_t)(void *, void *); 41.Vt typedef void (*xcfunc_t)(void *, void *);
42.Ft uint64_t 42.Ft uint64_t
43.Fn xc_broadcast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" 43.Fn xc_broadcast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2"
44.Ft uint64_t 44.Ft uint64_t
45.Fn xc_unicast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" "struct cpu_info *ci" 45.Fn xc_unicast "u_int flags" "xcfunc_t func" "void *arg1" "void *arg2" "struct cpu_info *ci"
46.Ft void 46.Ft void
47.Fn xc_wait "uint64_t where" 47.Fn xc_wait "uint64_t where"
48.Sh DESCRIPTION 48.Sh DESCRIPTION
49The machine-independent 49The machine-independent
50.Nm 50.Nm
51interface allows any CPU in the system to request that an arbitrary 51interface allows any CPU in the system to request that an arbitrary
52function be executed on any other CPU. 52function be executed on any other CPU.
53.Pp 53.Pp
54Sometimes it is necessary to modify hardware state that is tied 54Sometimes it is necessary to modify hardware state that is tied
55directly to individual CPUs 55directly to individual CPUs
56.Po 56.Po
57such as a CPU's local timer 57such as a CPU's local timer
58.Pc , 58.Pc ,
59and these updates can not be done remotely by another CPU. 59and these updates can not be done remotely by another CPU.
60The LWP requesting the update may be unable to guarantee that it 60The LWP requesting the update may be unable to guarantee that it
61will be running on the CPU where the update must occur, when the 61will be running on the CPU where the update must occur, when the
62update occurs. 62update occurs.
63.Pp 63.Pp
64Additionally, it is sometimes necessary to modify per-CPU software 64Additionally, it is sometimes necessary to modify per-CPU software
65state from a remote CPU. 65state from a remote CPU.
66Where these update operations are so rare or the access to the 66Where these update operations are so rare or the access to the
67per-CPU data so frequent that the cost of using locking or atomic 67per-CPU data so frequent that the cost of using locking or atomic
68operations to provide coherency is prohibitive, another way must 68operations to provide coherency is prohibitive, another way must
69be found. 69be found.
70.Pp 70.Pp
71Cross calls help to solve these types of problem. 71Cross calls help to solve these types of problem.
72However, since this facility is heavyweight, it is expected that 72However, since this facility is heavyweight, it is expected that
73it will not be used often. 73it will not be used often.
74.Pp 74.Pp
75.Nm 75.Nm
76provides a mechanism for making 76provides a mechanism for making
77.Dq "low priority" 77.Dq "low priority"
78cross calls. 78cross calls.
79The function to be executed runs on the remote CPU within a thread 79The function to be executed runs on the remote CPU within a thread
80context, and not from a software interrupt, so it can ensure that it is 80context, and not from a software interrupt, so it can ensure that it is
81not interrupting other code running on the CPU, and so has exclusive 81not interrupting other code running on the CPU, and so has exclusive
82access to the CPU. 82access to the CPU.
83Keep in mind that unless disabled, it may cause a kernel preemption. 83Keep in mind that unless disabled, it may cause a kernel preemption.
84.Pp 84.Pp
85.Nm 85.Nm
86also provides a mechanism for making 86also provides a mechanism for making
87.Dq "high priority" 87.Dq "high priority"
88cross calls. 88cross calls.
89The function to be executed runs on the remote CPU within a 89The function to be executed runs on the remote CPU within a
90software interrupt context, possibly interrupting other lower-priority 90software interrupt context, possibly interrupting other lower-priority
91code running on the CPU. 91code running on the CPU.
92.Sh NOTES 92.Sh NOTES
93Functions being called should be relatively lightweight. 93Functions being called should be relatively lightweight.
94They may block on locks, but carefully and minimally, to not interfere 94They may block on locks, but carefully and minimally, to not interfere
95with other cross calls in the system. 95with other cross calls in the system.
96.Sh FUNCTIONS 96.Sh FUNCTIONS
97.Bl -tag -width compact 97.Bl -tag -width Fn
98.It Fn xc_broadcast "flags" "func" "arg1" "arg2" 98.It Fn xc_broadcast "flags" "func" "arg1" "arg2"
99Call 99Call
100.Pf (* Fa func\| ) Ns Fo "" 100.Pf (* Fa func\| ) Ns Fo ""
101.Fa "arg1" 101.Fa "arg1"
102.Fa "arg2" 102.Fa "arg2"
103.Fc 103.Fc
104on all CPUs in the system. 104on all CPUs in the system.
105Return a 105Return a
106.Vt uint64_t 106.Vt uint64_t
107.Dq ticket 107.Dq ticket
108to 108to
109.Fn xc_wait 109.Fn xc_wait
110on for the cross-call to complete. 110on for the cross-call to complete.
111.Fa flags 111.Fa flags
112should be 112should be
113.Dv XC_HIGHPRI 113.Dv XC_HIGHPRI
114or 114or
115.Dv XC_HIGHPRI_IPL\| Ns Fn "" ipl 115.Dv XC_HIGHPRI_IPL\| Ns Fn "" ipl
116for a "high priority" call, and 0 for a "low priority" call. 116for a "high priority" call, and 0 for a "low priority" call.
117.Dv XC_HIGHPRI 117.Dv XC_HIGHPRI
118uses an 118uses an
119.Dv IPL_SOFTSERIAL 119.Dv IPL_SOFTSERIAL
120software interrupt while 120software interrupt while
121.Dv XC_HIGHPRI_IPL 121.Dv XC_HIGHPRI_IPL
122uses a software interrupt with an IPL specified by 122uses a software interrupt with an IPL specified by
123.Fa ipl . 123.Fa ipl .
124.Fn xc_broadcast 124.Fn xc_broadcast
125should not be called from interrupt context. 125should not be called from interrupt context.
126.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci" 126.It Fn xc_unicast "flags" "func" "arg1" "arg2" "ci"
127Like 127Like
128.Fn xc_broadcast , 128.Fn xc_broadcast ,
129but call 129but call
130.Fa func 130.Fa func
131on only the CPU indicated by 131on only the CPU indicated by
132.Fa ci . 132.Fa ci .
133.Fn xc_unicast 133.Fn xc_unicast
134also returns a 134also returns a
135.Dq ticket . 135.Dq ticket .
136.It Fn xc_wait "where" 136.It Fn xc_wait "where"
137Wait on the 137Wait on the
138.Dq ticket 138.Dq ticket
139returned by a prior 139returned by a prior
140.Fn xc_broadcast 140.Fn xc_broadcast
141or 141or
142.Fn xc_unicast 142.Fn xc_unicast
143for the corresponding cross-call to complete. 143for the corresponding cross-call to complete.
144.Fn xc_wait 144.Fn xc_wait
145should be called from a thread context. 145should be called from a thread context.
146.El 146.El
147.Sh CODE REFERENCES 147.Sh CODE REFERENCES
148The 148The
149.Nm 149.Nm
150interface is implemented within the file 150interface is implemented within the file
151.Pa sys/kern/subr_xcall.c . 151.Pa sys/kern/subr_xcall.c .
152.\" .Sh EXAMPLES 152.\" .Sh EXAMPLES
153.Sh SEE ALSO 153.Sh SEE ALSO
154.Xr kpreempt 9 , 154.Xr kpreempt 9 ,
155.Xr percpu 9 , 155.Xr percpu 9 ,
156.Xr softint 9 156.Xr softint 9
157.Sh HISTORY 157.Sh HISTORY
158The 158The
159.Nm 159.Nm
160interface first appeared in 160interface first appeared in
161.Nx 5.0 . 161.Nx 5.0 .
162.Sh AUTHORS 162.Sh AUTHORS
163.An Andrew Doran Aq Mt ad@NetBSD.org 163.An Andrew Doran Aq Mt ad@NetBSD.org