Commit 25259fc9 authored by Vipin Sharma's avatar Vipin Sharma Committed by Tejun Heo
Browse files

cgroup: Miscellaneous cgroup documentation. 



Documentation of miscellaneous cgroup controller. This new controller is
used to track and limit the usage of scalar resources.

Signed-off-by: default avatarVipin Sharma <vipinsh@google.com>
Reviewed-by: default avatarDavid Rientjes <rientjes@google.com>
Signed-off-by: default avatarTejun Heo <tj@kernel.org>
parent a72232ea

Documentation/admin-guide/cgroup-v1/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@ Control Groups version 1 
    hugetlb

    memcg_test

    memory

    misc

    net_cls

    net_prio

    pids

Documentation/admin-guide/cgroup-v1/misc.rst

0 → 100644
+4 −0
Original line number Diff line number Diff line 
===============

Misc controller

===============

Please refer "Misc" documentation in Documentation/admin-guide/cgroup-v2.rst

Documentation/admin-guide/cgroup-v2.rst

+71 −2
Original line number Diff line number Diff line
@@ -65,8 +65,11 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgrou 
       5-7-1. RDMA Interface Files

     5-8. HugeTLB

       5.8-1. HugeTLB Interface Files

     5-8. Misc

       5-8-1. perf_event

     5-9. Misc

       5.9-1 Miscellaneous cgroup Interface Files

       5.9-2 Migration and Ownership

     5-10. Others

       5-10-1. perf_event

     5-N. Non-normative information

       5-N-1. CPU controller root cgroup process behaviour

       5-N-2. IO controller root cgroup process behaviour
@@ -2171,6 +2174,72 @@ HugeTLB Interface Files 
Misc

----



The Miscellaneous cgroup provides the resource limiting and tracking

mechanism for the scalar resources which cannot be abstracted like the other

cgroup resources. Controller is enabled by the CONFIG_CGROUP_MISC config

option.



A resource can be added to the controller via enum misc_res_type{} in the

include/linux/misc_cgroup.h file and the corresponding name via misc_res_name[]

in the kernel/cgroup/misc.c file. Provider of the resource must set its

capacity prior to using the resource by calling misc_cg_set_capacity().



Once a capacity is set then the resource usage can be updated using charge and

uncharge APIs. All of the APIs to interact with misc controller are in

include/linux/misc_cgroup.h.



Misc Interface Files

~~~~~~~~~~~~~~~~~~~~



Miscellaneous controller provides 3 interface files. If two misc resources (res_a and res_b) are registered then:



  misc.capacity

        A read-only flat-keyed file shown only in the root cgroup.  It shows

        miscellaneous scalar resources available on the platform along with

        their quantities::



	  $ cat misc.capacity

	  res_a 50

	  res_b 10



  misc.current

        A read-only flat-keyed file shown in the non-root cgroups.  It shows

        the current usage of the resources in the cgroup and its children.::



	  $ cat misc.current

	  res_a 3

	  res_b 0



  misc.max

        A read-write flat-keyed file shown in the non root cgroups. Allowed

        maximum usage of the resources in the cgroup and its children.::



	  $ cat misc.max

	  res_a max

	  res_b 4



	Limit can be set by::



	  # echo res_a 1 > misc.max



	Limit can be set to max by::



	  # echo res_a max > misc.max



        Limits can be set higher than the capacity value in the misc.capacity

        file.



Migration and Ownership

~~~~~~~~~~~~~~~~~~~~~~~



A miscellaneous scalar resource is charged to the cgroup in which it is used

first, and stays charged to that cgroup until that resource is freed. Migrating

a process to a different cgroup does not move the charge to the destination

cgroup where the process has moved.



Others

------



perf_event

~~~~~~~~~~