]>
Commit | Line | Data |
---|---|---|
0de5014f MK |
1 | .\" Copyright (c) 2008 Silicon Graphics, Inc. |
2 | .\" | |
3 | .\" Author: Paul Jackson (http://oss.sgi.com/projects/cpusets) | |
4 | .\" | |
ef06249a | 5 | .\" %%%LICENSE_START(GPLv2_MISC) |
0de5014f MK |
6 | .\" This is free documentation; you can redistribute it and/or |
7 | .\" modify it under the terms of the GNU General Public License | |
8 | .\" version 2 as published by the Free Software Foundation. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
21 | .\" License along with this manual; if not, see |
22 | .\" <http://www.gnu.org/licenses/>. | |
8ff7380d | 23 | .\" %%%LICENSE_END |
0de5014f | 24 | .\" |
9f496381 | 25 | .TH CPUSET 7 2016-05-09 "Linux" "Linux Programmer's Manual" |
0de5014f MK |
26 | .SH NAME |
27 | cpuset \- confine processes to processor and memory node subsets | |
28 | .SH DESCRIPTION | |
9ee4a2b6 | 29 | The cpuset filesystem is a pseudo-filesystem interface |
0de5014f MK |
30 | to the kernel cpuset mechanism, |
31 | which is used to control the processor placement | |
32 | and memory placement of processes. | |
33 | It is commonly mounted at | |
34 | .IR /dev/cpuset . | |
35 | .PP | |
36 | On systems with kernels compiled with built in support for cpusets, | |
37 | all processes are attached to a cpuset, and cpusets are always present. | |
38 | If a system supports cpusets, then it will have the entry | |
39 | .B nodev cpuset | |
40 | in the file | |
41 | .IR /proc/filesystems . | |
9ee4a2b6 | 42 | By mounting the cpuset filesystem (see the |
0de5014f MK |
43 | .B EXAMPLE |
44 | section below), | |
45 | the administrator can configure the cpusets on a system | |
46 | to control the processor and memory placement of processes | |
47 | on that system. | |
48 | By default, if the cpuset configuration | |
28955f15 SP |
49 | on a system is not modified or if the cpuset filesystem |
50 | is not even mounted, then the cpuset mechanism, | |
41185b12 | 51 | though present, has no effect on the system's behavior. |
0de5014f MK |
52 | .PP |
53 | A cpuset defines a list of CPUs and memory nodes. | |
54 | .PP | |
55 | The CPUs of a system include all the logical processing | |
56 | units on which a process can execute, including, if present, | |
57 | multiple processor cores within a package and Hyper-Threads | |
58 | within a processor core. | |
59 | Memory nodes include all distinct | |
60 | banks of main memory; small and SMP systems typically have | |
61 | just one memory node that contains all the system's main memory, | |
62 | while NUMA (non-uniform memory access) systems have multiple memory nodes. | |
63 | .PP | |
64 | Cpusets are represented as directories in a hierarchical | |
9ee4a2b6 | 65 | pseudo-filesystem, where the top directory in the hierarchy |
0de5014f MK |
66 | .RI ( /dev/cpuset ) |
67 | represents the entire system (all online CPUs and memory nodes) | |
68 | and any cpuset that is the child (descendant) of | |
69 | another parent cpuset contains a subset of that parent's | |
70 | CPUs and memory nodes. | |
71 | The directories and files representing cpusets have normal | |
9ee4a2b6 | 72 | filesystem permissions. |
0de5014f MK |
73 | .PP |
74 | Every process in the system belongs to exactly one cpuset. | |
33a0ccb2 | 75 | A process is confined to run only on the CPUs in |
0de5014f MK |
76 | the cpuset it belongs to, and to allocate memory only |
77 | on the memory nodes in that cpuset. | |
78 | When a process | |
79 | .BR fork (2)s, | |
80 | the child process is placed in the same cpuset as its parent. | |
81 | With sufficient privilege, a process may be moved from one | |
82 | cpuset to another and the allowed CPUs and memory nodes | |
83 | of an existing cpuset may be changed. | |
84 | .PP | |
85 | When the system begins booting, a single cpuset is | |
86 | defined that includes all CPUs and memory nodes on the | |
87 | system, and all processes are in that cpuset. | |
88 | During the boot process, or later during normal system operation, | |
89 | other cpusets may be created, as subdirectories of this top cpuset, | |
90 | under the control of the system administrator, | |
91 | and processes may be placed in these other cpusets. | |
92 | .PP | |
93 | Cpusets are integrated with the | |
94 | .BR sched_setaffinity (2) | |
95 | scheduling affinity mechanism and the | |
96 | .BR mbind (2) | |
97 | and | |
98 | .BR set_mempolicy (2) | |
99 | memory-placement mechanisms in the kernel. | |
100 | Neither of these mechanisms let a process make use | |
101 | of a CPU or memory node that is not allowed by that process's cpuset. | |
102 | If changes to a process's cpuset placement conflict with these | |
103 | other mechanisms, then cpuset placement is enforced | |
104 | even if it means overriding these other mechanisms. | |
105 | The kernel accomplishes this overriding by silently | |
106 | restricting the CPUs and memory nodes requested by | |
107 | these other mechanisms to those allowed by the | |
108 | invoking process's cpuset. | |
109 | This can result in these | |
110 | other calls returning an error, if for example, such | |
111 | a call ends up requesting an empty set of CPUs or | |
112 | memory nodes, after that request is restricted to | |
113 | the invoking process's cpuset. | |
114 | .PP | |
115 | Typically, a cpuset is used to manage | |
116 | the CPU and memory-node confinement for a set of | |
117 | cooperating processes such as a batch scheduler job, and these | |
118 | other mechanisms are used to manage the placement of | |
119 | individual processes or memory regions within that set or job. | |
120 | .SH FILES | |
121 | Each directory below | |
122 | .I /dev/cpuset | |
123 | represents a cpuset and contains a fixed set of pseudo-files | |
124 | describing the state of that cpuset. | |
125 | .PP | |
126 | New cpusets are created using the | |
127 | .BR mkdir (2) | |
128 | system call or the | |
129 | .BR mkdir (1) | |
130 | command. | |
131 | The properties of a cpuset, such as its flags, allowed | |
132 | CPUs and memory nodes, and attached processes, are queried and modified | |
133 | by reading or writing to the appropriate file in that cpuset's directory, | |
134 | as listed below. | |
135 | .PP | |
136 | The pseudo-files in each cpuset directory are automatically created when | |
137 | the cpuset is created, as a result of the | |
138 | .BR mkdir (2) | |
139 | invocation. | |
140 | It is not possible to directly add or remove these pseudo-files. | |
141 | .PP | |
142 | A cpuset directory that contains no child cpuset directories, | |
143 | and has no attached processes, can be removed using | |
144 | .BR rmdir (2) | |
145 | or | |
146 | .BR rmdir (1). | |
147 | It is not necessary, or possible, | |
148 | to remove the pseudo-files inside the directory before removing it. | |
149 | .PP | |
150 | The pseudo-files in each cpuset directory are | |
151 | small text files that may be read and | |
152 | written using traditional shell utilities such as | |
153 | .BR cat (1), | |
154 | and | |
155 | .BR echo (1), | |
156 | or from a program by using file I/O library functions or system calls, | |
157 | such as | |
158 | .BR open (2), | |
159 | .BR read (2), | |
160 | .BR write (2), | |
161 | and | |
162 | .BR close (2). | |
163 | .PP | |
164 | The pseudo-files in a cpuset directory represent internal kernel | |
165 | state and do not have any persistent image on disk. | |
166 | Each of these per-cpuset files is listed and described below. | |
167 | .\" ====================== tasks ====================== | |
168 | .TP | |
169 | .I tasks | |
170 | List of the process IDs (PIDs) of the processes in that cpuset. | |
171 | The list is formatted as a series of ASCII | |
172 | decimal numbers, each followed by a newline. | |
173 | A process may be added to a cpuset (automatically removing | |
174 | it from the cpuset that previously contained it) by writing its | |
175 | PID to that cpuset's | |
176 | .I tasks | |
de396db5 | 177 | file (with or without a trailing newline). |
0de5014f MK |
178 | |
179 | .B Warning: | |
180 | only one PID may be written to the | |
181 | .I tasks | |
182 | file at a time. | |
183 | If a string is written that contains more | |
184 | than one PID, only the first one will be used. | |
185 | .\" =================== notify_on_release =================== | |
186 | .TP | |
187 | .I notify_on_release | |
188 | Flag (0 or 1). | |
189 | If set (1), that cpuset will receive special handling | |
190 | after it is released, that is, after all processes cease using | |
191 | it (i.e., terminate or are moved to a different cpuset) | |
192 | and all child cpuset directories have been removed. | |
193 | See the \fBNotify On Release\fR section, below. | |
194 | .\" ====================== cpus ====================== | |
195 | .TP | |
0a61a4f4 | 196 | .I cpuset.cpus |
0de5014f MK |
197 | List of the physical numbers of the CPUs on which processes |
198 | in that cpuset are allowed to execute. | |
199 | See \fBList Format\fR below for a description of the | |
200 | format of | |
201 | .IR cpus . | |
202 | ||
203 | The CPUs allowed to a cpuset may be changed by | |
204 | writing a new list to its | |
205 | .I cpus | |
206 | file. | |
207 | .\" ==================== cpu_exclusive ==================== | |
208 | .TP | |
0a61a4f4 | 209 | .I cpuset.cpu_exclusive |
0de5014f MK |
210 | Flag (0 or 1). |
211 | If set (1), the cpuset has exclusive use of | |
212 | its CPUs (no sibling or cousin cpuset may overlap CPUs). | |
238a751e | 213 | By default, this is off (0). |
0de5014f MK |
214 | Newly created cpusets also initially default this to off (0). |
215 | ||
216 | Two cpusets are | |
217 | .I sibling | |
218 | cpusets if they share the same parent cpuset in the | |
219 | .I /dev/cpuset | |
220 | hierarchy. | |
221 | Two cpusets are | |
222 | .I cousin | |
223 | cpusets if neither is the ancestor of the other. | |
224 | Regardless of the | |
225 | .I cpu_exclusive | |
226 | setting, if one cpuset is the ancestor of another, | |
aa796481 | 227 | and if both of these cpusets have nonempty |
0de5014f MK |
228 | .IR cpus , |
229 | then their | |
230 | .I cpus | |
231 | must overlap, because the | |
232 | .I cpus | |
233 | of any cpuset are always a subset of the | |
234 | .I cpus | |
235 | of its parent cpuset. | |
236 | .\" ====================== mems ====================== | |
237 | .TP | |
0a61a4f4 | 238 | .I cpuset.mems |
0de5014f MK |
239 | List of memory nodes on which processes in this cpuset are |
240 | allowed to allocate memory. | |
241 | See \fBList Format\fR below for a description of the | |
242 | format of | |
243 | .IR mems . | |
244 | .\" ==================== mem_exclusive ==================== | |
245 | .TP | |
0a61a4f4 | 246 | .I cpuset.mem_exclusive |
0de5014f MK |
247 | Flag (0 or 1). |
248 | If set (1), the cpuset has exclusive use of | |
249 | its memory nodes (no sibling or cousin may overlap). | |
76eac093 | 250 | Also if set (1), the cpuset is a \fBHardwall\fR cpuset (see below). |
238a751e | 251 | By default, this is off (0). |
0de5014f MK |
252 | Newly created cpusets also initially default this to off (0). |
253 | ||
254 | Regardless of the | |
255 | .I mem_exclusive | |
256 | setting, if one cpuset is the ancestor of another, | |
257 | then their memory nodes must overlap, because the memory | |