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