Sun Sep 16 22:22:45 2012 UTC ()
Describe kcpuset_export_u32(9) routine.


(rmind)
diff -r1.3 -r1.4 src/share/man/man9/kcpuset.9
cvs diff -r1.3 -r1.4 src/share/man/man9/kcpuset.9 (switch to unified diff)

--- src/share/man/man9/kcpuset.9 2012/07/07 21:26:36 1.3
+++ src/share/man/man9/kcpuset.9 2012/09/16 22:22:45 1.4
@@ -1,246 +1,259 @@ @@ -1,246 +1,259 @@
1.\" $NetBSD: kcpuset.9,v 1.3 2012/07/07 21:26:36 rmind Exp $ */ 1.\" $NetBSD: kcpuset.9,v 1.4 2012/09/16 22:22:45 rmind Exp $ */
2.\" 2.\"
3.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi> 3.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi>
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 9.\"
10.\" 1. Redistributions of source code must retain the above copyright 10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer. 11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the 13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution. 14.\" documentation and/or other materials provided with the distribution.
15.\" 15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26.\" POSSIBILITY OF SUCH DAMAGE. 26.\" POSSIBILITY OF SUCH DAMAGE.
27.\" 27.\"
28.Dd July 7, 2012 28.Dd September 16, 2012
29.Dt KCPUSET 9 29.Dt KCPUSET 9
30.Os 30.Os
31.Sh NAME 31.Sh NAME
32.Nm kcpuset , 32.Nm kcpuset ,
33.Nm kcpuset_create , 33.Nm kcpuset_create ,
34.Nm kcpuset_destroy , 34.Nm kcpuset_destroy ,
35.Nm kcpuset_copy , 35.Nm kcpuset_copy ,
36.Nm kcpuset_use , 36.Nm kcpuset_use ,
37.Nm kcpuset_unuse , 37.Nm kcpuset_unuse ,
38.Nm kcpuset_copyin , 38.Nm kcpuset_copyin ,
39.Nm kcpuset_copyout , 39.Nm kcpuset_copyout ,
40.Nm kcpuset_zero , 40.Nm kcpuset_zero ,
41.Nm kcpuset_fill , 41.Nm kcpuset_fill ,
42.Nm kcpuset_set , 42.Nm kcpuset_set ,
43.Nm kcpuset_clear , 43.Nm kcpuset_clear ,
44.Nm kcpuset_isset , 44.Nm kcpuset_isset ,
45.Nm kcpuset_isotherset , 45.Nm kcpuset_isotherset ,
46.Nm kcpuset_iszero , 46.Nm kcpuset_iszero ,
47.Nm kcpuset_match , 47.Nm kcpuset_match ,
48.Nm kcpuset_merge , 48.Nm kcpuset_merge ,
49.Nm kcpuset_countset , 49.Nm kcpuset_countset ,
50.Nm kcpuset_atomic_set , 50.Nm kcpuset_atomic_set ,
51.Nm kcpuset_atomic_clear 51.Nm kcpuset_atomic_clear
 52.Nm kcpuset_export_32
