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.Dd July 3, 2018 27.Dt CPUSET 1 28.Os 29.Sh NAME 30.Nm cpuset 31.Nd "configure processor sets" 32.Sh SYNOPSIS 33.Nm 34.Op Fl l Ar cpu-list 35.Op Fl n Ar policy:domain-list 36.Op Fl s Ar setid 37.Ar cmd ... 38.Nm 39.Op Fl l Ar cpu-list 40.Op Fl n Ar policy:domain-list 41.Op Fl s Ar setid 42.Fl p Ar pid 43.Nm 44.Op Fl c 45.Op Fl l Ar cpu-list 46.Op Fl n Ar policy:domain-list 47.Fl C 48.Fl p Ar pid 49.Nm 50.Op Fl c 51.Op Fl l Ar cpu-list 52.Op Fl n Ar policy:domain-list 53.Op Fl j Ar jail | Fl p Ar pid | Fl t Ar tid | Fl s Ar setid | Fl x Ar irq 54.Nm 55.Fl g 56.Op Fl cir 57.Op Fl d Ar domain | Fl j Ar jail | Fl p Ar pid | Fl t Ar tid | Fl s Ar setid | Fl x Ar irq 58.Sh DESCRIPTION 59The 60.Nm 61command can be used to assign processor sets to processes, run commands 62constrained to a given set or list of processors and memory domains, and query 63information about processor binding, memory binding and policy, sets, and 64available processors and memory domains in the system. 65.Pp 66.Nm 67requires a target to modify or query. 68The target may be specified as a command, process id, thread id, a 69cpuset id, an irq, a jail, or a NUMA domain. 70Using 71.Fl g 72the target's set id or mask may be queried. 73Using 74.Fl l 75or 76.Fl s 77the target's CPU mask or set id may be set. 78If no target is specified, 79.Nm 80operates on itself. 81Not all combinations of operations and targets are supported. 82For example, 83you may not set the id of an existing set or query and launch a command 84at the same time. 85.Pp 86There are two sets applicable to each process and one private mask per thread. 87Every process in the system belongs to a cpuset. 88By default processes are started in set 1. 89The mask or id may be queried using 90.Fl c . 91Each thread also has a private mask of CPUs it is allowed to run 92on that must be a subset of the assigned set. 93And finally, there is a root set, numbered 0, that is immutable. 94This last set is the list of all possible CPUs in the system and is 95queried using 96.Fl r . 97.Pp 98Most sets include NUMA memory domain and policy information. 99This can be inspected with 100.Fl g 101and set with 102.Fl n . 103This will specify which NUMA domains are visible to the process and 104affect where anonymous memory and file pages will be stored on first access. 105Files accessed first by other processes may specify conflicting policy. 106.Pp 107When running a command it may join a set specified with 108.Fl s 109otherwise a new set is created. 110In addition, a mask for the command may be specified using 111.Fl l . 112When used in conjunction with 113.Fl c 114the mask modifies the supplied or created set rather than the private mask 115for the thread. 116.Pp 117The options are as follows: 118.Bl -tag -width ".Fl l Ar cpu-list" 119.It Fl C 120Create a new cpuset and assign the target process to that set. 121.It Fl c 122The requested operation should reference the cpuset available via the 123target specifier. 124.It Fl d Ar domain 125Specifies a NUMA domain id as the target of the operation. 126This can only be used to query the cpus visible in each numberd domain. 127.It Fl g 128Causes 129.Nm 130to print either a list of valid CPUs or, using 131.Fl i , 132the id of the target. 133.It Fl i 134When used with the 135.Fl g 136option print the id rather than the valid mask of the target. 137.It Fl j Ar jail 138Specifies a jail id or name as the target of the operation. 139.It Fl l Ar cpu-list 140Specifies a list of CPUs to apply to a target. 141Specification may include 142numbers separated by '-' for ranges and commas separating individual numbers. 143A special list of 144.Dq all 145may be specified in which case the list includes all CPUs from the root set. 146.It Fl n Ar policy:domain-list 147Specifies a list of domains and allocation policy to apply to a target. 148Ranges may be specified as in 149.Fl l . 150Valid policies include first-touch (ft), round-robin (rr), prefer and 151interleave (il). 152First-touch allocates on the local domain when memory is available. 153Round-robin alternates between every possible domain page at a time. 154The prefer policy accepts only a single domain in the set. 155The parent of the set is consulted if the preferred domain is unavailable. 156Interleave operates like round-robin with an implementation defined stripe 157width. 158See 159.Xr domainset 9 160for more details on policies. 161.It Fl p Ar pid 162Specifies a pid as the target of the operation. 163.It Fl s Ar setid 164Specifies a set id as the target of the operation. 165.It Fl r 166The requested operation should reference the root set available via the 167target specifier. 168.It Fl t Ar tid 169Specifies a thread id as the target of the operation. 170.It Fl x Ar irq 171Specifies an irq as the target of the operation. 172.El 173.Sh EXIT STATUS 174.Ex -std 175.Sh EXAMPLES 176Create a new group with CPUs 0-4 inclusive and run 177.Pa /bin/sh 178on it: 179.Dl cpuset -c -l 0-4 /bin/sh 180.Pp 181Query the mask of CPUs the 182.Aq sh pid 183is allowed to run on: 184.Dl cpuset -g -p <sh pid> 185.Pp 186Restrict 187.Pa /bin/sh 188to run on CPUs 0 and 2 while its group is still allowed to run on 189CPUs 0-4: 190.Dl cpuset -l 0,2 -p <sh pid> 191.Pp 192Modify the cpuset 193.Pa /bin/sh 194belongs to restricting it to CPUs 0 and 2: 195.Dl cpuset -l 0,2 -c -p <sh pid> 196.Pp 197Modify the cpuset all threads are in by default to contain only 198the first 4 CPUs, leaving the rest idle: 199.Dl cpuset -l 0-3 -s 1 200.Pp 201Print the id of the cpuset 202.Pa /bin/sh 203is in: 204.Dl cpuset -g -i -p <sh pid> 205.Pp 206Move the 207.Ar pid 208into the specified cpuset 209.Ar setid 210so it may be managed with other pids in that set: 211.Dl cpuset -s <setid> -p <pid> 212.Pp 213Create a new cpuset that is restricted to CPUs 0 and 2 and move 214.Ar pid 215into the new set: 216.Dl cpuset -C -c -l 0,2 -p <pid> 217.Sh SEE ALSO 218.Xr nproc 1 , 219.Xr cpuset 2 , 220.Xr rctl 8 221.Sh HISTORY 222The 223.Nm 224command first appeared in 225.Fx 7.1 . 226.Sh AUTHORS 227.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org 228