1.\" Copyright (c) 2018 Jeffrey Roberson 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'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd June 18, 2020 26.Dt CPUSET_GETDOMAIN 2 27.Os 28.Sh NAME 29.Nm cpuset_getdomain , 30.Nm cpuset_setdomain 31.Nd manage memory domain policy 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In sys/param.h 36.In sys/domainset.h 37.Ft int 38.Fn cpuset_getdomain "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "domainset_t *mask" "int *policy" 39.Ft int 40.Fn cpuset_setdomain "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const domainset_t *mask" "int policy" 41.Sh DESCRIPTION 42.Fn cpuset_getdomain 43and 44.Fn cpuset_setdomain 45allow the manipulation of sets of memory domains and allocation policy available 46to processes, threads, jails and other resources. 47These functions may manipulate sets of memory domains that contain many processes 48or per-object anonymous masks that affect only a single object. 49.Pp 50The valid values for the 51.Fa level 52and 53.Fa which 54arguments are documented in 55.Xr cpuset 2 . 56These arguments specify which object and which set of the object we are 57referring to. 58Not all possible combinations are valid. 59For example, only processes may belong to a numbered set accessed by a 60.Fa level 61argument of 62.Dv CPU_LEVEL_CPUSET . 63All resources, however, have a mask which may be manipulated with 64.Dv CPU_LEVEL_WHICH . 65.Pp 66Masks of type 67.Ft domainset_t 68are composed using the 69.Dv DOMAINSET 70macros. 71The kernel tolerates large sets as long as all domains specified 72in the set exist. 73Sets smaller than the kernel uses generate an error on calls to 74.Fn cpuset_getdomain 75even if the result set would fit within the user supplied set. 76Calls to 77.Fn cpuset_setdomain 78tolerate small sets with no restrictions. 79.Pp 80The supplied mask should have a size of 81.Fa setsize 82bytes. 83This size is usually provided by calling 84.Li sizeof(mask) 85which is ultimately determined by the value of 86.Dv DOMAINSET_SETSIZE 87as defined in 88.In sys/domainset.h . 89.Pp 90.Fn cpuset_getdomain 91retrieves the 92mask and policy from the object specified by 93.Fa level , 94.Fa which 95and 96.Fa id 97and stores it in the space provided by 98.Fa mask 99and 100.Fa policy . 101.Pp 102.Fn cpuset_setdomain 103attempts to set the mask and policy for the object specified by 104.Fa level , 105.Fa which 106and 107.Fa id 108to the values in 109.Fa mask 110and 111.Fa policy . 112.Sh ALLOCATION POLICIES 113Valid policy values are as follows: 114.Bl -tag -width "foo" 115.It Dv DOMAINSET_POLICY_ROUNDROBIN 116Memory is allocated on a round-robin basis by cycling through each domain in 117.Fa mask . 118.It Dv DOMAINSET_POLICY_FIRSTTOUCH 119Memory is allocated on the domain local to the CPU the requesting thread is 120running on. 121Failure to allocate from this domain will fallback to round-robin. 122.It Dv DOMAINSET_POLICY_PREFER 123Memory is allocated preferentially from the single domain specified in the mask. 124If memory is unavailable the domains listed in the parent cpuset will be 125visited in a round-robin order. 126.El 127.Sh RETURN VALUES 128.Rv -std 129.Sh ERRORS 130The following error codes may be set in 131.Va errno : 132.Bl -tag -width Er 133.\" When changing this list, consider updating share/man/man3/pthread_create.3, 134.\" since that function can return any of these errors. 135.It Bq Er EINVAL 136The 137.Fa level 138or 139.Fa which 140argument was not a valid value. 141.It Bq Er EINVAL 142The 143.Fa mask or 144.Fa policy 145argument specified when calling 146.Fn cpuset_setdomain 147was not a valid value. 148.It Bq Er EDEADLK 149The 150.Fn cpuset_setdomain 151call would leave a thread without a valid CPU to run on because the set 152does not overlap with the thread's anonymous mask. 153.It Bq Er EFAULT 154The mask pointer passed was invalid. 155.It Bq Er ESRCH 156The object specified by the 157.Fa id 158and 159.Fa which 160arguments could not be found. 161.It Bq Er ERANGE 162The 163.Fa domainsetsize 164was either preposterously large or smaller than the kernel set size. 165.It Bq Er EPERM 166The calling process did not have the credentials required to complete the 167operation. 168.It Bq Er ECAPMODE 169The calling process attempted to act on a process other than itself, while 170in capability mode. 171See 172.Xr capsicum 4 . 173.El 174.Sh SEE ALSO 175.Xr cpuset 1 , 176.Xr cpuset 2 , 177.Xr cpuset_getaffinity 2 , 178.Xr cpuset_getid 2 , 179.Xr cpuset_setaffinity 2 , 180.Xr cpuset_setid 2 , 181.Xr capsicum 4 , 182.Xr cpuset 9 183.Sh HISTORY 184The 185.Nm 186family of system calls first appeared in 187.Fx 12.0 . 188.Sh AUTHORS 189.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org 190