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