doc: add cgroup documentation

First draft of the new cgroup documentation.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

README.md

@@ -244,6 +244,46 @@ unnecessary overhead, which can be removed at build-time using:
     configure --enable-auto-reload
 
 
+**Cgroups**
+
+Finit supports cgroups v2 and comes with the following default groups
+in which services and user sessions are placed in:
+
+     /sys/fs/cgroup
+       |-- init/               # cpu.weight:100
+       |-- system/             # cpu.weight:9800
+       `-- user/               # cpu.weight:100
+
+Finit itself, helper services like `ifup -a`, and the like are placed
+in the leaf-node group `init/`, which also is _reserved_.
+
+All run/task/service/sysv processes are placed in their own sub-group
+in `system/`.  The name of each sub-group is taken from the respective
+`.conf` file from `/etc/finit.d`.
+
+All getty/tty processes are placed in their own sub-group in `user/`.
+The name of each sub-group is taken from the username.
+
+A fourth group also exists, the `root` group.  It is also _reserved_ and
+primarily intended for RT tasks.  If you have RT tasks they need to be
+declared as such in their service stanza like this:
+
+    service [...] <...> cgroup.root /path/to/foo args -- description
+
+or
+
+    cgroup.root
+    service [...] <...> /path/to/foo args -- description
+    service [...] <...> /path/to/bar args -- description
+
+See [doc/config.md](doc/config.md#cgroups) for more information, e.g.,
+how to configure per-group limits.
+
+The `initctl` tool has three commands to help debug and optimize the
+setup and monitoring of cgroups.  See the `ps`, `top`, and `cgroup`
+commands for details.
+
+
 Runparts & /etc/rc.local
 ------------------------
 

doc/config.md

@@ -2,7 +2,9 @@ Configuration
 =============
 
 * [Introduction](#introduction)
+* [Service Environment](#service-environment)
 * [Service Wrapper Scripts](#service-wrapper-scripts)
+* [Cgroups](#cgroups)
 * [Configuration File Syntax](#configuration-file-syntax)
   * [Hostname](#hostname)
   * [Kernel Modules](#kernel-modules)
@@ -128,6 +130,68 @@ example employs a wrapper script in `/etc/start.d`.
 >           instead of sending SIGHUP at restart/reload events.
 
 
+Cgroups
+-------
+
+There are three major cgroup configuration directives:
+
+ 1. Global top-level group: init, system, user, or a custom group
+ 2. Selecting a top-level group for a set of run/task/services
+ 3. Per run/task/service limits
+
+Top-level group configuration.
+
+    # Top-level cgroups and their default settings.  All groups mandatory
+    # but more can be added, max 8 groups in total currently.  The cgroup
+    # 'root' is also available, reserved for RT processes.  Settings are
+    # as-is, only one shorthand 'mem.' exists, other than that it's the
+    # cgroup v2 controller default names.
+    cgroup init   cpu.weight:100
+    cgroup user   cpu.weight:100
+    cgroup system cpu.weight:9800
+
+Adding an extra cgroup `maint/` will require you to adjust the weight of
+the above three.  We leave `init/` and `user /` as-is reducing weight of
+`system/` to 9700.
+
+    cgroup system cpu.weight:9700
+
+    # Example extra cgroup 'maint'
+    cgroup maint  cpu.weight:100
+
+By default, the `system/` cgroup is selected for almost everything.  The
+`init/` cgroup is reserved for PID 1 itself and its closest relatives,
+e.g., children of `ifup -a`.  The `user/` cgroup is for local TTY logins
+spawned by getty.
+
+To select a different top-level cgroup, e.g. `maint/`, one can either
+define it for a group of run/task/service directives in a `.conf` or per
+each stanza:
+
+    cgroup.maint
+    service [...] <...> /path/to/foo args -- description
+    service [...] <...> /path/to/bar args -- description
+
+or
+
+    service [...] <...> cgroup.maint /path/to/foo args -- description
+
+The latter form also allows per-stanza limits on the form:
+
+    service [...] <...> cgroup.maint,cpu.max:10000,mem.max:655360 /path/to/foo args -- description
+
+Notice the comma separation and the `mem.` exception to the rule: every
+cgroup setting maps directly to cgroup v2 syntax.  I.e., `cpu.max` maps
+to the file `/sys/fs/cgroup/maint/foo/cpu.max`.  There is not filtering,
+except for expanding the shorthand `mem.` to `memory.`, if the file is
+not available, either the cgroup controller is not available in your
+Linux kernel, or the name is misspelled.
+
+> Linux cgroups and details surrounding values are not explained in the
+> Finit documentation.  The Linux admin-guide cover this well:
+> <https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html>
+
+
 Configuration File Syntax
 -------------------------