52.Nd dynamic kernel CPU sets 53.Nd dynamic kernel CPU sets
53.Sh SYNOPSIS 54.Sh SYNOPSIS
54.In sys/kcpuset.h 55.In sys/kcpuset.h
55.Ft void 56.Ft void
56.Fn kcpuset_create "kcpuset_t **retkcp" "bool zero" 57.Fn kcpuset_create "kcpuset_t **retkcp" "bool zero"
57.Ft void 58.Ft void
58.Fn kcpuset_destroy "kcpuset_t *kcp" 59.Fn kcpuset_destroy "kcpuset_t *kcp"
59.Ft void 60.Ft void
60.Fn kcpuset_copy "kcpuset_t *dkcp" "kcpuset_t *skcp" 61.Fn kcpuset_copy "kcpuset_t *dkcp" "kcpuset_t *skcp"
61.Ft void 62.Ft void
62.Fn kcpuset_use "kcpuset_t *kcp" 63.Fn kcpuset_use "kcpuset_t *kcp"
63.Ft void 64.Ft void
64.Fn kcpuset_unuse "kcpuset_t *kcp" "kcpuset_t **lst" 65.Fn kcpuset_unuse "kcpuset_t *kcp" "kcpuset_t **lst"
65.Ft int 66.Ft int
66.Fn kcpuset_copyin "const cpuset_t *ucp" "kcpuset_t *kcp" "size_t len" 67.Fn kcpuset_copyin "const cpuset_t *ucp" "kcpuset_t *kcp" "size_t len"
67.Ft int 68.Ft int
68.Fn kcpuset_copyout "kcpuset_t *kcp" "cpuset_t *ucp" "size_t len" 69.Fn kcpuset_copyout "kcpuset_t *kcp" "cpuset_t *ucp" "size_t len"
69.Ft void 70.Ft void
70.Fn kcpuset_zero "kcpuset_t *kcp" 71.Fn kcpuset_zero "kcpuset_t *kcp"
71.Ft void 72.Ft void
72.Fn kcpuset_fill "kcpuset_t *kcp" 73.Fn kcpuset_fill "kcpuset_t *kcp"
73.Ft void 74.Ft void
74.Fn kcpuset_set "kcpuset_t *kcp" "cpuid_t cpu" 75.Fn kcpuset_set "kcpuset_t *kcp" "cpuid_t cpu"
75.Ft void 76.Ft void
76.Fn kcpuset_clear "kcpuset_t *kcp" "cpuid_t cpu" 77.Fn kcpuset_clear "kcpuset_t *kcp" "cpuid_t cpu"
77.Ft bool 78.Ft bool
78.Fn kcpuset_isset "kcpuset_t * kcp" "cpuid_t cpu" 79.Fn kcpuset_isset "kcpuset_t * kcp" "cpuid_t cpu"
79.Ft bool 80.Ft bool
80.Fn kcpuset_isotherset "kcpuset_t * kcp" "cpuid_t cpu" 81.Fn kcpuset_isotherset "kcpuset_t * kcp" "cpuid_t cpu"
81.Ft bool 82.Ft bool
82.Fn kcpuset_iszero "kcpuset_t *kcp" 83.Fn kcpuset_iszero "kcpuset_t *kcp"
83.Ft bool 84.Ft bool
84.Fn kcpuset_match "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" 85.Fn kcpuset_match "const kcpuset_t *kcp1" "const kcpuset_t *kcp2"
85.Ft void 86.Ft void
86.Fn kcpuset_merge "kcpuset_t *kcp1" "kcpuset_t *kcp2" 87.Fn kcpuset_merge "kcpuset_t *kcp1" "kcpuset_t *kcp2"
87.Ft int 88.Ft int
88.Fn kcpuset_countset "kcpuset_t *kcp1" 89.Fn kcpuset_countset "kcpuset_t *kcp1"
89.Ft void 90.Ft void
90.Fn kcpuset_atomic_set "kcpuset_t *kcp" "cpuid_t cpu" 91.Fn kcpuset_atomic_set "kcpuset_t *kcp" "cpuid_t cpu"
91.Ft void 92.Ft void
92.Fn kcpuset_atomic_clear "kcpuset_t *kcp" "cpuid_t cpu" 93.Fn kcpuset_atomic_clear "kcpuset_t *kcp" "cpuid_t cpu"
 94.Ft void
 95.Fn kcpuset_export_u32 "const kcpuset_t *kcp" "uint32_t *bitfield" "size_t len"
