share/man/man9/CPUMASK.9

   1 .\"
   2 .\" Copyright (c) 2016 The DragonFly Project.
   3 .\" All rights reserved.
   4 .\"
   5 .\" 1. Redistributions of source code must retain the above copyright
   6 .\"    notice, this list of conditions and the following disclaimer.
   7 .\" 2. Redistributions in binary form must reproduce the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer in
   9 .\"    the documentation and/or other materials provided with the
  10 .\"    distribution.
  11 .\" 3. Neither the name of The DragonFly Project nor the names of its
  12 .\"    contributors may be used to endorse or promote products derived
  13 .\"    from this software without specific, prior written permission.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\"
  28 .Dd July 24, 2016
  29 .Dt CPUMASK 9
  30 .Os
  31 .Sh NAME
  32 .Nm CPUMASK ,
  33 .Nm ATOMIC_CPUMASK_COPY ,
  34 .Nm ATOMIC_CPUMASK_NANDBIT ,
  35 .Nm ATOMIC_CPUMASK_NANDMASK ,
  36 .Nm ATOMIC_CPUMASK_ORBIT ,
  37 .Nm ATOMIC_CPUMASK_ORMASK ,
  38 .Nm ATOMIC_CPUMASK_TESTANDCLR ,
  39 .Nm ATOMIC_CPUMASK_TESTANDSET ,
  40 .Nm BSFCPUMASK ,
  41 .Nm BSRCPUMASK ,
  42 .Nm CPUMASK_ADDR ,
  43 .Nm CPUMASK_ANDBIT ,
  44 .Nm CPUMASK_ANDMASK ,
  45 .Nm CPUMASK_ASSALLONES ,
  46 .Nm CPUMASK_ASSBIT ,
  47 .Nm CPUMASK_ASSBMASK ,
  48 .Nm CPUMASK_ASSNBMASK ,
  49 .Nm CPUMASK_ASSZERO ,
  50 .Nm CPUMASK_CMPMASKEQ ,
  51 .Nm CPUMASK_CMPMASKNEQ ,
  52 .Nm CPUMASK_ISUP ,
  53 .Nm CPUMASK_LOWMASK ,
  54 .Nm CPUMASK_NANDBIT ,
  55 .Nm CPUMASK_NANDMASK ,
  56 .Nm CPUMASK_ORBIT ,
  57 .Nm CPUMASK_ORMASK ,
  58 .Nm CPUMASK_SIMPLE ,
  59 .Nm CPUMASK_TESTBIT ,
  60 .Nm CPUMASK_TESTMASK ,
  61 .Nm CPUMASK_TESTNZERO ,
  62 .Nm CPUMASK_TESTZERO ,
  63 .Nm CPUMASK_XORMASK
  64 .Nd Macros to manipulate cpumask_t fields
  65 .Sh SYNOPSIS
  66 .In machine/cpumask.h
  67 .Fo ATOMIC_CPUMASK_COPY
  68 .Fa "mask"
  69 .Fa "val"
  70 .Fc
  71 .Fo ATOMIC_CPUMASK_NANDBIT
  72 .Fa "mask"
  73 .Fa "i"
  74 .Fc
  75 .Fo ATOMIC_CPUMASK_NANDMASK
  76 .Fa "mask"
  77 .Fa "val"
  78 .Fc
  79 .Fo ATOMIC_CPUMASK_ORBIT
  80 .Fa "mask"
  81 .Fa "i"
  82 .Fc
  83 .Fo ATOMIC_CPUMASK_ORMASK
  84 .Fa "mask"
  85 .Fa "val"
  86 .Fc
  87 .Fo ATOMIC_CPUMASK_TESTANDCLR
  88 .Fa "mask"
  89 .Fa "i"
  90 .Fc
  91 .Fo ATOMIC_CPUMASK_TESTANDSET
  92 .Fa "mask"
  93 .Fa "i"
  94 .Fc
  95 .Fo BSFCPUMASK
  96 .Fa "val"
  97 .Fc
  98 .Fo BSRCPUMASK
  99 .Fa "val"
 100 .Fc
 101 .Fo CPUMASK_ADDR
 102 .Fa "mask"
 103 .Fa "cpu"
 104 .Fc
 105 .Fo CPUMASK_ANDBIT
 106 .Fa "mask"
 107 .Fa "i"
 108 .Fc
 109 .Fo CPUMASK_ANDMASK
 110 .Fa "mask"
 111 .Fa "val"
 112 .Fc
 113 .Fo CPUMASK_ASSALLONES
 114 .Fa "mask"
 115 .Fc
 116 .Fo CPUMASK_ASSBIT
 117 .Fa "mask"
 118 .Fa "i"
 119 .Fc
 120 .Fo CPUMASK_ASSBMASK
 121 .Fa "mask"
 122 .Fa "i"
 123 .Fc
 124 .Fo CPUMASK_ASSNBMASK
 125 .Fa "mask"
 126 .Fa "i"
 127 .Fc
 128 .Fo CPUMASK_ASSZERO
 129 .Fa "mask"
 130 .Fc
 131 .Fo CPUMASK_CMPMASKEQ
 132 .Fa "mask1"
 133 .Fa "mask2"
 134 .Fc
 135 .Fo CPUMASK_CMPMASKNEQ
 136 .Fa "mask1"
 137 .Fa "mask2"
 138 .Fc
 139 .Fo CPUMASK_ISUP
 140 .Fa "val"
 141 .Fc
 142 .Fo CPUMASK_LOWMASK
 143 .Fa "val"
 144 .Fc
 145 .Fo CPUMASK_NANDBIT
 146 .Fa "mask"
 147 .Fa "i"
 148 .Fc
 149 .Fo CPUMASK_NANDMASK
 150 .Fa "mask"
 151 .Fa "val"
 152 .Fc
 153 .Fo CPUMASK_ORBIT
 154 .Fa "mask"
 155 .Fa "i"
 156 .Fc
 157 .Fo CPUMASK_ORMASK
 158 .Fa "mask"
 159 .Fa "val"
 160 .Fc
 161 .Fo CPUMASK_SIMPLE
 162 .Fa "cpu"
 163 .Fc
 164 .Fo CPUMASK_TESTBIT
 165 .Fa "val"
 166 .Fa "i"
 167 .Fc
 168 .Fo CPUMASK_TESTMASK
 169 .Fa "mask1"
 170 .Fa "mask2"
 171 .Fc
 172 .Fo CPUMASK_TESTNZERO
 173 .Fa "val"
 174 .Fc
 175 .Fo CPUMASK_TESTZERO
 176 .Fa "val"
 177 .Fc
 178 .Fo CPUMASK_XORMASK
 179 .Fa "mask"
 180 .Fa "val"
 181 .Fc
 182 .Sh DESCRIPTION
 183 The
 184 .Nm
 185 macros allow to safely manipulate the non standard type CPU bitmasks that uses
 186 .Dv CPUMASK_ELEMENTS
 187 of 64-bit words in
 188 .Vt cpumask_t
 189 type.
 190 .Pp
 191 Declared CPU mask variables can be initialized using one of
 192 .Dv CPUMASK_INITIALIZER_ALLONES ,
 193 .Dv CPUMASK_INITIALIZER_ONLYONE
 194 macros.
 195 .Pp
 196 The
 197 .Nm BSFCPUMASK
 198 performs a "bit scan forward" assembler instruction over whole
 199 .Vt cpumask_t
 200 type, while the
 201 .Nm BSRCPUMASK
 202 performs a "bit scan reverse".
 203 .Pp
 204 Keep in mind that macros like
 205 .Nm CPUMASK_SIMPLE
 206 might only work in 64-bit mask range as they are provided as a convenience to
 207 build more sophisticated macros.
 208 .Pp
 209 The
 210 .Nm
 211 macros with ATOMIC prefix perform
 212 .Xr atomic 9
 213 operations on the given CPU mask.
 214 .Pp
 215 When adding, modifying or removing CPUMASK macros, it is important to be
 216 aware that these interfaces may be used by libraries, applications,
 217 users or documentation.
 218 Changing the
 219 .Vt cpumask_t
 220 length defined by
 221 .Dv CPUMASK_ELEMENTS
 222 requires adjustment of both
 223 .Nm
 224 macros and kernel assembly sources because
 225 .Nm
 226 are implemented as non variably-sized macros.