share/man/man9/cpuset.9

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