lib/libc/sys/cpuset.2

   1 .\" Copyright (c) 2008 Christian Brueffer
   2 .\" Copyright (c) 2008 Jeffrey Roberson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd May 3, 2017
  29 .Dt CPUSET 2
  30 .Os
  31 .Sh NAME
  32 .Nm cpuset ,
  33 .Nm cpuset_getid ,
  34 .Nm cpuset_setid
  35 .Nd manage CPU affinity sets
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .In sys/cpuset.h
  41 .Ft int
  42 .Fn cpuset "cpusetid_t *setid"
  43 .Ft int
  44 .Fn cpuset_setid "cpuwhich_t which" "id_t id" "cpusetid_t setid"
  45 .Ft int
  46 .Fn cpuset_getid "cpulevel_t level" "cpuwhich_t which" "id_t id" "cpusetid_t *setid"
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 family of system calls allow applications to control sets of processors and
  51 assign processes and threads to these sets.
  52 Processor sets contain lists of CPUs that members may run on and exist only
  53 as long as some process is a member of the set.
  54 All processes in the system have an assigned set.
  55 The default set for all processes in the system is the set numbered 1.
  56 Threads belong to the same set as the process which contains them,
  57 however, they may further restrict their set with the anonymous
  58 per-thread mask.
  59 .Pp
  60 Sets are referenced by a number of type
  61 .Ft cpuset_id_t .
  62 Each thread has a root set, an assigned set, and an anonymous mask.
  63 Only the root and assigned sets are numbered.
  64 The root set is the set of all CPUs available in the system or in the
  65 system partition the thread is running in.
  66 The assigned set is a subset of the root set and is administratively
  67 assignable on a per-process basis.
  68 Many processes and threads may be members of a numbered set.
  69 .Pp
  70 The anonymous set is a further thread-specific refinement on the assigned
  71 set.
  72 It is intended that administrators will manipulate numbered sets using
  73 .Xr cpuset 1
  74 while application developers will manipulate anonymous sets using
  75 .Xr cpuset_setaffinity 2 .
  76 .Pp
  77 To select the correct set a value of type
  78 .Ft cpulevel_t
  79 is used.
  80 The following values for
  81 .Fa level
  82 are supported:
  83 .Bl -column CPU_LEVEL_CPUSET -offset indent
  84 .It Dv CPU_LEVEL_ROOT Ta "Root set"
  85 .It Dv CPU_LEVEL_CPUSET Ta "Assigned set"
  86 .It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument"
  87 .El
  88 .Pp
  89 The
  90 .Fa which
  91 argument determines how the value of
  92 .Fa id
  93 is interpreted and is of type
  94 .Ft cpuwhich_t .
  95 The
  96 .Fa which
  97 argument may have the following values:
  98 .Bl -column CPU_WHICH_CPUSET -offset indent
  99 .It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)"
 100 .It Dv CPU_WHICH_PID Ta "id is pid_t (process id)"
 101 .It Dv CPU_WHICH_JAIL Ta "id is jid (jail id)"
 102 .It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)"
 103 .It Dv CPU_WHICH_IRQ Ta "id is an irq number"
 104 .It Dv CPU_WHICH_INTRHANDLER Ta "id is an irq number for an interrupt handler"
 105 .It Dv CPU_WHICH_ITHREAD Ta "id is an irq number for an ithread"
 106 .It Dv CPU_WHICH_DOMAIN Ta "id is a NUMA domain"
 107 .El
 108 .Pp
 109 An
 110 .Fa id
 111 of '-1' may be used with a
 112 .Fa which
 113 of
 114 .Dv CPU_WHICH_TID ,
 115 .Dv CPU_WHICH_PID ,
 116 or
 117 .Dv CPU_WHICH_CPUSET
 118 to mean the current thread, process, or current thread's
 119 cpuset.
 120 All cpuset syscalls allow this usage.
 121 .Pp
 122 A
 123 .Fa level
 124 argument of
 125 .Dv CPU_LEVEL_WHICH
 126 combined with a
 127 .Fa which
 128 argument other than
 129 .Dv CPU_WHICH_CPUSET
 130 refers to the anonymous mask of the object.
 131 This mask does not have an id and may only be manipulated with
 132 .Xr cpuset_setaffinity 2 .
 133 .Pp
 134 .Fn cpuset
 135 creates a new set containing the same CPUs as the root set of the current
 136 process and stores its id in the space provided by
 137 .Fa setid .
 138 On successful completion the calling process joins the set and is the
 139 only member.
 140 Children inherit this set after a call to
 141 .Xr fork 2 .
 142 .Pp
 143 .Fn cpuset_setid
 144 attempts to set the id of the object specified by the
 145 .Fa which
 146 argument.
 147 Currently
 148 .Dv CPU_WHICH_PID
 149 is the only acceptable value for which as
 150 threads do not have an id distinct from their process and the API does
 151 not permit changing the id of an existing set.
 152 Upon successful completion all of the threads in the target process will
 153 be running on CPUs permitted by the set.
 154 .Pp
 155 .Fn cpuset_getid
 156 retrieves a set id from the object indicated by
 157 .Fa which
 158 and stores it in the space pointed to by
 159 .Fa setid .
 160 The retrieved id may be that of either the root or assigned set
 161 depending on the value of
 162 .Fa level .
 163 .Fa level
 164 should be
 165 .Dv CPU_LEVEL_CPUSET
 166 or
 167 .Dv CPU_LEVEL_ROOT
 168 to get the set id from
 169 the process or thread specified by the
 170 .Fa id
 171 argument.
 172 Specifying
 173 .Dv CPU_LEVEL_WHICH
 174 with a process or thread is unsupported since
 175 this references the unnumbered anonymous mask.
 176 .Pp
 177 The actual contents of the sets may be retrieved or manipulated using
 178 .Xr cpuset_getaffinity 2
 179 and
 180 .Xr cpuset_setaffinity 2 .
 181 See those manual pages for more detail.
 182 .Sh RETURN VALUES
 183 .Rv -std
 184 .Sh ERRORS
 185 The following error codes may be set in
 186 .Va errno :
 187 .Bl -tag -width Er
 188 .It Bq Er EINVAL
 189 The
 190 .Fa which
 191 or
 192 .Fa level
 193 argument was not a valid value.
 194 .It Bq Er EDEADLK
 195 The
 196 .Fn cpuset_setid
 197 call would leave a thread without a valid CPU to run on because the set
 198 does not overlap with the thread's anonymous mask.
 199 .It Bq Er EFAULT
 200 The setid pointer passed to
 201 .Fn cpuset_getid
 202 or
 203 .Fn cpuset
 204 was invalid.
 205 .It Bq Er ESRCH
 206 The object specified by the
 207 .Fa id
 208 and
 209 .Fa which
 210 arguments could not be found.
 211 .It Bq Er EPERM
 212 The calling process did not have the credentials required to complete the
 213 operation.
 214 .It Bq Er ENFILE
 215 There was no free
 216 .Ft cpusetid_t
 217 for allocation.
 218 .El
 219 .Sh SEE ALSO
 220 .Xr cpuset 1 ,
 221 .Xr cpuset_getaffinity 2 ,
 222 .Xr cpuset_setaffinity 2 ,
 223 .Xr pthread_affinity_np 3 ,
 224 .Xr pthread_attr_affinity_np 3 ,
 225 .Xr cpuset 9
 226 .Sh HISTORY
 227 The
 228 .Nm
 229 family of system calls first appeared in
 230 .Fx 7.1 .
 231 .Sh AUTHORS
 232 .An Jeffrey Roberson Aq Mt jeff@FreeBSD.org