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