[PATCH v4] control groups: documentation improvements

[Glyn Normington]

On 16/04/2014 22:00, Tejun Heo wrote:
> On Wed, Apr 02, 2014 at 02:17:13PM +0100, Glyn Normington wrote:
> > From: Glyn Normington<gnormington@xxxxxxxxxxxxx>
> >
> > Various clarifications to make the control groups documentation
> > easier to understand, especially for newcomers.
> Patch doesn't apply.  Can you please re-generate the patch with 'diff
> -u' and send it as an attachment?
>
> Thanks.
From: Glyn Normington<gnormington@xxxxxxxxxxxxx>

Please see the attachment for the patch created using 'diff -u'. I 
checked it applied ok with:

patch -p1 < ~/patchfile

at the latest HEAD (6ca2a88).

Related LKML thread:

http://lkml.iu.edu//hypermail/linux/kernel/1402.0/02419.html

Signed-off-by: Glyn Normington<gnormington@xxxxxxxxxxxxx>

diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt
index 821de56..f086b70 100644
--- a/Documentation/cgroups/cgroups.txt
+++ b/Documentation/cgroups/cgroups.txt
@@ -24,6 +24,7 @@ CONTENTS:
   2.1 Basic Usage
   2.2 Attaching processes
   2.3 Mounting hierarchies by name
+  2.4 Mounting hierarchies with no subsystems
 3. Kernel API
   3.1 Overview
   3.2 Synchronization
@@ -43,24 +44,29 @@ specialized behaviour.
 
 Definitions:
 
-A *cgroup* associates a set of tasks with a set of parameters for one
-or more subsystems.
+A *cgroup* associates a set of tasks with zero or more subsystems.
 
-A *subsystem* is a module that makes use of the task grouping
-facilities provided by cgroups to treat groups of tasks in
-particular ways. A subsystem is typically a "resource controller" that
+A *subsystem* is a module that treats the tasks of each cgroup in a
+particular way. A subsystem is typically a "resource controller" that
 schedules a resource or applies per-cgroup limits, but it may be
-anything that wants to act on a group of processes, e.g. a
-virtualization subsystem.
+anything that wants to act on a group of tasks, e.g. a virtualization
+subsystem.
 
-A *hierarchy* is a set of cgroups arranged in a tree, such that
-every task in the system is in exactly one of the cgroups in the
-hierarchy, and a set of subsystems; each subsystem has system-specific
-state attached to each cgroup in the hierarchy.  Each hierarchy has
-an instance of the cgroup virtual filesystem associated with it.
+A *hierarchy* is a non-empty set of cgroups arranged in a tree and a
+set of subsystems such that the cgroups in the hierarchy
+partition all the tasks in the system (in other words, every task in the
+system is in exactly one of the cgroups in the hierarchy) and each
+subsystem attaches its own state to each cgroup in the hierarchy.
 
-At any one time there may be multiple active hierarchies of task
-cgroups. Each hierarchy is a partition of all tasks in the system.
+There may be zero or more active hierarchies. Each hierarchy has an
+instance of the cgroup virtual filesystem associated with it. The tree
+of cgroups is represented by the directory tree in the cgroup virtual
+filesystem.
+
+The sets of subsystems participating in distinct hierarchies are either
+identical or disjoint. If the sets are identical, the virtual filesystems
+associated with the hierarchies have identical content and a change in
+one is automatically reflected in all the others.
 
 User-level code may create and destroy cgroups by name in an
 instance of the cgroup virtual file system, specify and query to
@@ -69,9 +75,9 @@ a cgroup. Those creations and assignments only affect the hierarchy
 associated with that instance of the cgroup file system.
 
 On their own, the only use for cgroups is for simple job
-tracking. The intention is that other subsystems hook into the generic
+tracking. The intention is that subsystems hook into the generic
 cgroup support to provide new attributes for cgroups, such as
-accounting/limiting the resources which processes in a cgroup can
+accounting/limiting the resources which tasks in a cgroup can
 access. For example, cpusets (see Documentation/cgroups/cpusets.txt) allow
 you to associate a set of CPUs and a set of memory nodes with the
 tasks in each cgroup.
@@ -79,12 +85,12 @@ tasks in each cgroup.
 1.2 Why are cgroups needed ?
 ----------------------------
 
-There are multiple efforts to provide process aggregations in the
+There are multiple efforts to provide task aggregations in the
 Linux kernel, mainly for resource-tracking purposes. Such efforts
 include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server
 namespaces. These all require the basic notion of a
-grouping/partitioning of processes, with newly forked processes ending
-up in the same group (cgroup) as their parent process.
+grouping/partitioning of tasks, with newly forked tasks ending
+up in the same group (cgroup) as their parent task.
 
 The kernel cgroup patch provides the minimum essential kernel
 mechanisms required to efficiently implement such groups. It has
@@ -418,11 +424,11 @@ To remove a cgroup, just use rmdir:
 # rmdir my_sub_cs
 
 This will fail if the cgroup is in use (has cgroups inside, or
-has processes attached, or is held alive by other subsystem-specific
+has tasks attached, or is held alive by other subsystem-specific
 reference).
 
-2.2 Attaching processes
------------------------
+2.2 Attaching tasks
+-------------------
 
 # /bin/echo PID > tasks
 
@@ -450,7 +456,7 @@ move it into a new cgroup (possibly the root cgroup) by writing to the
 new cgroup's tasks file.
 
 Note: Due to some restrictions enforced by some cgroup subsystems, moving
-a process to another cgroup can fail.
+a task to another cgroup can fail.
 
 2.3 Mounting hierarchies by name
 --------------------------------
@@ -471,6 +477,13 @@ you give a subsystem a name.
 The name of the subsystem appears as part of the hierarchy description
 in /proc/mounts and /proc/<pid>/cgroups.
 
+2.4 Mounting hierarchies with no subsystems
+-------------------------------------------
+
+To mount a hierarchy with no associated subsystems, specify a name
+for the hierarchy and the dummy subsystem name "none".  For example: 
+
+# mount -t cgroup -o name=hier0,none hier0 /sys/fs/cgroup/h0 
 
 3. Kernel API
 =============
@@ -658,7 +671,7 @@ A: bash's builtin 'echo' command does not check calls to write() against
    errors. If you use it in the cgroup file system, you won't be
    able to tell whether a command succeeded or failed.
 
-Q: When I attach processes, only the first of the line gets really attached !
+Q: When I attach tasks, only the first of the line gets really attached !
 A: We can only return one error code per call to write(). So you should also
    put only ONE PID.