[RFC,2/2] cgroup: sev: Miscellaneous cgroup documentation.
diff mbox series

Message ID 20210218195549.1696769-3-vipinsh@google.com
State New, archived
Headers show
Series
  • cgroup: New misc cgroup controller
Related show

Commit Message

Vipin Sharma Feb. 18, 2021, 7:55 p.m. UTC
Documentation of miscellaneous cgroup controller. This new controller is
used to track and limit usage of scalar resources.

Signed-off-by: Vipin Sharma <vipinsh@google.com>
Reviewed-by: David Rientjes <rientjes@google.com>
---
 Documentation/admin-guide/cgroup-v1/misc.rst |  1 +
 Documentation/admin-guide/cgroup-v2.rst      | 64 +++++++++++++++++++-
 2 files changed, 63 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/admin-guide/cgroup-v1/misc.rst

Comments

Randy Dunlap Feb. 19, 2021, 7:02 p.m. UTC | #1
Hi,

On 2/18/21 11:55 AM, Vipin Sharma wrote:
> Documentation of miscellaneous cgroup controller. This new controller is
> used to track and limit usage of scalar resources.
> 
> Signed-off-by: Vipin Sharma <vipinsh@google.com>
> Reviewed-by: David Rientjes <rientjes@google.com>
> ---
>  Documentation/admin-guide/cgroup-v1/misc.rst |  1 +
>  Documentation/admin-guide/cgroup-v2.rst      | 64 +++++++++++++++++++-
>  2 files changed, 63 insertions(+), 2 deletions(-)
>  create mode 100644 Documentation/admin-guide/cgroup-v1/misc.rst
> 
> diff --git a/Documentation/admin-guide/cgroup-v1/misc.rst b/Documentation/admin-guide/cgroup-v1/misc.rst
> new file mode 100644
> index 000000000000..8e9e9311daeb
> --- /dev/null
> +++ b/Documentation/admin-guide/cgroup-v1/misc.rst
> @@ -0,0 +1 @@
> +/Documentation/admin-guide/cgroup-v2.rst
What is the purpose of this (above) file?

> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 1de8695c264b..1a41a3623b9b 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -63,8 +63,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
> @@ -2161,6 +2164,63 @@ HugeTLB Interface Files
>  	generated on this file reflects only the local events.
>  
>  Misc
> +--------------
> +
> +The Miscellaneous cgroup provides the resource allocation 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.
> +
> +The first two resources added to the miscellaneous controller are Secure
> +Encrypted Virtualization (SEV) ASIDs and SEV - Encrypted State (SEV-ES) ASIDs.
> +These limited ASIDs are used for encrypting virtual machines memory on the AMD
> +platform.
> +
> +Misc Interface Files
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Miscellaneous controller provides 3 interface files:
> +
> +  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
> +	  sev 50
> +	  sev_es 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
> +	  sev 3
> +	  sev_es 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
> +	  sev max
> +	  sev_es 4
> +
> +	Limit can be set by::
> +	  # echo sev 1 > misc.max
> +
> +	Limit can be set to max by::
> +	  # echo sev max > misc.max
> +
> +        Limits can be set more than the capacity value in the misc.capacity

                             higher than

> +        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 do not move the charge to the destination

                                   does

> +cgroup where the process has moved.
> +
> +Others
>  ----

That underline is too short for "Others".

>  
>  perf_event
> 

Try building this doc file, please.

next-20210219/Documentation/admin-guide/cgroup-v2.rst:2196: WARNING: Unexpected indentation.
next-20210219/Documentation/admin-guide/cgroup-v2.rst:2203: WARNING: Unexpected indentation.
next-20210219/Documentation/admin-guide/cgroup-v2.rst:2210: WARNING: Unexpected indentation.
next-20210219/Documentation/admin-guide/cgroup-v2.rst:2232: WARNING: Title underline too short.

Others
----
next-20210219/Documentation/admin-guide/cgroup-v2.rst:2232: WARNING: Title underline too short.


I think that the first 3 warnings are due to missing a blank line after ::
or they could have something to do with mixed tabs and spaces in the misc.*
properties descriptions.


thanks.
Vipin Sharma Feb. 24, 2021, 11:13 p.m. UTC | #2
On Fri, Feb 19, 2021 at 11:02:41AM -0800, Randy Dunlap wrote:
> > +++ b/Documentation/admin-guide/cgroup-v1/misc.rst
> > @@ -0,0 +1 @@
> > +/Documentation/admin-guide/cgroup-v2.rst
> What is the purpose of this (above) file?

This new controller has both cgroup v1 and v2 support. Tejun suggested
if we can point to v2 doc from v1. If this is not recommended approach I
can add all of the v2 documention of misc controller here, let me know.

I missed a heading and adding this file in cgroup-v1/index.rst.
Fixed it now.

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

Done

> > +a process to a different cgroup do not move the charge to the destination
> 
>                                    does

Done

> > +Others
> >  ----
> 
> That underline is too short for "Others".
> 

Fixed.

> Try building this doc file, please.
> 
> next-20210219/Documentation/admin-guide/cgroup-v2.rst:2196: WARNING: Unexpected indentation.
> next-20210219/Documentation/admin-guide/cgroup-v2.rst:2203: WARNING: Unexpected indentation.
> next-20210219/Documentation/admin-guide/cgroup-v2.rst:2210: WARNING: Unexpected indentation.
> next-20210219/Documentation/admin-guide/cgroup-v2.rst:2232: WARNING: Title underline too short.
> 
> Others
> ----
> next-20210219/Documentation/admin-guide/cgroup-v2.rst:2232: WARNING: Title underline too short.
> 
> 
> I think that the first 3 warnings are due to missing a blank line after ::
> or they could have something to do with mixed tabs and spaces in the misc.*
> properties descriptions.
> 

Sorry, I was not familiar with Sphinx build and didn't build using that.
I have fixed all of the above warnings. My next patch will reflect
fixes.

Thanks

Patch
diff mbox series

diff --git a/Documentation/admin-guide/cgroup-v1/misc.rst b/Documentation/admin-guide/cgroup-v1/misc.rst
new file mode 100644
index 000000000000..8e9e9311daeb
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/misc.rst
@@ -0,0 +1 @@ 
+/Documentation/admin-guide/cgroup-v2.rst
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 1de8695c264b..1a41a3623b9b 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -63,8 +63,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
@@ -2161,6 +2164,63 @@  HugeTLB Interface Files
 	generated on this file reflects only the local events.
 
 Misc
+--------------
+
+The Miscellaneous cgroup provides the resource allocation 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.
+
+The first two resources added to the miscellaneous controller are Secure
+Encrypted Virtualization (SEV) ASIDs and SEV - Encrypted State (SEV-ES) ASIDs.
+These limited ASIDs are used for encrypting virtual machines memory on the AMD
+platform.
+
+Misc Interface Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Miscellaneous controller provides 3 interface files:
+
+  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
+	  sev 50
+	  sev_es 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
+	  sev 3
+	  sev_es 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
+	  sev max
+	  sev_es 4
+
+	Limit can be set by::
+	  # echo sev 1 > misc.max
+
+	Limit can be set to max by::
+	  # echo sev max > misc.max
+
+        Limits can be set more 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 do not move the charge to the destination
+cgroup where the process has moved.
+
+Others
 ----
 
 perf_event