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