lib/libc/sys/numa_getaffinity.2

   1 .\" Copyright (c) 2008 Christian Brueffer
   2 .\" Copyright (c) 2008 Jeffrey Roberson
   3 .\" Copyright (c) 2015 Adrian Chadd
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  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 .\" $FreeBSD$
  28 .\"
  29 .Dd May 7, 2015
  30 .Dt NUMA_GETAFFINITY 2
  31 .Os
  32 .Sh NAME
  33 .Nm numa_getaffinity ,
  34 .Nm numa_setaffinity
  35 .Nd manage NUMA affinity
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .In sys/numa.h
  41 .Ft int
  42 .Fn numa_getaffinity "cpuwhich_t which" "id_t id" "struct vm_domain_policy_entry *policy"
  43 .Ft int
  44 .Fn numa_setaffinity "cpuwhich_t which" "id_t id" "const struct vm_domain_policy_entry *policy"
  45 .Sh DESCRIPTION
  46 .Fn numa_getaffinity
  47 and
  48 .Fn numa_setaffinity
  49 allow the manipulation of NUMA policies available to processes and threads.
  50 These functions may manipulate NUMA policies that contain many processes
  51 or affect only a single object.
  52 .Pp
  53 Valid values for the
  54 .Fa which
  55 argument are documented in
  56 .Xr cpuset 2 .
  57 These arguments specify which object set are used.
  58 Only
  59 .Dv CPU_WHICH_TID
  60 and
  61 .Dv CPU_WHICH_PID
  62 can be manipulated.
  63 .Pp
  64 The
  65 .Fa policy
  66 entry contains a vm_domain_policy_entry with the following fields:
  67 .Bd -literal
  68 struct vm_domain_policy_entry {
  69     vm_domain_policy_type_t policy;   /* VM policy */
  70     int domain;   /* VM domain, if applicable */
  71 }
  72 .Ed
  73 .Fa vm_domain_policy_type_t policy
  74 is one these:
  75 .Bl -tag -width VM_POLICY_NONE
  76 .It Dv VM_POLICY_NONE
  77 Reset the domain back to none.
  78 Any parent object NUMA domain policy will apply.
  79 The only valid value for
  80 .Dv domain
  81 is -1.
  82 .It Dv VM_POLICY_ROUND_ROBIN
  83 Select round-robin policy.
  84 Pages will be allocated round-robin from each VM domain in order.
  85 The only valid value for
  86 .Dv domain
  87 is -1.
  88 .It Dv VM_POLICY_FIXED_DOMAIN
  89 Select fixed-domain only policy.
  90 Pages will be allocated from the given
  91 .Dv domain
  92 which must be set to a valid VM domain.
  93 Pages will not be allocated from another domain if
  94 .Dv domain
  95 is out of free pages.
  96 .It Dv VM_POLICY_FIXED_DOMAIN_ROUND_ROBIN
  97 Select fixed-domain only policy.
  98 Pages will be allocated from
  99 .Dv domain
 100 which must be set to a valid VM domain.
 101 If page allocation fails, pages will be round-robin
 102 allocated from another domain if
 103 .Dv domain
 104 is out of free pages.
 105 .It Dv VM_POLICY_FIRST_TOUCH
 106 Select first-touch policy.
 107 Pages will be allocated from the NUMA domain which the thread
 108 is currently scheduled upon.
 109 Pages will not be allocated from another domain if the current domain
 110 is out of free pages.
 111 The only valid value for
 112 .Dv domain
 113 is -1.
 114 .It Dv VM_POLICY_FIRST_TOUCH_ROUND_ROBIN
 115 Select first-touch policy.
 116 Pages will be allocated from the NUMA domain which the thread
 117 is currently scheduled upon.
 118 Pages will be allocated round-robin from another domain if the
 119 current domain is out of free pages.
 120 The only valid value for
 121 .Dv domain
 122 is -1.
 123 .El
 124 .Pp
 125 Note that the VM might assign some pages from other domains.
 126 For example, if an existing page allocation is covered by a superpage
 127 allocation.
 128 .Pp
 129 .Fn numa_getaffinity
 130 retrieves the
 131 NUMA policy from the object specified by
 132 .Fa which
 133 and
 134 .Fa id
 135 and stores it in the space provided by
 136 .Fa policy .
 137 .Pp
 138 .Fn numa_setaffinity
 139 attempts to set the NUMA policy for the object specified by
 140 .Fa which
 141 and
 142 .Fa id
 143 to the policy in
 144 .Fa policy .
 145 .Sh RETURN VALUES
 146 .Rv -std
 147 .Sh ERRORS
 148 .Va errno
 149 can contain these error codes:
 150 .Bl -tag -width Er
 151 .It Bq Er EINVAL
 152 The
 153 .Fa level
 154 or
 155 .Fa which
 156 argument was not a valid value.
 157 .It Bq Er EINVAL
 158 The
 159 .Fa policy
 160 argument specified when calling
 161 .Fn numa_setaffinity
 162 did not contain a valid policy.
 163 .It Bq Er EFAULT
 164 The policy pointer passed was invalid.
 165 .It Bq Er ESRCH
 166 The object specified by the
 167 .Fa id
 168 and
 169 .Fa which
 170 arguments could not be found.
 171 .It Bq Er ERANGE
 172 The
 173 .Fa domain
 174 in the given policy
 175 was out of the range of possible VM domains available.
 176 .It Bq Er EPERM
 177 The calling process did not have the credentials required to complete the
 178 operation.
 179 .El
 180 .Sh SEE ALSO
 181 .Xr cpuset 1 ,
 182 .Xr numactl 1 ,
 183 .Xr cpuset 2 ,
 184 .Xr cpuset_getaffinity 2 ,
 185 .Xr cpuset_getid 2 ,
 186 .Xr cpuset_setaffinity 2 ,
 187 .Xr cpuset_setid 2 ,
 188 .Xr pthread_affinity_np 3 ,
 189 .Xr pthread_attr_affinity_np 3 ,
 190 .Xr numa 4
 191 .Sh HISTORY
 192 The
 193 .Nm
 194 family of system calls first appeared in
 195 .Fx 11.0 .
 196 .Sh AUTHORS
 197 .An Adrian Chadd Aq Mt adrian@FreeBSD.org