blob: d17b7d2dd771e6c0eeeda4b93c372840209f014d [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001 CPUSETS
2 -------
3
4Copyright (C) 2004 BULL SA.
5Written by Simon.Derr@bull.net
6
7Portions Copyright (c) 2004 Silicon Graphics, Inc.
8Modified by Paul Jackson <pj@sgi.com>
9
10CONTENTS:
11=========
12
131. Cpusets
14 1.1 What are cpusets ?
15 1.2 Why are cpusets needed ?
16 1.3 How are cpusets implemented ?
17 1.4 How do I use cpusets ?
182. Usage Examples and Syntax
19 2.1 Basic Usage
20 2.2 Adding/removing cpus
21 2.3 Setting flags
22 2.4 Attaching processes
233. Questions
244. Contact
25
261. Cpusets
27==========
28
291.1 What are cpusets ?
30----------------------
31
32Cpusets provide a mechanism for assigning a set of CPUs and Memory
33Nodes to a set of tasks.
34
35Cpusets constrain the CPU and Memory placement of tasks to only
36the resources within a tasks current cpuset. They form a nested
37hierarchy visible in a virtual file system. These are the essential
38hooks, beyond what is already present, required to manage dynamic
39job placement on large systems.
40
41Each task has a pointer to a cpuset. Multiple tasks may reference
42the same cpuset. Requests by a task, using the sched_setaffinity(2)
43system call to include CPUs in its CPU affinity mask, and using the
44mbind(2) and set_mempolicy(2) system calls to include Memory Nodes
45in its memory policy, are both filtered through that tasks cpuset,
46filtering out any CPUs or Memory Nodes not in that cpuset. The
47scheduler will not schedule a task on a CPU that is not allowed in
48its cpus_allowed vector, and the kernel page allocator will not
49allocate a page on a node that is not allowed in the requesting tasks
50mems_allowed vector.
51
52If a cpuset is cpu or mem exclusive, no other cpuset, other than a direct
53ancestor or descendent, may share any of the same CPUs or Memory Nodes.
Dinakar Guniguntala85d7b942005-06-25 14:57:34 -070054A cpuset that is cpu exclusive has a sched domain associated with it.
55The sched domain consists of all cpus in the current cpuset that are not
56part of any exclusive child cpusets.
57This ensures that the scheduler load balacing code only balances
58against the cpus that are in the sched domain as defined above and not
59all of the cpus in the system. This removes any overhead due to
60load balancing code trying to pull tasks outside of the cpu exclusive
61cpuset only to be prevented by the tasks' cpus_allowed mask.
Linus Torvalds1da177e2005-04-16 15:20:36 -070062
Paul Jackson9bf22292005-09-06 15:18:12 -070063A cpuset that is mem_exclusive restricts kernel allocations for
64page, buffer and other data commonly shared by the kernel across
65multiple users. All cpusets, whether mem_exclusive or not, restrict
66allocations of memory for user space. This enables configuring a
67system so that several independent jobs can share common kernel
68data, such as file system pages, while isolating each jobs user
69allocation in its own cpuset. To do this, construct a large
70mem_exclusive cpuset to hold all the jobs, and construct child,
71non-mem_exclusive cpusets for each individual job. Only a small
72amount of typical kernel memory, such as requests from interrupt
73handlers, is allowed to be taken outside even a mem_exclusive cpuset.
74
Linus Torvalds1da177e2005-04-16 15:20:36 -070075User level code may create and destroy cpusets by name in the cpuset
76virtual file system, manage the attributes and permissions of these
77cpusets and which CPUs and Memory Nodes are assigned to each cpuset,
78specify and query to which cpuset a task is assigned, and list the
79task pids assigned to a cpuset.
80
81
821.2 Why are cpusets needed ?
83----------------------------
84
85The management of large computer systems, with many processors (CPUs),
86complex memory cache hierarchies and multiple Memory Nodes having
87non-uniform access times (NUMA) presents additional challenges for
88the efficient scheduling and memory placement of processes.
89
90Frequently more modest sized systems can be operated with adequate
91efficiency just by letting the operating system automatically share
92the available CPU and Memory resources amongst the requesting tasks.
93
94But larger systems, which benefit more from careful processor and
95memory placement to reduce memory access times and contention,
96and which typically represent a larger investment for the customer,
97can benefit from explictly placing jobs on properly sized subsets of
98the system.
99
100This can be especially valuable on:
101
102 * Web Servers running multiple instances of the same web application,
103 * Servers running different applications (for instance, a web server
104 and a database), or
105 * NUMA systems running large HPC applications with demanding
106 performance characteristics.
Dinakar Guniguntala85d7b942005-06-25 14:57:34 -0700107 * Also cpu_exclusive cpusets are useful for servers running orthogonal
108 workloads such as RT applications requiring low latency and HPC
109 applications that are throughput sensitive
Linus Torvalds1da177e2005-04-16 15:20:36 -0700110
111These subsets, or "soft partitions" must be able to be dynamically
112adjusted, as the job mix changes, without impacting other concurrently
113executing jobs.
114
115The kernel cpuset patch provides the minimum essential kernel
116mechanisms required to efficiently implement such subsets. It
117leverages existing CPU and Memory Placement facilities in the Linux
118kernel to avoid any additional impact on the critical scheduler or
119memory allocator code.
120
121
1221.3 How are cpusets implemented ?
123---------------------------------
124
125Cpusets provide a Linux kernel (2.6.7 and above) mechanism to constrain
126which CPUs and Memory Nodes are used by a process or set of processes.
127
128The Linux kernel already has a pair of mechanisms to specify on which
129CPUs a task may be scheduled (sched_setaffinity) and on which Memory
130Nodes it may obtain memory (mbind, set_mempolicy).
131
132Cpusets extends these two mechanisms as follows:
133
134 - Cpusets are sets of allowed CPUs and Memory Nodes, known to the
135 kernel.
136 - Each task in the system is attached to a cpuset, via a pointer
137 in the task structure to a reference counted cpuset structure.
138 - Calls to sched_setaffinity are filtered to just those CPUs
139 allowed in that tasks cpuset.
140 - Calls to mbind and set_mempolicy are filtered to just
141 those Memory Nodes allowed in that tasks cpuset.
142 - The root cpuset contains all the systems CPUs and Memory
143 Nodes.
144 - For any cpuset, one can define child cpusets containing a subset
145 of the parents CPU and Memory Node resources.
146 - The hierarchy of cpusets can be mounted at /dev/cpuset, for
147 browsing and manipulation from user space.
148 - A cpuset may be marked exclusive, which ensures that no other
149 cpuset (except direct ancestors and descendents) may contain
150 any overlapping CPUs or Memory Nodes.
Dinakar Guniguntala85d7b942005-06-25 14:57:34 -0700151 Also a cpu_exclusive cpuset would be associated with a sched
152 domain.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700153 - You can list all the tasks (by pid) attached to any cpuset.
154
155The implementation of cpusets requires a few, simple hooks
156into the rest of the kernel, none in performance critical paths:
157
158 - in main/init.c, to initialize the root cpuset at system boot.
159 - in fork and exit, to attach and detach a task from its cpuset.
160 - in sched_setaffinity, to mask the requested CPUs by what's
161 allowed in that tasks cpuset.
162 - in sched.c migrate_all_tasks(), to keep migrating tasks within
163 the CPUs allowed by their cpuset, if possible.
Dinakar Guniguntala85d7b942005-06-25 14:57:34 -0700164 - in sched.c, a new API partition_sched_domains for handling
165 sched domain changes associated with cpu_exclusive cpusets
166 and related changes in both sched.c and arch/ia64/kernel/domain.c
Linus Torvalds1da177e2005-04-16 15:20:36 -0700167 - in the mbind and set_mempolicy system calls, to mask the requested
168 Memory Nodes by what's allowed in that tasks cpuset.
169 - in page_alloc, to restrict memory to allowed nodes.
170 - in vmscan.c, to restrict page recovery to the current cpuset.
171
172In addition a new file system, of type "cpuset" may be mounted,
173typically at /dev/cpuset, to enable browsing and modifying the cpusets
174presently known to the kernel. No new system calls are added for
175cpusets - all support for querying and modifying cpusets is via
176this cpuset file system.
177
178Each task under /proc has an added file named 'cpuset', displaying
179the cpuset name, as the path relative to the root of the cpuset file
180system.
181
182The /proc/<pid>/status file for each task has two added lines,
183displaying the tasks cpus_allowed (on which CPUs it may be scheduled)
184and mems_allowed (on which Memory Nodes it may obtain memory),
185in the format seen in the following example:
186
187 Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff
188 Mems_allowed: ffffffff,ffffffff
189
190Each cpuset is represented by a directory in the cpuset file system
191containing the following files describing that cpuset:
192
193 - cpus: list of CPUs in that cpuset
194 - mems: list of Memory Nodes in that cpuset
195 - cpu_exclusive flag: is cpu placement exclusive?
196 - mem_exclusive flag: is memory placement exclusive?
197 - tasks: list of tasks (by pid) attached to that cpuset
198
199New cpusets are created using the mkdir system call or shell
200command. The properties of a cpuset, such as its flags, allowed
201CPUs and Memory Nodes, and attached tasks, are modified by writing
202to the appropriate file in that cpusets directory, as listed above.
203
204The named hierarchical structure of nested cpusets allows partitioning
205a large system into nested, dynamically changeable, "soft-partitions".
206
207The attachment of each task, automatically inherited at fork by any
208children of that task, to a cpuset allows organizing the work load
209on a system into related sets of tasks such that each set is constrained
210to using the CPUs and Memory Nodes of a particular cpuset. A task
211may be re-attached to any other cpuset, if allowed by the permissions
212on the necessary cpuset file system directories.
213
214Such management of a system "in the large" integrates smoothly with
215the detailed placement done on individual tasks and memory regions
216using the sched_setaffinity, mbind and set_mempolicy system calls.
217
218The following rules apply to each cpuset:
219
220 - Its CPUs and Memory Nodes must be a subset of its parents.
221 - It can only be marked exclusive if its parent is.
222 - If its cpu or memory is exclusive, they may not overlap any sibling.
223
224These rules, and the natural hierarchy of cpusets, enable efficient
225enforcement of the exclusive guarantee, without having to scan all
226cpusets every time any of them change to ensure nothing overlaps a
227exclusive cpuset. Also, the use of a Linux virtual file system (vfs)
228to represent the cpuset hierarchy provides for a familiar permission
229and name space for cpusets, with a minimum of additional kernel code.
230
2311.4 How do I use cpusets ?
232--------------------------
233
234In order to minimize the impact of cpusets on critical kernel
235code, such as the scheduler, and due to the fact that the kernel
236does not support one task updating the memory placement of another
237task directly, the impact on a task of changing its cpuset CPU
238or Memory Node placement, or of changing to which cpuset a task
239is attached, is subtle.
240
241If a cpuset has its Memory Nodes modified, then for each task attached
242to that cpuset, the next time that the kernel attempts to allocate
243a page of memory for that task, the kernel will notice the change
244in the tasks cpuset, and update its per-task memory placement to
245remain within the new cpusets memory placement. If the task was using
246mempolicy MPOL_BIND, and the nodes to which it was bound overlap with
247its new cpuset, then the task will continue to use whatever subset
248of MPOL_BIND nodes are still allowed in the new cpuset. If the task
249was using MPOL_BIND and now none of its MPOL_BIND nodes are allowed
250in the new cpuset, then the task will be essentially treated as if it
251was MPOL_BIND bound to the new cpuset (even though its numa placement,
252as queried by get_mempolicy(), doesn't change). If a task is moved
253from one cpuset to another, then the kernel will adjust the tasks
254memory placement, as above, the next time that the kernel attempts
255to allocate a page of memory for that task.
256
257If a cpuset has its CPUs modified, then each task using that
258cpuset does _not_ change its behavior automatically. In order to
259minimize the impact on the critical scheduling code in the kernel,
260tasks will continue to use their prior CPU placement until they
261are rebound to their cpuset, by rewriting their pid to the 'tasks'
262file of their cpuset. If a task had been bound to some subset of its
263cpuset using the sched_setaffinity() call, and if any of that subset
264is still allowed in its new cpuset settings, then the task will be
265restricted to the intersection of the CPUs it was allowed on before,
266and its new cpuset CPU placement. If, on the other hand, there is
267no overlap between a tasks prior placement and its new cpuset CPU
268placement, then the task will be allowed to run on any CPU allowed
269in its new cpuset. If a task is moved from one cpuset to another,
270its CPU placement is updated in the same way as if the tasks pid is
271rewritten to the 'tasks' file of its current cpuset.
272
273In summary, the memory placement of a task whose cpuset is changed is
274updated by the kernel, on the next allocation of a page for that task,
275but the processor placement is not updated, until that tasks pid is
276rewritten to the 'tasks' file of its cpuset. This is done to avoid
277impacting the scheduler code in the kernel with a check for changes
278in a tasks processor placement.
279
Tobias Klauserd533f672005-09-10 00:26:46 -0700280There is an exception to the above. If hotplug functionality is used
Linus Torvalds1da177e2005-04-16 15:20:36 -0700281to remove all the CPUs that are currently assigned to a cpuset,
282then the kernel will automatically update the cpus_allowed of all
Paul Jacksonb39c4fa2005-05-20 13:59:15 -0700283tasks attached to CPUs in that cpuset to allow all CPUs. When memory
Linus Torvalds1da177e2005-04-16 15:20:36 -0700284hotplug functionality for removing Memory Nodes is available, a
285similar exception is expected to apply there as well. In general,
286the kernel prefers to violate cpuset placement, over starving a task
287that has had all its allowed CPUs or Memory Nodes taken offline. User
288code should reconfigure cpusets to only refer to online CPUs and Memory
289Nodes when using hotplug to add or remove such resources.
290
291There is a second exception to the above. GFP_ATOMIC requests are
292kernel internal allocations that must be satisfied, immediately.
293The kernel may drop some request, in rare cases even panic, if a
294GFP_ATOMIC alloc fails. If the request cannot be satisfied within
295the current tasks cpuset, then we relax the cpuset, and look for
296memory anywhere we can find it. It's better to violate the cpuset
297than stress the kernel.
298
299To start a new job that is to be contained within a cpuset, the steps are:
300
301 1) mkdir /dev/cpuset
302 2) mount -t cpuset none /dev/cpuset
303 3) Create the new cpuset by doing mkdir's and write's (or echo's) in
304 the /dev/cpuset virtual file system.
305 4) Start a task that will be the "founding father" of the new job.
306 5) Attach that task to the new cpuset by writing its pid to the
307 /dev/cpuset tasks file for that cpuset.
308 6) fork, exec or clone the job tasks from this founding father task.
309
310For example, the following sequence of commands will setup a cpuset
311named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
312and then start a subshell 'sh' in that cpuset:
313
314 mount -t cpuset none /dev/cpuset
315 cd /dev/cpuset
316 mkdir Charlie
317 cd Charlie
318 /bin/echo 2-3 > cpus
319 /bin/echo 1 > mems
320 /bin/echo $$ > tasks
321 sh
322 # The subshell 'sh' is now running in cpuset Charlie
323 # The next line should display '/Charlie'
324 cat /proc/self/cpuset
325
326In the case that a change of cpuset includes wanting to move already
327allocated memory pages, consider further the work of IWAMOTO
328Toshihiro <iwamoto@valinux.co.jp> for page remapping and memory
329hotremoval, which can be found at:
330
331 http://people.valinux.co.jp/~iwamoto/mh.html
332
333The integration of cpusets with such memory migration is not yet
334available.
335
336In the future, a C library interface to cpusets will likely be
337available. For now, the only way to query or modify cpusets is
338via the cpuset file system, using the various cd, mkdir, echo, cat,
339rmdir commands from the shell, or their equivalent from C.
340
341The sched_setaffinity calls can also be done at the shell prompt using
342SGI's runon or Robert Love's taskset. The mbind and set_mempolicy
343calls can be done at the shell prompt using the numactl command
344(part of Andi Kleen's numa package).
345
3462. Usage Examples and Syntax
347============================
348
3492.1 Basic Usage
350---------------
351
352Creating, modifying, using the cpusets can be done through the cpuset
353virtual filesystem.
354
355To mount it, type:
356# mount -t cpuset none /dev/cpuset
357
358Then under /dev/cpuset you can find a tree that corresponds to the
359tree of the cpusets in the system. For instance, /dev/cpuset
360is the cpuset that holds the whole system.
361
362If you want to create a new cpuset under /dev/cpuset:
363# cd /dev/cpuset
364# mkdir my_cpuset
365
366Now you want to do something with this cpuset.
367# cd my_cpuset
368
369In this directory you can find several files:
370# ls
371cpus cpu_exclusive mems mem_exclusive tasks
372
373Reading them will give you information about the state of this cpuset:
374the CPUs and Memory Nodes it can use, the processes that are using
375it, its properties. By writing to these files you can manipulate
376the cpuset.
377
378Set some flags:
379# /bin/echo 1 > cpu_exclusive
380
381Add some cpus:
382# /bin/echo 0-7 > cpus
383
384Now attach your shell to this cpuset:
385# /bin/echo $$ > tasks
386
387You can also create cpusets inside your cpuset by using mkdir in this
388directory.
389# mkdir my_sub_cs
390
391To remove a cpuset, just use rmdir:
392# rmdir my_sub_cs
393This will fail if the cpuset is in use (has cpusets inside, or has
394processes attached).
395
3962.2 Adding/removing cpus
397------------------------
398
399This is the syntax to use when writing in the cpus or mems files
400in cpuset directories:
401
402# /bin/echo 1-4 > cpus -> set cpus list to cpus 1,2,3,4
403# /bin/echo 1,2,3,4 > cpus -> set cpus list to cpus 1,2,3,4
404
4052.3 Setting flags
406-----------------
407
408The syntax is very simple:
409
410# /bin/echo 1 > cpu_exclusive -> set flag 'cpu_exclusive'
411# /bin/echo 0 > cpu_exclusive -> unset flag 'cpu_exclusive'
412
4132.4 Attaching processes
414-----------------------
415
416# /bin/echo PID > tasks
417
418Note that it is PID, not PIDs. You can only attach ONE task at a time.
419If you have several tasks to attach, you have to do it one after another:
420
421# /bin/echo PID1 > tasks
422# /bin/echo PID2 > tasks
423 ...
424# /bin/echo PIDn > tasks
425
426
4273. Questions
428============
429
430Q: what's up with this '/bin/echo' ?
431A: bash's builtin 'echo' command does not check calls to write() against
432 errors. If you use it in the cpuset file system, you won't be
433 able to tell whether a command succeeded or failed.
434
435Q: When I attach processes, only the first of the line gets really attached !
436A: We can only return one error code per call to write(). So you should also
437 put only ONE pid.
438
4394. Contact
440==========
441
442Web: http://www.bullopensource.org/cpuset