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.Dd September 23, 2022 26.Dt CPUSET 9 27.Os 28.Sh NAME 29.Nm cpuset(9) 30\(em 31.Nm CPUSET_T_INITIALIZER , 32.Nm CPUSET_FSET , 33.Nm CPU_CLR , 34.Nm CPU_COPY , 35.Nm CPU_ISSET , 36.Nm CPU_SET , 37.Nm CPU_ZERO , 38.Nm CPU_FILL , 39.Nm CPU_SETOF , 40.Nm CPU_EMPTY , 41.Nm CPU_ISFULLSET , 42.Nm CPU_FFS , 43.Nm CPU_COUNT , 44.Nm CPU_SUBSET , 45.Nm CPU_OVERLAP , 46.Nm CPU_CMP , 47.Nm CPU_OR , 48.Nm CPU_AND , 49.Nm CPU_ANDNOT , 50.Nm CPU_XOR , 51.Nm CPU_CLR_ATOMIC , 52.Nm CPU_SET_ATOMIC , 53.Nm CPU_SET_ATOMIC_ACQ , 54.Nm CPU_AND_ATOMIC , 55.Nm CPU_OR_ATOMIC , 56.Nm CPU_COPY_STORE_REL 57.Nd cpuset manipulation macros 58.Sh SYNOPSIS 59.In sys/_cpuset.h 60.In sys/cpuset.h 61.\" 62.Fn CPUSET_T_INITIALIZER "ARRAY_CONTENTS" 63.Vt CPUSET_FSET 64.\" 65.Fn CPU_CLR "size_t cpu_idx" "cpuset_t *cpuset" 66.Fn CPU_COPY "cpuset_t *from" "cpuset_t *to" 67.Ft bool 68.Fn CPU_ISSET "size_t cpu_idx" "cpuset_t *cpuset" 69.Fn CPU_SET "size_t cpu_idx" "cpuset_t *cpuset" 70.Fn CPU_ZERO "cpuset_t *cpuset" 71.Fn CPU_FILL "cpuset_t *cpuset" 72.Fn CPU_SETOF "size_t cpu_idx" "cpuset_t *cpuset" 73.Ft bool 74.Fn CPU_EMPTY "cpuset_t *cpuset" 75.Ft bool 76.Fn CPU_ISFULLSET "cpuset_t *cpuset" 77.Ft int 78.Fn CPU_FFS "cpuset_t *cpuset" 79.Ft int 80.Fn CPU_COUNT "cpuset_t *cpuset" 81.\" 82.Ft bool 83.Fn CPU_SUBSET "cpuset_t *haystack" "cpuset_t *needle" 84.Ft bool 85.Fn CPU_OVERLAP "cpuset_t *cpuset1" "cpuset_t *cpuset2" 86.Ft bool 87.Fn CPU_CMP "cpuset_t *cpuset1" "cpuset_t *cpuset2" 88.Fn CPU_OR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 89.Fn CPU_AND "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 90.Fn CPU_ANDNOT "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 91.Fn CPU_XOR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 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 CPU_SETSIZE . 112Individual CPUs in cpusets are referenced with indices zero through 113.Fa CPU_SETSIZE - 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_ISSET 180macro returns 181.Dv true 182if CPU 183.Fa cpu_idx 184is a member of the cpuset pointed to by 185.Fa cpuset . 186.Pp 187The 188.Fn CPU_ZERO 189macro removes all CPUs from 190.Fa cpuset . 191.Pp 192The 193.Fn CPU_FILL 194macro adds all CPUs to 195.Fa cpuset . 196.Pp 197The 198.Fn CPU_SETOF 199macro removes all CPUs in 200.Fa cpuset 201before adding only CPU 202.Fa cpu_idx . 203.Pp 204The 205.Fn CPU_EMPTY 206macro returns 207.Dv true 208if 209.Fa cpuset 210is empty. 211.Pp 212The 213.Fn CPU_ISFULLSET 214macro returns 215.Dv true 216if 217.Fa cpuset 218is full (the set of all CPUs). 219.Pp 220The 221.Fn CPU_FFS 222macro returns the 1-index of the first (lowest) CPU in 223.Fa cpuset , 224or zero if 225.Fa cpuset 226is empty. 227Like with 228.Xr ffs 3 , 229to use the non-zero result of 230.Fn CPU_FFS 231as a 232.Fa cpu_idx 233index parameter to any other 234.Nm 235macro, you must subtract one from the result. 236.Pp 237The 238.Fn CPU_COUNT 239macro returns the total number of CPUs in 240.Fa cpuset . 241.Pp 242The 243.Fn CPU_SUBSET 244macro returns 245.Dv true 246if 247.Fa needle 248is a subset of 249.Fa haystack . 250.Pp 251The 252.Fn CPU_OVERLAP 253macro returns 254.Dv true 255if 256.Fa cpuset1 257and 258.Fa cpuset2 259have any common CPUs. 260(That is, if 261.Fa cpuset1 262AND 263.Fa cpuset2 264is not the empty set.) 265.Pp 266The 267.Fn CPU_CMP 268macro returns 269.Dv true 270if 271.Fa cpuset1 272is NOT equal to 273.Fa cpuset2 . 274.Pp 275The 276.Fn CPU_OR 277macro adds CPUs present in 278.Fa src 279to 280.Fa dst . 281(It is the 282.Nm 283equivalent of the scalar: 284.Fa dst 285|= 286.Fa src . ) 287.Fn CPU_OR_ATOMIC 288is similar, but sets the bits representing CPUs in the component machine words 289in 290.Fa dst 291with atomic machine instructions. 292(That is, if 293.Fa dst 294is composed of multiple machine words, 295.Fn CPU_OR_ATOMIC 296performs multiple individually atomic operations.) 297.Pp 298The 299.Fn CPU_AND 300macro removes CPUs absent from 301.Fa src 302from 303.Fa dst . 304(It is the 305.Nm 306equivalent of the scalar: 307.Fa dst 308&= 309.Fa src . ) 310.Fn CPU_AND_ATOMIC 311is similar, with the same atomic semantics as 312.Fn CPU_OR_ATOMIC . 313.Pp 314The 315.Fn CPU_ANDNOT 316macro removes CPUs in 317.Fa src 318from 319.Fa dst . 320(It is the 321.Nm 322equivalent of the scalar: 323.Fa dst 324&= 325.Fa ~ src . ) 326.Sh CPUSET_T_INITIALIZER EXAMPLE 327.Bd -literal 328cpuset_t myset; 329 330/* Initialize myset to filled (all CPUs) */ 331myset = CPUSET_T_INITIALIZER(CPUSET_FSET); 332 333/* Initialize myset to only the lowest CPU */ 334myset = CPUSET_T_INITIALIZER(0x1); 335.Ed 336.Sh SEE ALSO 337.Xr cpuset 1 , 338.Xr cpuset 2 , 339.Xr bitset 9 340.Sh HISTORY 341.In sys/cpuset.h 342first appeared in 343.Fx 7.1 , 344released in January 2009, and in 345.Fx 8.0 , 346released in November 2009. 347.Pp 348This manual page first appeared in 349.Fx 11.0 . 350.Sh AUTHORS 351.An -nosplit 352The 353.Nm 354macros were written by 355.An Jeff Roberson Aq Mt jeff@FreeBSD.org . 356This manual page was written by 357.An Conrad Meyer Aq Mt cem@FreeBSD.org . 358.Sh CAVEATS 359Unlike every other reference to individual set members, which are zero-indexed, 360.Fn CPU_FFS 361returns a one-indexed result (or zero if the cpuset is empty). 362