1.\" $NetBSD: kcpuset.9,v 1.2 2011/10/06 08:59:01 wiz 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 October 6, 2011 29.Dt KCPUSET 9 30.Os 31.Sh NAME 32.Nm kcpuset , 33.Nm kcpuset_create , 34.Nm kcpuset_destroy , 35.Nm kcpuset_copy , 36.Nm kcpuset_use , 37.Nm kcpuset_unuse , 38.Nm kcpuset_copyin , 39.Nm kcpuset_copyout , 40.Nm kcpuset_zero , 41.Nm kcpuset_fill , 42.Nm kcpuset_set , 43.Nm kcpuset_clear , 44.Nm kcpuset_isset , 45.Nm kcpuset_iszero , 46.Nm kcpuset_match , 47.Nm kcpuset_merge , 48.Nm kcpuset_atomic_set , 49.Nm kcpuset_atomic_clear 50.Nd dynamic kernel CPU sets 51.Sh SYNOPSIS 52.In sys/kcpuset.h 53.Ft void 54.Fn kcpuset_create "kcpuset_t **retkcp" "bool zero" 55.Ft void 56.Fn kcpuset_destroy "kcpuset_t *kcp" 57.Ft void 58.Fn kcpuset_copy "kcpuset_t *dkcp" "kcpuset_t *skcp" 59.Ft void 60.Fn kcpuset_use "kcpuset_t *kcp" 61.Ft void 62.Fn kcpuset_unuse "kcpuset_t *kcp" "kcpuset_t **lst" 63.Ft int 64.Fn kcpuset_copyin "const cpuset_t *ucp" "kcpuset_t *kcp" "size_t len" 65.Ft int 66.Fn kcpuset_copyout "kcpuset_t *kcp" "cpuset_t *ucp" "size_t len" 67.Ft void 68.Fn kcpuset_zero "kcpuset_t *kcp" 69.Ft void 70.Fn kcpuset_fill "kcpuset_t *kcp" 71.Ft void 72.Fn kcpuset_set "kcpuset_t *kcp" "cpuid_t cpu" 73.Ft void 74.Fn kcpuset_clear "kcpuset_t *kcp" "cpuid_t cpu" 75.Ft int 76.Fn kcpuset_isset "kcpuset_t * kcp" "cpuid_t cpu" 77.Ft bool 78.Fn kcpuset_iszero "kcpuset_t *kcp" 79.Ft bool 80.Fn kcpuset_match "const kcpuset_t *kcp1" "const kcpuset_t *kcp2" 81.Ft void 82.Fn kcpuset_merge "kcpuset_t *kcp1" "kcpuset_t *kcp2" 83.Ft void 84.Fn kcpuset_atomic_set "kcpuset_t *kcp" "cpuid_t cpu" 85.Ft void 86.Fn kcpuset_atomic_clear "kcpuset_t *kcp" "cpuid_t cpu" 87.Sh DESCRIPTION 88The machine-independent 89.Nm 90subsystem provides support for dynamic processor sets. 91Conceptually 92.Nm 93can be understood to be the kernel equivalent of the user space 94.Xr cpuset 3 95interface. 96.Sh FUNCTIONS 97.Bl -tag -width compact 98.It Fn kcpuset_create "retkcp" "zero" 99The 100.Fn kcpuset_create 101function creates a dynamic 102.Tn CPU 103set and stores the result to 104.Fa retkcp . 105If the boolean 106.Fa zero 107is not false, the allocated set is also initialized to zero. 108.It Fn kcpuset_destroy "kcp" 109Destroys the 110.Tn CPU 111set 112.Fa kcp 113and schedules any linked CPU sets for deferred destruction. 114.It Fn kcpuset_copy "dkcp" "skcp" 115Copies the 116.Tn CPU 117set pointed by 118.Fa skcp 119to 120.Fa dkcp . 121.It Fn kcpuset_use "kcp" 122Marks 123.Fa kcp 124as being in use by increasing the reference count of the object. 125Note that initially 126.Fn kcpuset_create 127sets the reference count to 1. 128.It Fn kcpuset_unuse "kcp" "lst" 129Decreases the internal reference count of 130.Fa kcp , 131and on the last reference (when the count reaches zero), destroys 132.Fa kcp . 133If 134.Fa lst 135is not 136.Dv NULL , 137then instead of destroying, 138.Fa kcp 139will be added to the 140.Fa lst 141list for a deferred destruction. 142.It Fn kcpuset_copyin "ucp" "kcp" "len" 143Copies the 144.Fa len 145bytes long user-space 146.Tn CPU 147set 148.Fa ucp 149to the kernel 150.Tn CPU 151set 152.Fa kcp . 153.It Fn kcpuset_copyout "kcp" "ucp" "len" 154Copies the kernel 155.Tn CPU 156set 157.Fa kcp 158to the user-space 159.Tn CPU 160set 161.Fa ucp . 162.It Fn kcpuset_zero "kcp" 163Clears the set 164.Fa kcp . 165.It Fn kcpuset_fill "kcp" 166Fills the whole set 167.Fa kcp 168with ones. 169.It Fn kcpuset_set "kcp" "cpu" 170Adds 171.Fa cpu 172to the set 173.Fa kcp . 174.It Fn kcpuset_clear "kcp" "cpu" 175Removes 176.Fa cpu 177from the set 178.Fa kcp . 179.It Fn kcpuset_isset "kcp" "cpu" 180Returns 1 if 181.Fa cpu 182is part of the 183.Tn CPU 184set 185.Fa kcp . 186.It Fn kcpuset_iszero "kcp" 187Returns true if the set 188.Fa kcp 189is empty. 190.It Fn kcpuset_match "kcp1" "kcp2" 191Compares the sets 192.Fa kcp1 193and 194.Fa kcp2 , 195returning true if these are identical. 196.It Fn kcpuset_merge "kcp1" "kcp2" 197Merges the set 198.Fa kcp2 199to the set 200.Fa kcp1 . 201.It Fn kcpuset_atomic_set "kcp" "cpu" 202The 203.Fn kcpuset_atomic_set 204function operates as 205.Fn kcpuset_set , 206but the operation is atomic; see 207.Xr atomic_ops 3 208for more details. 209.It Fn kcpuset_atomic_clear "kcp" "cpu" 210Removes 211.Fa cpu 212from the 213.Tn CPU 214set 215.Fa kcp 216atomically. 217.El 218.Sh CODE REFERENCES 219The 220.Nm 221subsystem is implemented within 222.Pa sys/kern/subr_kcpuset.c . 223.Sh SEE ALSO 224.Xr cpuset 3 225.Sh HISTORY 226The 227.Nm 228subsystem first appeared in 229.Nx 6.0 . 230