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 August 7, 2025 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_ORNOT , 49.Nm CPU_AND , 50.Nm CPU_ANDNOT , 51.Nm CPU_XOR , 52.Nm CPU_CLR_ATOMIC , 53.Nm CPU_TEST_CLR_ATOMIC , 54.Nm CPU_SET_ATOMIC , 55.Nm CPU_SET_ATOMIC_ACQ , 56.Nm CPU_TEST_SET_ATOMIC , 57.Nm CPU_AND_ATOMIC , 58.Nm CPU_OR_ATOMIC , 59.Nm CPU_COPY_STORE_REL 60.Nd cpuset manipulation macros 61.Sh SYNOPSIS 62.In sys/_cpuset.h 63.In sys/cpuset.h 64.\" 65.Fn CPUSET_T_INITIALIZER "ARRAY_CONTENTS" 66.Vt CPUSET_FSET 67.\" 68.Fn CPU_CLR "size_t cpu_idx" "cpuset_t *cpuset" 69.Fn CPU_COPY "cpuset_t *from" "cpuset_t *to" 70.Ft bool 71.Fn CPU_ISSET "size_t cpu_idx" "cpuset_t *cpuset" 72.Fn CPU_SET "size_t cpu_idx" "cpuset_t *cpuset" 73.Fn CPU_ZERO "cpuset_t *cpuset" 74.Fn CPU_FILL "cpuset_t *cpuset" 75.Fn CPU_SETOF "size_t cpu_idx" "cpuset_t *cpuset" 76.Ft bool 77.Fn CPU_EMPTY "cpuset_t *cpuset" 78.Ft bool 79.Fn CPU_ISFULLSET "cpuset_t *cpuset" 80.Ft int 81.Fn CPU_FFS "cpuset_t *cpuset" 82.Ft int 83.Fn CPU_COUNT "cpuset_t *cpuset" 84.\" 85.Ft bool 86.Fn CPU_SUBSET "cpuset_t *haystack" "cpuset_t *needle" 87.Ft bool 88.Fn CPU_OVERLAP "cpuset_t *cpuset1" "cpuset_t *cpuset2" 89.Ft bool 90.Fn CPU_CMP "cpuset_t *cpuset1" "cpuset_t *cpuset2" 91.Fn CPU_OR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 92.Fn CPU_ORNOT "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 93.Fn CPU_AND "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 94.Fn CPU_ANDNOT "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 95.Fn CPU_XOR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" 96.\" 97.Fn CPU_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" 98.Fn CPU_TEST_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" 99.Fn CPU_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" 100.Fn CPU_SET_ATOMIC_ACQ "size_t cpu_idx" "cpuset_t *cpuset" 101.Fn CPU_TEST_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" 102.\" 103.Fn CPU_AND_ATOMIC "cpuset_t *dst" "cpuset_t *src" 104.Fn CPU_OR_ATOMIC "cpuset_t *dst" "cpuset_t *src" 105.Fn CPU_COPY_STORE_REL "cpuset_t *from" "cpuset_t *to" 106.Sh DESCRIPTION 107The 108.Nm 109family of macros provide a flexible and efficient CPU set implementation, 110backed by the 111.Xr bitset 9 112macros. 113Each CPU is represented by a single bit. 114The maximum number of CPUs representable by 115.Vt cpuset_t 116is 117.Va CPU_SETSIZE . 118Individual CPUs in cpusets are referenced with indices zero through 119.Fa CPU_SETSIZE - 1 . 120.Pp 121The 122.Fn CPUSET_T_INITIALIZER 123macro allows one to initialize a 124.Vt cpuset_t 125with a compile time literal value. 126.Pp 127The 128.Fn CPUSET_FSET 129macro defines a compile time literal, usable by 130.Fn CPUSET_T_INITIALIZER , 131representing a full cpuset (all CPUs present). 132For examples of 133.Fn CPUSET_T_INITIALIZER 134and 135.Fn CPUSET_FSET 136usage, see the 137.Sx CPUSET_T_INITIALIZER EXAMPLE 138section. 139.Pp 140The 141.Fn CPU_CLR 142macro removes CPU 143.Fa cpu_idx 144from the cpuset pointed to by 145.Fa cpuset . 146The 147.Fn CPU_CLR_ATOMIC 148macro is identical, but the bit representing the CPU is cleared with atomic 149machine instructions. 150The 151.Fn CPU_TEST_CLR_ATOMIC 152macro atomically clears the bit representing the CPU and returns whether it 153was set. 154.Pp 155The 156.Fn CPU_COPY 157macro copies the contents of the cpuset 158.Fa from 159to the cpuset 160.Fa to . 161.Fn CPU_COPY_STORE_REL 162is similar, but copies component machine words from 163.Fa from 164and writes them to 165.Fa to 166with atomic store with release semantics. 167(That is, if 168.Fa to 169is composed of multiple machine words, 170.Fn CPU_COPY_STORE_REL 171performs multiple individually atomic operations.) 172.Pp 173The 174.Fn CPU_SET 175macro adds CPU 176.Fa cpu_idx 177to the cpuset pointed to by 178.Fa cpuset , 179if it is not already present. 180The 181.Fn CPU_SET_ATOMIC 182macro is identical, but the bit representing the CPU is set with atomic 183machine instructions. 184The 185.Fn CPU_SET_ATOMIC_ACQ 186macro sets the bit representing the CPU with atomic acquire semantics. 187The 188.Fn CPU_TEST_SET_ATOMIC 189macro atomically sets the bit representing the CPU and returns whether it was 190set. 191.Pp 192The 193.Fn CPU_ISSET 194macro returns 195.Dv true 196if CPU 197.Fa cpu_idx 198is a member of the cpuset pointed to by 199.Fa cpuset . 200.Pp 201The 202.Fn CPU_ZERO 203macro removes all CPUs from 204.Fa cpuset . 205.Pp 206The 207.Fn CPU_FILL 208macro adds all CPUs to 209.Fa cpuset . 210.Pp 211The 212.Fn CPU_SETOF 213macro removes all CPUs in 214.Fa cpuset 215before adding only CPU 216.Fa cpu_idx . 217.Pp 218The 219.Fn CPU_EMPTY 220macro returns 221.Dv true 222if 223.Fa cpuset 224is empty. 225.Pp 226The 227.Fn CPU_ISFULLSET 228macro returns 229.Dv true 230if 231.Fa cpuset 232is full (the set of all CPUs). 233.Pp 234The 235.Fn CPU_FFS 236macro returns the 1-index of the first (lowest) CPU in 237.Fa cpuset , 238or zero if 239.Fa cpuset 240is empty. 241Like with 242.Xr ffs 3 , 243to use the non-zero result of 244.Fn CPU_FFS 245as a 246.Fa cpu_idx 247index parameter to any other 248.Nm 249macro, you must subtract one from the result. 250.Pp 251The 252.Fn CPU_COUNT 253macro returns the total number of CPUs in 254.Fa cpuset . 255.Pp 256The 257.Fn CPU_SUBSET 258macro returns 259.Dv true 260if 261.Fa needle 262is a subset of 263.Fa haystack . 264.Pp 265The 266.Fn CPU_OVERLAP 267macro returns 268.Dv true 269if 270.Fa cpuset1 271and 272.Fa cpuset2 273have any common CPUs. 274(That is, if 275.Fa cpuset1 276AND 277.Fa cpuset2 278is not the empty set.) 279.Pp 280The 281.Fn CPU_CMP 282macro returns 283.Dv true 284if 285.Fa cpuset1 286is NOT equal to 287.Fa cpuset2 . 288.Pp 289The 290.Fn CPU_OR 291macro adds CPUs present in 292.Fa src 293to 294.Fa dst . 295(It is the 296.Nm 297equivalent of the scalar: 298.Fa dst 299|= 300.Fa src . ) 301.Fn CPU_OR_ATOMIC 302is similar, but sets the bits representing CPUs in the component machine words 303in 304.Fa dst 305with atomic machine instructions. 306(That is, if 307.Fa dst 308is composed of multiple machine words, 309.Fn CPU_OR_ATOMIC 310performs multiple individually atomic operations.) 311.Pp 312The 313.Fn CPU_ORNOT 314macro add CPUs not in 315.Fa src 316to 317.Fa dst . 318(It is the 319.Nm 320equivalent of the scalar: 321.Fa dst 322|= 323.Fa ~ src . ) 324.Pp 325The 326.Fn CPU_AND 327macro removes CPUs absent from 328.Fa src 329from 330.Fa dst . 331(It is the 332.Nm 333equivalent of the scalar: 334.Fa dst 335&= 336.Fa src . ) 337.Fn CPU_AND_ATOMIC 338is similar, with the same atomic semantics as 339.Fn CPU_OR_ATOMIC . 340.Pp 341The 342.Fn CPU_ANDNOT 343macro removes CPUs in 344.Fa src 345from 346.Fa dst . 347(It is the 348.Nm 349equivalent of the scalar: 350.Fa dst 351&= 352.Fa ~ src . ) 353.Sh CPUSET_T_INITIALIZER EXAMPLE 354.Bd -literal 355cpuset_t myset; 356 357/* Initialize myset to filled (all CPUs) */ 358myset = CPUSET_T_INITIALIZER(CPUSET_FSET); 359 360/* Initialize myset to only the lowest CPU */ 361myset = CPUSET_T_INITIALIZER(0x1); 362.Ed 363.Sh SEE ALSO 364.Xr cpuset 1 , 365.Xr cpuset 2 , 366.Xr bitset 9 367.Sh HISTORY 368.In sys/cpuset.h 369first appeared in 370.Fx 7.1 , 371released in January 2009, and in 372.Fx 8.0 , 373released in November 2009. 374.Pp 375This manual page first appeared in 376.Fx 11.0 . 377.Sh AUTHORS 378.An -nosplit 379The 380.Nm 381macros were written by 382.An Jeff Roberson Aq Mt jeff@FreeBSD.org . 383This manual page was written by 384.An Conrad Meyer Aq Mt cem@FreeBSD.org . 385.Sh CAVEATS 386Unlike every other reference to individual set members, which are zero-indexed, 387.Fn CPU_FFS 388returns a one-indexed result (or zero if the cpuset is empty). 389