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 January 8, 2010 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 48The 49.Nm 50family of system calls allow applications to control sets of processors and 51assign processes and threads to these sets. 52Processor sets contain lists of CPUs that members may run on and exist only 53as long as some process is a member of the set. 54All processes in the system have an assigned set. 55The default set for all processes in the system is the set numbered 1. 56Threads belong to the same set as the process which contains them, 57however, they may further restrict their set with the anonymous 58per-thread mask. 59.Pp 60Sets are referenced by a number of type 61.Ft cpuset_id_t . 62Each thread has a root set, an assigned set, and an anonymous mask. 63Only the root and assigned sets are numbered. 64The root set is the set of all CPUs available in the system or in the 65system partition the thread is running in. 66The assigned set is a subset of the root set and is administratively 67assignable on a per-process basis. 68Many processes and threads may be members of a numbered set. 69.Pp 70The anonymous set is a further thread-specific refinement on the assigned 71set. 72It is intended that administrators will manipulate numbered sets using 73.Xr cpuset 1 74while application developers will manipulate anonymous sets using 75.Xr cpuset_setaffinity 2 . 76.Pp 77To select the correct set a value of type 78.Ft cpulevel_t 79is used. 80The following values for 81.Fa level 82are 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 89The 90.Fa which 91argument determines how the value of 92.Fa id 93is interpreted and is of type 94.Ft cpuwhich_t . 95The 96.Fa which 97argument 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_CPUSET Ta "id is a cpusetid_t (cpuset id)" 102.It Dv CPU_WHICH_IRQ Ta "id is an irq number" 103.El 104.Pp 105An 106.Fa id 107of '-1' may be used with a 108.Fa which 109of 110.Dv CPU_WHICH_TID , 111.Dv CPU_WHICH_PID , 112or 113.Dv CPU_WHICH_CPUSET 114to mean the current thread, process, or current thread's 115cpuset. 116All cpuset syscalls allow this usage. 117.Pp 118A 119.Fa level 120argument of 121.Dv CPU_LEVEL_WHICH 122combined with a 123.Fa which 124argument other than 125.Dv CPU_WHICH_CPUSET 126refers to the anonymous mask of the object. 127This mask does not have an id and may only be manipulated with 128.Xr cpuset_setaffinity 2 . 129.Pp 130.Fn cpuset 131creates a new set containing the same CPUs as the root set of the current 132process and stores its id in the space provided by 133.Fa setid . 134On successful completion the calling process joins the set and is the 135only member. 136Children inherit this set after a call to 137.Xr fork 2 . 138.Pp 139.Fn cpuset_setid 140attempts to set the id of the object specified by the 141.Fa which 142argument. 143Currently 144.Dv CPU_WHICH_PID 145is the only acceptable value for which as 146threads do not have an id distinct from their process and the API does 147not permit changing the id of an existing set. 148Upon successful completion all of the threads in the target process will 149be running on CPUs permitted by the set. 150.Pp 151.Fn cpuset_getid 152retrieves a set id from the object indicated by 153.Fa which 154and stores it in the space pointed to by 155.Fa setid . 156The retrieved id may be that of either the root or assigned set 157depending on the value of 158.Fa level . 159.Fa level 160should be 161.Dv CPU_LEVEL_CPUSET 162or 163.Dv CPU_LEVEL_ROOT 164to get the set id from 165the process or thread specified by the 166.Fa id 167argument. 168Specifying 169.Dv CPU_LEVEL_WHICH 170with a process or thread is unsupported since 171this references the unnumbered anonymous mask. 172.Pp 173The actual contents of the sets may be retrieved or manipulated using 174.Xr cpuset_getaffinity 2 175and 176.Xr cpuset_setaffinity 2 . 177See those manual pages for more detail. 178.Sh RETURN VALUES 179.Rv -std 180.Sh ERRORS 181The following error codes may be set in 182.Va errno : 183.Bl -tag -width Er 184.It Bq Er EINVAL 185The 186.Fa which 187or 188.Fa level 189argument was not a valid value. 190.It Bq Er EDEADLK 191The 192.Fn cpuset_setid 193call would leave a thread without a valid CPU to run on because the set 194does not overlap with the thread's anonymous mask. 195.It Bq Er EFAULT 196The setid pointer passed to 197.Fn cpuset_getid 198or 199.Fn cpuset 200was invalid. 201.It Bq Er ESRCH 202The object specified by the 203.Fa id 204and 205.Fa which 206arguments could not be found. 207.It Bq Er EPERM 208The calling process did not have the credentials required to complete the 209operation. 210.It Bq Er ENFILE 211There was no free 212.Ft cpusetid_t 213for allocation. 214.El 215.Sh SEE ALSO 216.Xr cpuset 1 , 217.Xr cpuset_getaffinity 2 , 218.Xr cpuset_setaffinity 2 , 219.Xr pthread_affinity_np 3 , 220.Xr pthread_attr_affinity_np 3 221.Sh HISTORY 222The 223.Nm 224family of system calls first appeared in 225.Fx 7.1 . 226.Sh AUTHOR 227.An Jeffrey Roberson Aq jeff@FreeBSD.org 228