1.\" $NetBSD: kcpuset.9,v 1.9 2014/03/18 18:20:40 riastradh Exp $ */ 2.\" 3.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 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 18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 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 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 26.\" POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd July 17, 2013 29.Dt KCPUSET 9 30.Os 31.Sh NAME 32.Nm kcpuset , 33.Nm kcpuset_create , 34.Nm kcpuset_destroy , 35.Nm kcpuset_clone , 36.Nm kcpuset_copy , 37.Nm kcpuset_use , 38.Nm kcpuset_unuse , 39.Nm kcpuset_copyin , 40.Nm kcpuset_copyout , 41.Nm kcpuset_zero , 42.Nm kcpuset_fill , 43.Nm kcpuset_set , 44.Nm kcpuset_clear , 45.Nm kcpuset_isset , 46.Nm kcpuset_isotherset , 47.Nm kcpuset_iszero , 48.Nm kcpuset_match , 49.Nm kcpuset_intersect , 50.Nm kcpuset_merge , 51.Nm kcpuset_remove , 52.Nm kcpuset_ffs , 53.Nm kcpuset_ffs_intersecting , 54.Nm kcpuset_countset , 55.Nm kcpuset_atomic_set , 56.Nm kcpuset_atomic_clear , 57.Nm kcpuset_atomicly_intersect , 58.Nm kcpuset_atomicly_merge , 59.Nm kcpuset_atomicly_remove , 60.Nm kcpuset_export_32 61.Nd dynamic kernel CPU sets 62.Sh SYNOPSIS 63.In sys/kcpuset.h 64.Ft void 65.Fn kcpuset_create "kcpuset_t **retkcp" "bool zero" 66.Ft void 67.Fn kcpuset_destroy "kcpuset_t *kcp" 68.Ft void 69.Fn kcpuset_clone "kcpuset_t **retkcp" "const kcpuset_t *skcp" 70.Ft void 71.Fn kcpuset_copy "kcpuset_t *dkcp" "const kcpuset_t *skcp" 72.Ft void 73.Fn kcpuset_use "kcpuset_t *kcp" 74.Ft void 75.Fn kcpuset_unuse "kcpuset_t *kcp" "kcpuset_t **lst" 76.Ft int 77.Fn kcpuset_copyin "const cpuset_t *ucp" "kcpuset_t *kcp" "size_t len" 78.Ft int 79.Fn kcpuset_copyout "kcpuset_t *kcp" "cpuset_t *ucp" "size_t len" 80.Ft void 81.Fn kcpuset_zero "kcpuset_t *kcp" 82.Ft void 83.Fn kcpuset_fill "kcpuset_t *kcp" 84.Ft void 85.Fn kcpuset_set "kcpuset_t *kcp" "cpuid_t cpu" 86.Ft void 87.Fn kcpuset_clear "kcpuset_t *kcp" "cpuid_t cpu" 88.Ft bool 89.Fn kcpuset_isset "const kcpuset_t * kcp" "cpuid_t cpu" 90.Ft bool 91.Fn kcpuset_isotherset "const kcpuset_t * kcp" "cpuid_t cpu" 92.Ft bool 93.Fn kcpuset_iszero "const kcpuset_t *kcp" 94.Ft bool 95.Fn kcpuset_intersecting_p "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" 96.Ft bool 97.Fn kcpuset_match "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" 98.Ft void 99.Fn kcpuset_intersect "kcpuset_t *kcp1" "const kcpuset_t *kcp2" 100.Ft void 101.Fn kcpuset_merge "kcpuset_t *kcp1" "const kcpuset_t *kcp2" 102.Ft void 103.Fn kcpuset_remove "kcpuset_t *kcp1" "const kcpuset_t *kcp2" 104.Ft cpuid_t 105.Fn kcpuset_ffs "const kcpuset_t *kcp" 106.Ft cpuid_t 107.Fn kcpuset_ffs_intersecting "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" 108.Ft int 109.Fn kcpuset_countset "const kcpuset_t *kcp" 110.Ft void 111.Fn kcpuset_atomic_set "kcpuset_t *kcp" "cpuid_t cpu" 112.Ft void 113.Fn kcpuset_atomic_clear "kcpuset_t *kcp" "cpuid_t cpu" 114.Ft void 115.Fn kcpuset_atomicly_intersect "kcpuset_t *kcp1" "const kcpuset_t *kcp2" 116.Ft void 117.Fn kcpuset_atomicly_merge "kcpuset_t *kcp1" "const kcpuset_t *kcp2" 118.Ft void 119.Fn kcpuset_atomicly_remove "kcpuset_t *kcp1" "const kcpuset_t *kcp2" 120.Ft void 121.Fn kcpuset_export_u32 "const kcpuset_t *kcp" "uint32_t *bitfield" "size_t len" 122.Sh DESCRIPTION 123The machine-independent 124.Nm 125subsystem provides support for dynamic processor sets. 126Conceptually 127.Nm 128can be understood to be the kernel equivalent of the user space 129.Xr cpuset 3 130interface. 131.Sh FUNCTIONS 132.Bl -tag -width compact 133.It Fn kcpuset_create "retkcp" "zero" 134The 135.Fn kcpuset_create 136function creates a dynamic 137.Tn CPU 138set and stores the result to 139.Fa retkcp . 140If the boolean 141.Fa zero 142is not false, the allocated set is also initialized to zero. 143.It Fn kcpuset_destroy "kcp" 144Destroys the 145.Tn CPU 146set 147.Fa kcp 148and schedules any linked CPU sets for deferred destruction. 149.It Fn kcpuset_copy "dkcp" "skcp" 150Copies the 151.Tn CPU 152set pointed by 153.Fa skcp 154to 155.Fa dkcp . 156.It Fn kcpuset_clone "retkcp" "skcp" 157Creates a dynamic 158.Tn CPU 159set and stores the result to 160.Fa retkcp 161and copies the 162.Tn CPU 163set pointed by 164.Fa skcp 165to the new 166.Tn CPU 167set. 168.It Fn kcpuset_use "kcp" 169Marks 170.Fa kcp 171as being in use by increasing the reference count of the object. 172Note that initially 173.Fn kcpuset_create 174sets the reference count to 1. 175.It Fn kcpuset_unuse "kcp" "lst" 176Decreases the internal reference count of 177.Fa kcp , 178and on the last reference (when the count reaches zero), destroys 179.Fa kcp . 180If 181.Fa lst 182is not 183.Dv NULL , 184then instead of destroying, 185.Fa kcp 186will be added to the 187.Fa lst 188list for a deferred destruction. 189.It Fn kcpuset_copyin "ucp" "kcp" "len" 190Copies the 191.Fa len 192bytes long user-space 193.Tn CPU 194set 195.Fa ucp 196to the kernel 197.Tn CPU 198set 199.Fa kcp . 200.It Fn kcpuset_copyout "kcp" "ucp" "len" 201Copies the kernel 202.Tn CPU 203set 204.Fa kcp 205to the user-space 206.Tn CPU 207set 208.Fa ucp . 209.It Fn kcpuset_zero "kcp" 210Clears the set 211.Fa kcp . 212.It Fn kcpuset_fill "kcp" 213Fills the whole set 214.Fa kcp 215with ones. 216.It Fn kcpuset_set "kcp" "cpu" 217Adds 218.Fa cpu 219to the set 220.Fa kcp . 221.It Fn kcpuset_clear "kcp" "cpu" 222Removes 223.Fa cpu 224from the set 225.Fa kcp . 226.It Fn kcpuset_isset "kcp" "cpu" 227Returns true if 228.Fa cpu 229is part of the 230.Tn CPU 231set 232.Fa kcp . 233.It Fn kcpuset_isotherset "kcp" "cpu" 234Returns true if there any CPUs 235other than 236.Fa cpu 237in the 238.Tn CPU 239set 240.Fa kcp . 241.It Fn kcpuset_iszero "kcp" 242Returns true if the set 243.Fa kcp 244is empty. 245.It Fn kcpuset_match "kcp1" "kcp2" 246Compares the sets 247.Fa kcp1 248and 249.Fa kcp2 , 250returning true if these are identical. 251.It Fn kcpuset_intersect "kcp1" "kcp2" 252Removes any 253.Tn CPU 254not set in 255.Fa kcp2 256from the set 257.Fa kcp1 . 258.It Fn kcpuset_merge "kcp1" "kcp2" 259Merges the set 260.Fa kcp2 261to the set 262.Fa kcp1 . 263.It Fn kcpuset_remove "kcp1" "kcp2" 264Removes any 265.Tn CPU 266present in 267.Fa kcp2 268from the set 269.Fa kcp1 . 270.It Fn kcpuset_ffs "kcp" 271Returns the lowest numbered 272.Ft cpu 273present in 274.Fa kcp 275plus 1. 276If 277.Fa kcp 278is empty, a value of 0 is returned. 279.Fa kcp 280.It Fn kcpuset_ffs_intersecting "kcp1" "kcp2" 281Returns the lowest numbered 282.Ft cpu 283present in the intersection of 284.Fa kcp1 285and 286.Fa kcp2 287plus 1. 288If the intersection is empty, a value of 0 is returned. 289.It Fn kcpuset_countset "kcp" 290Counts how many CPUs are in the set 291.Fa kcp . 292.It Fn kcpuset_atomic_set "kcp" "cpu" 293The 294.Fn kcpuset_atomic_set 295function operates as 296.Fn kcpuset_set , 297but the operation is atomic; see 298.Xr atomic_ops 3 299for more details. 300.It Fn kcpuset_atomic_clear "kcp" "cpu" 301Removes 302.Fa cpu 303from the 304.Tn CPU 305set 306.Fa kcp 307atomically. 308.It Fn kcpuset_atomicly_intersect "kcp1" "kcp2" 309The 310.Fn kcpuset_atomicly_intersect 311function operates as 312.Fn kcpuset_intersect , 313but the operation is performed using atomic operations; see 314.Xr atomic_ops 3 315for more details. 316.It Fn kcpuset_atomicly_merge "kcp1" "kcp2" 317The 318.Fn kcpuset_atomicly_merge 319function operates as 320.Fn kcpuset_merge , 321but the operation is performed using atomic operations; see 322.Xr atomic_ops 3 323for more details. 324.It Fn kcpuset_atomicly_remove "kcp1" "kcp2" 325The 326.Fn kcpuset_atomicly_remove 327function operates as 328.Fn kcpuset_remove , 329but the operation is performed using atomic operations; see 330.Xr atomic_ops 3 331for more details. 332.It Fn kcpuset_export_u32 "kcp" "bitfield" "len" 333Exports the CPU set 334.Fa kcp 335into a format of 32-bit integer array, 336specified by 337.Fa bitfield 338and length in bytes by 339.Fa len . 340An integers is in the host byte-order and represents a bit field. 341The first bit at index zero represents CPU number 0, and so on. 342.El 343.Sh CODE REFERENCES 344The 345.Nm 346subsystem is implemented within 347.Pa sys/kern/subr_kcpuset.c . 348.Sh SEE ALSO 349.Xr cpuset 3 350.Sh HISTORY 351The 352.Nm 353subsystem first appeared in 354.Nx 6.0 . 355