1.\" Copyright (c) 2015 Conrad Meyer <cem@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' 14.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 15.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE 17.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 20.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 21.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 22.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 23.\" POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd July 29, 2016 28.Dt CPUSET 9 29.Os 30.Sh NAME 31.Nm cpuset(9) 32\(em 33.Nm CPUSET_T_INITIALIZER , 34.Nm CPUSET_FSET , 35.Nm CPU_CLR , 36.Nm CPU_COPY , 37.Nm CPU_ISSET , 38.Nm CPU_SET , 39.Nm CPU_ZERO , 40.Nm CPU_FILL , 41.Nm CPU_SETOF , 42.Nm CPU_EMPTY , 43.Nm CPU_ISFULLSET , 44.Nm CPU_FFS , 45.Nm CPU_COUNT , 46.Nm CPU_SUBSET , 47.Nm CPU_OVERLAP , 48.Nm CPU_CMP , 49.Nm CPU_OR , 50.Nm CPU_AND , 51.Nm CPU_NAND , 52.Nm CPU_CLR_ATOMIC , 53.Nm CPU_SET_ATOMIC , 54.Nm CPU_SET_ATOMIC_ACQ , 55.Nm CPU_AND_ATOMIC , 56.Nm CPU_OR_ATOMIC , 57.Nm CPU_COPY_STORE_REL 58.Nd cpuset manipulation macros 59.Sh SYNOPSIS 60.In sys/_cpuset.h 61.In sys/cpuset.h 62.\" 63.Fn CPUSET_T_INITIALIZER "ARRAY_CONTENTS" 64.Vt CPUSET_FSET 65.\" 66.Fn CPU_CLR "size_t cpu_idx" "cpuset_t *cpuset" 67.Fn CPU_COPY "cpuset_t *from" "cpuset_t *to" 68.Ft bool 69.Fn CPU_ISSET "size_t cpu_idx" "cpuset_t *cpuset" 70.Fn CPU_SET "size_t cpu_idx" "cpuset_t *cpuset" 71.Fn CPU_ZERO "cpuset_t *cpuset" 72.Fn CPU_FILL "cpuset_t *cpuset" 73.Fn CPU_SETOF "size_t cpu_idx" "cpuset_t *cpuset" 74.Ft bool 75.Fn CPU_EMPTY "cpuset_t *cpuset" 76.Ft bool 77.Fn CPU_ISFULLSET "cpuset_t *cpuset" 78.Ft int 79.Fn CPU_FFS "cpuset_t *cpuset" 80.Ft int 81.Fn CPU_COUNT "cpuset_t *cpuset" 82.\" 83.Ft bool 84.Fn CPU_SUBSET "cpuset_t *haystack" "cpuset_t *needle" 85.Ft bool 86.Fn CPU_OVERLAP "cpuset_t *cpuset1" "cpuset_t *cpuset2" 87.Ft bool 88.Fn CPU_CMP "cpuset_t *cpuset1" "cpuset_t *cpuset2" 89.Fn CPU_OR "cpuset_t *dst" "cpuset_t *src" 90.Fn CPU_AND "cpuset_t *dst" "cpuset_t *src" 91.Fn CPU_NAND "cpuset_t *dst" "cpuset_t *src" 92.\" 93.Fn CPU_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" 94.Fn CPU_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" 95.Fn CPU_SET_ATOMIC_ACQ "size_t cpu_idx" "cpuset_t *cpuset" 96.\" 97.Fn CPU_AND_ATOMIC "cpuset_t *dst" "cpuset_t *src" 98.Fn CPU_OR_ATOMIC "cpuset_t *dst" "cpuset_t *src" 99.Fn CPU_COPY_STORE_REL "cpuset_t *from" "cpuset_t *to" 100.Sh DESCRIPTION 101The 102.Nm 103family of macros provide a flexible and efficient CPU set implementation, 104backed by the 105.Xr bitset 9 106macros. 107Each CPU is represented by a single bit. 108The maximum number of CPUs representable by 109.Vt cpuset_t 110is 111.Va MAXCPU . 112Individual CPUs in cpusets are referenced with indices zero through 113.Fa MAXCPU - 1 . 114.Pp 115The 116.Fn CPUSET_T_INITIALIZER 117macro allows one to initialize a 118.Vt cpuset_t 119with a compile time literal value. 120.Pp 121The 122.Fn CPUSET_FSET 123macro defines a compile time literal, usable by 124.Fn CPUSET_T_INITIALIZER , 125representing a full cpuset (all CPUs present). 126For examples of 127.Fn CPUSET_T_INITIALIZER 128and 129.Fn CPUSET_FSET 130usage, see the 131.Sx CPUSET_T_INITIALIZER EXAMPLE 132section. 133.Pp 134The 135.Fn CPU_CLR 136macro removes CPU 137.Fa cpu_idx 138from the cpuset pointed to by 139.Fa cpuset . 140The 141.Fn CPU_CLR_ATOMIC 142macro is identical, but the bit representing the CPU is cleared with atomic 143machine instructions. 144.Pp 145The 146.Fn CPU_COPY 147macro copies the contents of the cpuset 148.Fa from 149to the cpuset 150.Fa to . 151.Fn CPU_COPY_STORE_REL 152is similar, but copies component machine words from 153.Fa from 154and writes them to 155.Fa to 156with atomic store with release semantics. 157(That is, if 158.Fa to 159is composed of multiple machine words, 160.Fn CPU_COPY_STORE_REL 161performs multiple individually atomic operations.) 162.Pp 163The 164.Fn CPU_SET 165macro adds CPU 166.Fa cpu_idx 167to the cpuset pointed to by 168.Fa cpuset , 169if it is not already present. 170The 171.Fn CPU_SET_ATOMIC 172macro is identical, but the bit representing the CPU is set with atomic 173machine instructions. 174The 175.Fn CPU_SET_ATOMIC_ACQ 176macro sets the bit representing the CPU with atomic acquire semantics. 177.Pp 178The 179.Fn CPU_ZERO 180macro removes all CPUs from 181.Fa cpuset . 182.Pp 183The 184.Fn CPU_FILL 185macro adds all CPUs to 186.Fa cpuset . 187.Pp 188The 189.Fn CPU_SETOF 190macro removes all CPUs in 191.Fa cpuset 192before adding only CPU 193.Fa cpu_idx . 194.Pp 195The 196.Fn CPU_EMPTY 197macro returns 198.Dv true 199if 200.Fa cpuset 201is empty. 202.Pp 203The 204.Fn CPU_ISFULLSET 205macro returns 206.Dv true 207if 208.Fa cpuset 209is full (the set of all CPUs). 210.Pp 211The 212.Fn CPU_FFS 213macro returns the 1-index of the first (lowest) CPU in 214.Fa cpuset , 215or zero if 216.Fa cpuset 217is empty. 218Like with 219.Xr ffs 3 , 220to use the non-zero result of 221.Fn CPU_FFS 222as a 223.Fa cpu_idx 224index parameter to any other 225.Nm 226macro, you must subtract one from the result. 227.Pp 228The 229.Fn CPU_COUNT 230macro returns the total number of CPUs in 231.Fa cpuset . 232.Pp 233The 234.Fn CPU_SUBSET 235macro returns 236.Dv true 237if 238.Fa needle 239is a subset of 240.Fa haystack . 241.Pp 242The 243.Fn CPU_OVERLAP 244macro returns 245.Dv true 246if 247.Fa cpuset1 248and 249.Fa cpuset2 250have any common CPUs. 251(That is, if 252.Fa cpuset1 253AND 254.Fa cpuset2 255is not the empty set.) 256.Pp 257The 258.Fn CPU_CMP 259macro returns 260.Dv true 261if 262.Fa cpuset1 263is NOT equal to 264.Fa cpuset2 . 265.Pp 266The 267.Fn CPU_OR 268macro adds CPUs present in 269.Fa src 270to 271.Fa dst . 272(It is the 273.Nm 274equivalent of the scalar: 275.Fa dst 276|= 277.Fa src . ) 278.Fn CPU_OR_ATOMIC 279is similar, but sets the bits representing CPUs in the component machine words 280in 281.Fa dst 282with atomic machine instructions. 283(That is, if 284.Fa dst 285is composed of multiple machine words, 286.Fn CPU_OR_ATOMIC 287performs multiple individually atomic operations.) 288.Pp 289The 290.Fn CPU_AND 291macro removes CPUs absent from 292.Fa src 293from 294.Fa dst . 295(It is the 296.Nm 297equivalent of the scalar: 298.Fa dst 299&= 300.Fa src . ) 301.Fn CPU_AND_ATOMIC 302is similar, with the same atomic semantics as 303.Fn CPU_OR_ATOMIC . 304.Pp 305The 306.Fn CPU_NAND 307macro removes CPUs in 308.Fa src 309from 310.Fa dst . 311(It is the 312.Nm 313equivalent of the scalar: 314.Fa dst 315&= 316.Fa ~ src . ) 317.Sh CPUSET_T_INITIALIZER EXAMPLE 318.Bd -literal 319cpuset_t myset; 320 321/* Initialize myset to filled (all CPUs) */ 322myset = CPUSET_T_INITIALIZER(CPUSET_FSET); 323 324/* Initialize myset to only the lowest CPU */ 325myset = CPUSET_T_INITIALIZER(0x1); 326.Ed 327.Sh SEE ALSO 328.Xr cpuset 1 , 329.Xr cpuset 2 , 330.Xr bitset 9 331.Sh HISTORY 332.In sys/cpuset.h 333first appeared in 334.Fx 7.1 , 335released in January 2009, and in 336.Fx 8.0 , 337released in November 2009. 338.Pp 339This manual page first appeared in 340.Fx 11.0 . 341.Sh AUTHORS 342.An -nosplit 343The 344.Nm 345macros were written by 346.An Jeff Roberson Aq Mt jeff@FreeBSD.org . 347This manual page was written by 348.An Conrad Meyer Aq Mt cem@FreeBSD.org . 349.Sh CAVEATS 350Unlike every other reference to individual set members, which are zero-indexed, 351.Fn CPU_FFS 352returns a one-indexed result (or zero if the cpuset is empty). 353