cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

cgroups.rst (27005B)


      1==============
      2Control Groups
      3==============
      4
      5Written by Paul Menage <menage@google.com> based on
      6Documentation/admin-guide/cgroup-v1/cpusets.rst
      7
      8Original copyright statements from cpusets.txt:
      9
     10Portions Copyright (C) 2004 BULL SA.
     11
     12Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
     13
     14Modified by Paul Jackson <pj@sgi.com>
     15
     16Modified by Christoph Lameter <cl@linux.com>
     17
     18.. CONTENTS:
     19
     20	1. Control Groups
     21	1.1 What are cgroups ?
     22	1.2 Why are cgroups needed ?
     23	1.3 How are cgroups implemented ?
     24	1.4 What does notify_on_release do ?
     25	1.5 What does clone_children do ?
     26	1.6 How do I use cgroups ?
     27	2. Usage Examples and Syntax
     28	2.1 Basic Usage
     29	2.2 Attaching processes
     30	2.3 Mounting hierarchies by name
     31	3. Kernel API
     32	3.1 Overview
     33	3.2 Synchronization
     34	3.3 Subsystem API
     35	4. Extended attributes usage
     36	5. Questions
     37
     381. Control Groups
     39=================
     40
     411.1 What are cgroups ?
     42----------------------
     43
     44Control Groups provide a mechanism for aggregating/partitioning sets of
     45tasks, and all their future children, into hierarchical groups with
     46specialized behaviour.
     47
     48Definitions:
     49
     50A *cgroup* associates a set of tasks with a set of parameters for one
     51or more subsystems.
     52
     53A *subsystem* is a module that makes use of the task grouping
     54facilities provided by cgroups to treat groups of tasks in
     55particular ways. A subsystem is typically a "resource controller" that
     56schedules a resource or applies per-cgroup limits, but it may be
     57anything that wants to act on a group of processes, e.g. a
     58virtualization subsystem.
     59
     60A *hierarchy* is a set of cgroups arranged in a tree, such that
     61every task in the system is in exactly one of the cgroups in the
     62hierarchy, and a set of subsystems; each subsystem has system-specific
     63state attached to each cgroup in the hierarchy.  Each hierarchy has
     64an instance of the cgroup virtual filesystem associated with it.
     65
     66At any one time there may be multiple active hierarchies of task
     67cgroups. Each hierarchy is a partition of all tasks in the system.
     68
     69User-level code may create and destroy cgroups by name in an
     70instance of the cgroup virtual file system, specify and query to
     71which cgroup a task is assigned, and list the task PIDs assigned to
     72a cgroup. Those creations and assignments only affect the hierarchy
     73associated with that instance of the cgroup file system.
     74
     75On their own, the only use for cgroups is for simple job
     76tracking. The intention is that other subsystems hook into the generic
     77cgroup support to provide new attributes for cgroups, such as
     78accounting/limiting the resources which processes in a cgroup can
     79access. For example, cpusets (see Documentation/admin-guide/cgroup-v1/cpusets.rst) allow
     80you to associate a set of CPUs and a set of memory nodes with the
     81tasks in each cgroup.
     82
     831.2 Why are cgroups needed ?
     84----------------------------
     85
     86There are multiple efforts to provide process aggregations in the
     87Linux kernel, mainly for resource-tracking purposes. Such efforts
     88include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server
     89namespaces. These all require the basic notion of a
     90grouping/partitioning of processes, with newly forked processes ending
     91up in the same group (cgroup) as their parent process.
     92
     93The kernel cgroup patch provides the minimum essential kernel
     94mechanisms required to efficiently implement such groups. It has
     95minimal impact on the system fast paths, and provides hooks for
     96specific subsystems such as cpusets to provide additional behaviour as
     97desired.
     98
     99Multiple hierarchy support is provided to allow for situations where
    100the division of tasks into cgroups is distinctly different for
    101different subsystems - having parallel hierarchies allows each
    102hierarchy to be a natural division of tasks, without having to handle
    103complex combinations of tasks that would be present if several
    104unrelated subsystems needed to be forced into the same tree of
    105cgroups.
    106
    107At one extreme, each resource controller or subsystem could be in a
    108separate hierarchy; at the other extreme, all subsystems
    109would be attached to the same hierarchy.
    110
    111As an example of a scenario (originally proposed by vatsa@in.ibm.com)
    112that can benefit from multiple hierarchies, consider a large
    113university server with various users - students, professors, system
    114tasks etc. The resource planning for this server could be along the
    115following lines::
    116
    117       CPU :          "Top cpuset"
    118                       /       \
    119               CPUSet1         CPUSet2
    120                  |               |
    121               (Professors)    (Students)
    122
    123               In addition (system tasks) are attached to topcpuset (so
    124               that they can run anywhere) with a limit of 20%
    125
    126       Memory : Professors (50%), Students (30%), system (20%)
    127
    128       Disk : Professors (50%), Students (30%), system (20%)
    129
    130       Network : WWW browsing (20%), Network File System (60%), others (20%)
    131                               / \
    132               Professors (15%)  students (5%)
    133
    134Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd goes
    135into the NFS network class.
    136
    137At the same time Firefox/Lynx will share an appropriate CPU/Memory class
    138depending on who launched it (prof/student).
    139
    140With the ability to classify tasks differently for different resources
    141(by putting those resource subsystems in different hierarchies),
    142the admin can easily set up a script which receives exec notifications
    143and depending on who is launching the browser he can::
    144
    145    # echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks
    146
    147With only a single hierarchy, he now would potentially have to create
    148a separate cgroup for every browser launched and associate it with
    149appropriate network and other resource class.  This may lead to
    150proliferation of such cgroups.
    151
    152Also let's say that the administrator would like to give enhanced network
    153access temporarily to a student's browser (since it is night and the user
    154wants to do online gaming :))  OR give one of the student's simulation
    155apps enhanced CPU power.
    156
    157With ability to write PIDs directly to resource classes, it's just a
    158matter of::
    159
    160       # echo pid > /sys/fs/cgroup/network/<new_class>/tasks
    161       (after some time)
    162       # echo pid > /sys/fs/cgroup/network/<orig_class>/tasks
    163
    164Without this ability, the administrator would have to split the cgroup into
    165multiple separate ones and then associate the new cgroups with the
    166new resource classes.
    167
    168
    169
    1701.3 How are cgroups implemented ?
    171---------------------------------
    172
    173Control Groups extends the kernel as follows:
    174
    175 - Each task in the system has a reference-counted pointer to a
    176   css_set.
    177
    178 - A css_set contains a set of reference-counted pointers to
    179   cgroup_subsys_state objects, one for each cgroup subsystem
    180   registered in the system. There is no direct link from a task to
    181   the cgroup of which it's a member in each hierarchy, but this
    182   can be determined by following pointers through the
    183   cgroup_subsys_state objects. This is because accessing the
    184   subsystem state is something that's expected to happen frequently
    185   and in performance-critical code, whereas operations that require a
    186   task's actual cgroup assignments (in particular, moving between
    187   cgroups) are less common. A linked list runs through the cg_list
    188   field of each task_struct using the css_set, anchored at
    189   css_set->tasks.
    190
    191 - A cgroup hierarchy filesystem can be mounted for browsing and
    192   manipulation from user space.
    193
    194 - You can list all the tasks (by PID) attached to any cgroup.
    195
    196The implementation of cgroups requires a few, simple hooks
    197into the rest of the kernel, none in performance-critical paths:
    198
    199 - in init/main.c, to initialize the root cgroups and initial
    200   css_set at system boot.
    201
    202 - in fork and exit, to attach and detach a task from its css_set.
    203
    204In addition, a new file system of type "cgroup" may be mounted, to
    205enable browsing and modifying the cgroups presently known to the
    206kernel.  When mounting a cgroup hierarchy, you may specify a
    207comma-separated list of subsystems to mount as the filesystem mount
    208options.  By default, mounting the cgroup filesystem attempts to
    209mount a hierarchy containing all registered subsystems.
    210
    211If an active hierarchy with exactly the same set of subsystems already
    212exists, it will be reused for the new mount. If no existing hierarchy
    213matches, and any of the requested subsystems are in use in an existing
    214hierarchy, the mount will fail with -EBUSY. Otherwise, a new hierarchy
    215is activated, associated with the requested subsystems.
    216
    217It's not currently possible to bind a new subsystem to an active
    218cgroup hierarchy, or to unbind a subsystem from an active cgroup
    219hierarchy. This may be possible in future, but is fraught with nasty
    220error-recovery issues.
    221
    222When a cgroup filesystem is unmounted, if there are any
    223child cgroups created below the top-level cgroup, that hierarchy
    224will remain active even though unmounted; if there are no
    225child cgroups then the hierarchy will be deactivated.
    226
    227No new system calls are added for cgroups - all support for
    228querying and modifying cgroups is via this cgroup file system.
    229
    230Each task under /proc has an added file named 'cgroup' displaying,
    231for each active hierarchy, the subsystem names and the cgroup name
    232as the path relative to the root of the cgroup file system.
    233
    234Each cgroup is represented by a directory in the cgroup file system
    235containing the following files describing that cgroup:
    236
    237 - tasks: list of tasks (by PID) attached to that cgroup.  This list
    238   is not guaranteed to be sorted.  Writing a thread ID into this file
    239   moves the thread into this cgroup.
    240 - cgroup.procs: list of thread group IDs in the cgroup.  This list is
    241   not guaranteed to be sorted or free of duplicate TGIDs, and userspace
    242   should sort/uniquify the list if this property is required.
    243   Writing a thread group ID into this file moves all threads in that
    244   group into this cgroup.
    245 - notify_on_release flag: run the release agent on exit?
    246 - release_agent: the path to use for release notifications (this file
    247   exists in the top cgroup only)
    248
    249Other subsystems such as cpusets may add additional files in each
    250cgroup dir.
    251
    252New cgroups are created using the mkdir system call or shell
    253command.  The properties of a cgroup, such as its flags, are
    254modified by writing to the appropriate file in that cgroups
    255directory, as listed above.
    256
    257The named hierarchical structure of nested cgroups allows partitioning
    258a large system into nested, dynamically changeable, "soft-partitions".
    259
    260The attachment of each task, automatically inherited at fork by any
    261children of that task, to a cgroup allows organizing the work load
    262on a system into related sets of tasks.  A task may be re-attached to
    263any other cgroup, if allowed by the permissions on the necessary
    264cgroup file system directories.
    265
    266When a task is moved from one cgroup to another, it gets a new
    267css_set pointer - if there's an already existing css_set with the
    268desired collection of cgroups then that group is reused, otherwise a new
    269css_set is allocated. The appropriate existing css_set is located by
    270looking into a hash table.
    271
    272To allow access from a cgroup to the css_sets (and hence tasks)
    273that comprise it, a set of cg_cgroup_link objects form a lattice;
    274each cg_cgroup_link is linked into a list of cg_cgroup_links for
    275a single cgroup on its cgrp_link_list field, and a list of
    276cg_cgroup_links for a single css_set on its cg_link_list.
    277
    278Thus the set of tasks in a cgroup can be listed by iterating over
    279each css_set that references the cgroup, and sub-iterating over
    280each css_set's task set.
    281
    282The use of a Linux virtual file system (vfs) to represent the
    283cgroup hierarchy provides for a familiar permission and name space
    284for cgroups, with a minimum of additional kernel code.
    285
    2861.4 What does notify_on_release do ?
    287------------------------------------
    288
    289If the notify_on_release flag is enabled (1) in a cgroup, then
    290whenever the last task in the cgroup leaves (exits or attaches to
    291some other cgroup) and the last child cgroup of that cgroup
    292is removed, then the kernel runs the command specified by the contents
    293of the "release_agent" file in that hierarchy's root directory,
    294supplying the pathname (relative to the mount point of the cgroup
    295file system) of the abandoned cgroup.  This enables automatic
    296removal of abandoned cgroups.  The default value of
    297notify_on_release in the root cgroup at system boot is disabled
    298(0).  The default value of other cgroups at creation is the current
    299value of their parents' notify_on_release settings. The default value of
    300a cgroup hierarchy's release_agent path is empty.
    301
    3021.5 What does clone_children do ?
    303---------------------------------
    304
    305This flag only affects the cpuset controller. If the clone_children
    306flag is enabled (1) in a cgroup, a new cpuset cgroup will copy its
    307configuration from the parent during initialization.
    308
    3091.6 How do I use cgroups ?
    310--------------------------
    311
    312To start a new job that is to be contained within a cgroup, using
    313the "cpuset" cgroup subsystem, the steps are something like::
    314
    315 1) mount -t tmpfs cgroup_root /sys/fs/cgroup
    316 2) mkdir /sys/fs/cgroup/cpuset
    317 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
    318 4) Create the new cgroup by doing mkdir's and write's (or echo's) in
    319    the /sys/fs/cgroup/cpuset virtual file system.
    320 5) Start a task that will be the "founding father" of the new job.
    321 6) Attach that task to the new cgroup by writing its PID to the
    322    /sys/fs/cgroup/cpuset tasks file for that cgroup.
    323 7) fork, exec or clone the job tasks from this founding father task.
    324
    325For example, the following sequence of commands will setup a cgroup
    326named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
    327and then start a subshell 'sh' in that cgroup::
    328
    329  mount -t tmpfs cgroup_root /sys/fs/cgroup
    330  mkdir /sys/fs/cgroup/cpuset
    331  mount -t cgroup cpuset -ocpuset /sys/fs/cgroup/cpuset
    332  cd /sys/fs/cgroup/cpuset
    333  mkdir Charlie
    334  cd Charlie
    335  /bin/echo 2-3 > cpuset.cpus
    336  /bin/echo 1 > cpuset.mems
    337  /bin/echo $$ > tasks
    338  sh
    339  # The subshell 'sh' is now running in cgroup Charlie
    340  # The next line should display '/Charlie'
    341  cat /proc/self/cgroup
    342
    3432. Usage Examples and Syntax
    344============================
    345
    3462.1 Basic Usage
    347---------------
    348
    349Creating, modifying, using cgroups can be done through the cgroup
    350virtual filesystem.
    351
    352To mount a cgroup hierarchy with all available subsystems, type::
    353
    354  # mount -t cgroup xxx /sys/fs/cgroup
    355
    356The "xxx" is not interpreted by the cgroup code, but will appear in
    357/proc/mounts so may be any useful identifying string that you like.
    358
    359Note: Some subsystems do not work without some user input first.  For instance,
    360if cpusets are enabled the user will have to populate the cpus and mems files
    361for each new cgroup created before that group can be used.
    362
    363As explained in section `1.2 Why are cgroups needed?` you should create
    364different hierarchies of cgroups for each single resource or group of
    365resources you want to control. Therefore, you should mount a tmpfs on
    366/sys/fs/cgroup and create directories for each cgroup resource or resource
    367group::
    368
    369  # mount -t tmpfs cgroup_root /sys/fs/cgroup
    370  # mkdir /sys/fs/cgroup/rg1
    371
    372To mount a cgroup hierarchy with just the cpuset and memory
    373subsystems, type::
    374
    375  # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1
    376
    377While remounting cgroups is currently supported, it is not recommend
    378to use it. Remounting allows changing bound subsystems and
    379release_agent. Rebinding is hardly useful as it only works when the
    380hierarchy is empty and release_agent itself should be replaced with
    381conventional fsnotify. The support for remounting will be removed in
    382the future.
    383
    384To Specify a hierarchy's release_agent::
    385
    386  # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \
    387    xxx /sys/fs/cgroup/rg1
    388
    389Note that specifying 'release_agent' more than once will return failure.
    390
    391Note that changing the set of subsystems is currently only supported
    392when the hierarchy consists of a single (root) cgroup. Supporting
    393the ability to arbitrarily bind/unbind subsystems from an existing
    394cgroup hierarchy is intended to be implemented in the future.
    395
    396Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the
    397tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1
    398is the cgroup that holds the whole system.
    399
    400If you want to change the value of release_agent::
    401
    402  # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent
    403
    404It can also be changed via remount.
    405
    406If you want to create a new cgroup under /sys/fs/cgroup/rg1::
    407
    408  # cd /sys/fs/cgroup/rg1
    409  # mkdir my_cgroup
    410
    411Now you want to do something with this cgroup:
    412
    413  # cd my_cgroup
    414
    415In this directory you can find several files::
    416
    417  # ls
    418  cgroup.procs notify_on_release tasks
    419  (plus whatever files added by the attached subsystems)
    420
    421Now attach your shell to this cgroup::
    422
    423  # /bin/echo $$ > tasks
    424
    425You can also create cgroups inside your cgroup by using mkdir in this
    426directory::
    427
    428  # mkdir my_sub_cs
    429
    430To remove a cgroup, just use rmdir::
    431
    432  # rmdir my_sub_cs
    433
    434This will fail if the cgroup is in use (has cgroups inside, or
    435has processes attached, or is held alive by other subsystem-specific
    436reference).
    437
    4382.2 Attaching processes
    439-----------------------
    440
    441::
    442
    443  # /bin/echo PID > tasks
    444
    445Note that it is PID, not PIDs. You can only attach ONE task at a time.
    446If you have several tasks to attach, you have to do it one after another::
    447
    448  # /bin/echo PID1 > tasks
    449  # /bin/echo PID2 > tasks
    450	  ...
    451  # /bin/echo PIDn > tasks
    452
    453You can attach the current shell task by echoing 0::
    454
    455  # echo 0 > tasks
    456
    457You can use the cgroup.procs file instead of the tasks file to move all
    458threads in a threadgroup at once. Echoing the PID of any task in a
    459threadgroup to cgroup.procs causes all tasks in that threadgroup to be
    460attached to the cgroup. Writing 0 to cgroup.procs moves all tasks
    461in the writing task's threadgroup.
    462
    463Note: Since every task is always a member of exactly one cgroup in each
    464mounted hierarchy, to remove a task from its current cgroup you must
    465move it into a new cgroup (possibly the root cgroup) by writing to the
    466new cgroup's tasks file.
    467
    468Note: Due to some restrictions enforced by some cgroup subsystems, moving
    469a process to another cgroup can fail.
    470
    4712.3 Mounting hierarchies by name
    472--------------------------------
    473
    474Passing the name=<x> option when mounting a cgroups hierarchy
    475associates the given name with the hierarchy.  This can be used when
    476mounting a pre-existing hierarchy, in order to refer to it by name
    477rather than by its set of active subsystems.  Each hierarchy is either
    478nameless, or has a unique name.
    479
    480The name should match [\w.-]+
    481
    482When passing a name=<x> option for a new hierarchy, you need to
    483specify subsystems manually; the legacy behaviour of mounting all
    484subsystems when none are explicitly specified is not supported when
    485you give a subsystem a name.
    486
    487The name of the subsystem appears as part of the hierarchy description
    488in /proc/mounts and /proc/<pid>/cgroups.
    489
    490
    4913. Kernel API
    492=============
    493
    4943.1 Overview
    495------------
    496
    497Each kernel subsystem that wants to hook into the generic cgroup
    498system needs to create a cgroup_subsys object. This contains
    499various methods, which are callbacks from the cgroup system, along
    500with a subsystem ID which will be assigned by the cgroup system.
    501
    502Other fields in the cgroup_subsys object include:
    503
    504- subsys_id: a unique array index for the subsystem, indicating which
    505  entry in cgroup->subsys[] this subsystem should be managing.
    506
    507- name: should be initialized to a unique subsystem name. Should be
    508  no longer than MAX_CGROUP_TYPE_NAMELEN.
    509
    510- early_init: indicate if the subsystem needs early initialization
    511  at system boot.
    512
    513Each cgroup object created by the system has an array of pointers,
    514indexed by subsystem ID; this pointer is entirely managed by the
    515subsystem; the generic cgroup code will never touch this pointer.
    516
    5173.2 Synchronization
    518-------------------
    519
    520There is a global mutex, cgroup_mutex, used by the cgroup
    521system. This should be taken by anything that wants to modify a
    522cgroup. It may also be taken to prevent cgroups from being
    523modified, but more specific locks may be more appropriate in that
    524situation.
    525
    526See kernel/cgroup.c for more details.
    527
    528Subsystems can take/release the cgroup_mutex via the functions
    529cgroup_lock()/cgroup_unlock().
    530
    531Accessing a task's cgroup pointer may be done in the following ways:
    532- while holding cgroup_mutex
    533- while holding the task's alloc_lock (via task_lock())
    534- inside an rcu_read_lock() section via rcu_dereference()
    535
    5363.3 Subsystem API
    537-----------------
    538
    539Each subsystem should:
    540
    541- add an entry in linux/cgroup_subsys.h
    542- define a cgroup_subsys object called <name>_cgrp_subsys
    543
    544Each subsystem may export the following methods. The only mandatory
    545methods are css_alloc/free. Any others that are null are presumed to
    546be successful no-ops.
    547
    548``struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)``
    549(cgroup_mutex held by caller)
    550
    551Called to allocate a subsystem state object for a cgroup. The
    552subsystem should allocate its subsystem state object for the passed
    553cgroup, returning a pointer to the new object on success or a
    554ERR_PTR() value. On success, the subsystem pointer should point to
    555a structure of type cgroup_subsys_state (typically embedded in a
    556larger subsystem-specific object), which will be initialized by the
    557cgroup system. Note that this will be called at initialization to
    558create the root subsystem state for this subsystem; this case can be
    559identified by the passed cgroup object having a NULL parent (since
    560it's the root of the hierarchy) and may be an appropriate place for
    561initialization code.
    562
    563``int css_online(struct cgroup *cgrp)``
    564(cgroup_mutex held by caller)
    565
    566Called after @cgrp successfully completed all allocations and made
    567visible to cgroup_for_each_child/descendant_*() iterators. The
    568subsystem may choose to fail creation by returning -errno. This
    569callback can be used to implement reliable state sharing and
    570propagation along the hierarchy. See the comment on
    571cgroup_for_each_descendant_pre() for details.
    572
    573``void css_offline(struct cgroup *cgrp);``
    574(cgroup_mutex held by caller)
    575
    576This is the counterpart of css_online() and called iff css_online()
    577has succeeded on @cgrp. This signifies the beginning of the end of
    578@cgrp. @cgrp is being removed and the subsystem should start dropping
    579all references it's holding on @cgrp. When all references are dropped,
    580cgroup removal will proceed to the next step - css_free(). After this
    581callback, @cgrp should be considered dead to the subsystem.
    582
    583``void css_free(struct cgroup *cgrp)``
    584(cgroup_mutex held by caller)
    585
    586The cgroup system is about to free @cgrp; the subsystem should free
    587its subsystem state object. By the time this method is called, @cgrp
    588is completely unused; @cgrp->parent is still valid. (Note - can also
    589be called for a newly-created cgroup if an error occurs after this
    590subsystem's create() method has been called for the new cgroup).
    591
    592``int can_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
    593(cgroup_mutex held by caller)
    594
    595Called prior to moving one or more tasks into a cgroup; if the
    596subsystem returns an error, this will abort the attach operation.
    597@tset contains the tasks to be attached and is guaranteed to have at
    598least one task in it.
    599
    600If there are multiple tasks in the taskset, then:
    601  - it's guaranteed that all are from the same thread group
    602  - @tset contains all tasks from the thread group whether or not
    603    they're switching cgroups
    604  - the first task is the leader
    605
    606Each @tset entry also contains the task's old cgroup and tasks which
    607aren't switching cgroup can be skipped easily using the
    608cgroup_taskset_for_each() iterator. Note that this isn't called on a
    609fork. If this method returns 0 (success) then this should remain valid
    610while the caller holds cgroup_mutex and it is ensured that either
    611attach() or cancel_attach() will be called in future.
    612
    613``void css_reset(struct cgroup_subsys_state *css)``
    614(cgroup_mutex held by caller)
    615
    616An optional operation which should restore @css's configuration to the
    617initial state.  This is currently only used on the unified hierarchy
    618when a subsystem is disabled on a cgroup through
    619"cgroup.subtree_control" but should remain enabled because other
    620subsystems depend on it.  cgroup core makes such a css invisible by
    621removing the associated interface files and invokes this callback so
    622that the hidden subsystem can return to the initial neutral state.
    623This prevents unexpected resource control from a hidden css and
    624ensures that the configuration is in the initial state when it is made
    625visible again later.
    626
    627``void cancel_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
    628(cgroup_mutex held by caller)
    629
    630Called when a task attach operation has failed after can_attach() has succeeded.
    631A subsystem whose can_attach() has some side-effects should provide this
    632function, so that the subsystem can implement a rollback. If not, not necessary.
    633This will be called only about subsystems whose can_attach() operation have
    634succeeded. The parameters are identical to can_attach().
    635
    636``void attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
    637(cgroup_mutex held by caller)
    638
    639Called after the task has been attached to the cgroup, to allow any
    640post-attachment activity that requires memory allocations or blocking.
    641The parameters are identical to can_attach().
    642
    643``void fork(struct task_struct *task)``
    644
    645Called when a task is forked into a cgroup.
    646
    647``void exit(struct task_struct *task)``
    648
    649Called during task exit.
    650
    651``void free(struct task_struct *task)``
    652
    653Called when the task_struct is freed.
    654
    655``void bind(struct cgroup *root)``
    656(cgroup_mutex held by caller)
    657
    658Called when a cgroup subsystem is rebound to a different hierarchy
    659and root cgroup. Currently this will only involve movement between
    660the default hierarchy (which never has sub-cgroups) and a hierarchy
    661that is being created/destroyed (and hence has no sub-cgroups).
    662
    6634. Extended attribute usage
    664===========================
    665
    666cgroup filesystem supports certain types of extended attributes in its
    667directories and files.  The current supported types are:
    668
    669	- Trusted (XATTR_TRUSTED)
    670	- Security (XATTR_SECURITY)
    671
    672Both require CAP_SYS_ADMIN capability to set.
    673
    674Like in tmpfs, the extended attributes in cgroup filesystem are stored
    675using kernel memory and it's advised to keep the usage at minimum.  This
    676is the reason why user defined extended attributes are not supported, since
    677any user can do it and there's no limit in the value size.
    678
    679The current known users for this feature are SELinux to limit cgroup usage
    680in containers and systemd for assorted meta data like main PID in a cgroup
    681(systemd creates a cgroup per service).
    682
    6835. Questions
    684============
    685
    686::
    687
    688  Q: what's up with this '/bin/echo' ?
    689  A: bash's builtin 'echo' command does not check calls to write() against
    690     errors. If you use it in the cgroup file system, you won't be
    691     able to tell whether a command succeeded or failed.
    692
    693  Q: When I attach processes, only the first of the line gets really attached !
    694  A: We can only return one error code per call to write(). So you should also
    695     put only ONE PID.