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