93.Sh DESCRIPTION 96.Sh DESCRIPTION
94The machine-independent 97The machine-independent
95.Nm 98.Nm
96subsystem provides support for dynamic processor sets. 99subsystem provides support for dynamic processor sets.
97Conceptually 100Conceptually
98.Nm 101.Nm
99can be understood to be the kernel equivalent of the user space 102can be understood to be the kernel equivalent of the user space
100.Xr cpuset 3 103.Xr cpuset 3
101interface. 104interface.
102.Sh FUNCTIONS 105.Sh FUNCTIONS
103.Bl -tag -width compact 106.Bl -tag -width compact
104.It Fn kcpuset_create "retkcp" "zero" 107.It Fn kcpuset_create "retkcp" "zero"
105The 108The
106.Fn kcpuset_create 109.Fn kcpuset_create
107function creates a dynamic 110function creates a dynamic
108.Tn CPU 111.Tn CPU
109set and stores the result to 112set and stores the result to
110.Fa retkcp . 113.Fa retkcp .
111If the boolean 114If the boolean
112.Fa zero 115.Fa zero
113is not false, the allocated set is also initialized to zero. 116is not false, the allocated set is also initialized to zero.
114.It Fn kcpuset_destroy "kcp" 117.It Fn kcpuset_destroy "kcp"
115Destroys the 118Destroys the
116.Tn CPU 119.Tn CPU
117set 120set
118.Fa kcp 121.Fa kcp
119and schedules any linked CPU sets for deferred destruction. 122and schedules any linked CPU sets for deferred destruction.
120.It Fn kcpuset_copy "dkcp" "skcp" 123.It Fn kcpuset_copy "dkcp" "skcp"
121Copies the 124Copies the
122.Tn CPU 125.Tn CPU
123set pointed by 126set pointed by
124.Fa skcp 127.Fa skcp
125to 128to
126.Fa dkcp . 129.Fa dkcp .
127.It Fn kcpuset_use "kcp" 130.It Fn kcpuset_use "kcp"
128Marks 131Marks
129.Fa kcp 132.Fa kcp
130as being in use by increasing the reference count of the object. 133as being in use by increasing the reference count of the object.
131Note that initially 134Note that initially
132.Fn kcpuset_create 135.Fn kcpuset_create
133sets the reference count to 1. 136sets the reference count to 1.
134.It Fn kcpuset_unuse "kcp" "lst" 137.It Fn kcpuset_unuse "kcp" "lst"
135Decreases the internal reference count of 138Decreases the internal reference count of
136.Fa kcp , 139.Fa kcp ,
137and on the last reference (when the count reaches zero), destroys 140and on the last reference (when the count reaches zero), destroys
138.Fa kcp . 141.Fa kcp .
139If 142If
140.Fa lst 143.Fa lst
141is not 144is not
142.Dv NULL , 145.Dv NULL ,
143then instead of destroying, 146then instead of destroying,
144.Fa kcp 147.Fa kcp
145will be added to the 148will be added to the
146.Fa lst 149.Fa lst
147list for a deferred destruction. 150list for a deferred destruction.
148.It Fn kcpuset_copyin "ucp" "kcp" "len" 151.It Fn kcpuset_copyin "ucp" "kcp" "len"
149Copies the 152Copies the
150.Fa len 153.Fa len
151bytes long user-space 154bytes long user-space
152.Tn CPU 155.Tn CPU
153set 156set
154.Fa ucp 157.Fa ucp
155to the kernel 158to the kernel
156.Tn CPU 159.Tn CPU
157set 160set
158.Fa kcp . 161.Fa kcp .
159.It Fn kcpuset_copyout "kcp" "ucp" "len" 162.It Fn kcpuset_copyout "kcp" "ucp" "len"
160Copies the kernel 163Copies the kernel
161.Tn CPU 164.Tn CPU
162set 165set
163.Fa kcp 166.Fa kcp
164to the user-space 167to the user-space
165.Tn CPU 168.Tn CPU
166set 169set
167.Fa ucp . 170.Fa ucp .
168.It Fn kcpuset_zero "kcp" 171.It Fn kcpuset_zero "kcp"
169Clears the set 172Clears the set
170.Fa kcp . 173.Fa kcp .
171.It Fn kcpuset_fill "kcp" 174.It Fn kcpuset_fill "kcp"
172Fills the whole set 175Fills the whole set
173.Fa kcp 176.Fa kcp
174with ones. 177with ones.
175.It Fn kcpuset_set "kcp" "cpu" 178.It Fn kcpuset_set "kcp" "cpu"
176Adds 179Adds
177.Fa cpu 180.Fa cpu
178to the set 181to the set
179.Fa kcp . 182.Fa kcp .
180.It Fn kcpuset_clear "kcp" "cpu" 183.It Fn kcpuset_clear "kcp" "cpu"
181Removes 184Removes
182.Fa cpu 185.Fa cpu
183from the set 186from the set
184.Fa kcp . 187.Fa kcp .
185.It Fn kcpuset_isset "kcp" "cpu" 188.It Fn kcpuset_isset "kcp" "cpu"
186Returns true if 189Returns true if
187.Fa cpu 190.Fa cpu
188is part of the 191is part of the
189.Tn CPU 192.Tn CPU
190set 193set
191.Fa kcp . 194.Fa kcp .
192.It Fn kcpuset_isotherset "kcp" "cpu" 195.It Fn kcpuset_isotherset "kcp" "cpu"
193Returns true if there any CPUs 196Returns true if there any CPUs
194other than 197other than
195.Fa cpu 198.Fa cpu
196in the 199in the
197.Tn CPU 200.Tn CPU
198set 201set
199.Fa kcp . 202.Fa kcp .
200.It Fn kcpuset_iszero "kcp" 203.It Fn kcpuset_iszero "kcp"
201Returns true if the set 204Returns true if the set
202.Fa kcp 205.Fa kcp
203is empty. 206is empty.
204.It Fn kcpuset_match "kcp1" "kcp2" 207.It Fn kcpuset_match "kcp1" "kcp2"
205Compares the sets 208Compares the sets
206.Fa kcp1 209.Fa kcp1
207and 210and
208.Fa kcp2 , 211.Fa kcp2 ,
209returning true if these are identical. 212returning true if these are identical.
210.It Fn kcpuset_merge "kcp1" "kcp2" 213.It Fn kcpuset_merge "kcp1" "kcp2"
211Merges the set 214Merges the set
212.Fa kcp2 215.Fa kcp2
213to the set 216to the set
214.Fa kcp1 . 217.Fa kcp1 .
215.It Fn kcpuset_countset "kcp" 218.It Fn kcpuset_countset "kcp"
216Counts how many CPUs are in the set 219Counts how many CPUs are in the set
217.Fa kcp . 220.Fa kcp .
218.It Fn kcpuset_atomic_set "kcp" "cpu" 221.It Fn kcpuset_atomic_set "kcp" "cpu"
219The 222The
220.Fn kcpuset_atomic_set 223.Fn kcpuset_atomic_set
221function operates as 224function operates as
222.Fn kcpuset_set , 225.Fn kcpuset_set ,
223but the operation is atomic; see 226but the operation is atomic; see
224.Xr atomic_ops 3 227.Xr atomic_ops 3
225for more details. 228for more details.
226.It Fn kcpuset_atomic_clear "kcp" "cpu" 229.It Fn kcpuset_atomic_clear "kcp" "cpu"
227Removes 230Removes
228.Fa cpu 231.Fa cpu
229from the 232from the
230.Tn CPU 233.Tn CPU
231set 234set
232.Fa kcp 235.Fa kcp
233atomically. 236atomically.
 237.Fn kcpuset_export_u32 "kcp" "bitfield" "len"
 238Exports the CPU set
 239.Fa kcp
 240into a format of 32-bit integer array,
 241specified by
 242.Fa bitfield
 243and length in bytes by
 244.Fa len .
 245An integers is in the host byte-order and represents a bit field.
 246The first bit at index zero represents CPU number 0, and so on.
234.El 247.El
235.Sh CODE REFERENCES 248.Sh CODE REFERENCES
236The 249The
237.Nm 250.Nm
238subsystem is implemented within 251subsystem is implemented within
239.Pa sys/kern/subr_kcpuset.c . 252.Pa sys/kern/subr_kcpuset.c .
240.Sh SEE ALSO 253.Sh SEE ALSO
241.Xr cpuset 3 254.Xr cpuset 3
242.Sh HISTORY 255.Sh HISTORY
243The 256The
244.Nm 257.Nm
245subsystem first appeared in 258subsystem first appeared in
246.Nx 6.0 . 259.Nx 6.0 .