Add RT Conf documentation

docs/.custom_wordlist.txt

@@ -48,6 +48,7 @@ Mutexes
 NMI
 NMIs
 NOCB
+nocbs
 OSAL
 OSNOISE
 OSS
@@ -192,6 +193,7 @@ mutex
 mutexes
 ng
 nohz
+ondemand
 optimization
 oslat
 osnoise

docs/how-to/cpu-boot-configs.rst

@@ -10,6 +10,8 @@ The parameters covered here should be passed to the bootloader.
 For that, refer to :doc:`modify-kernel-boot-parameters`.
 
 
+.. _cpu-lists:
+
 CPU lists
 ---------
 

docs/how-to/index.rst

@@ -36,6 +36,7 @@ Configure Real-time Ubuntu Core:
 
    Create a Real-time Ubuntu Core image <uc-image-creation>
    Install real-time kernel on Ubuntu Core <uc-install-real-time-kernel>
+   Tune Real-Time Ubuntu using rt-conf <rt-conf-cli>
 
 For tuning an existing Ubuntu Core system, refer to :ref:`ubuntu-core-kernel-cmdline`.
 

docs/how-to/rt-conf-cli.md

@@ -0,0 +1,98 @@
+# How-to tune Real-Time Ubuntu using rt-conf
+
+*rt-conf* is a tool that helps users tune their system for real-time responsiveness. 
+This guide describes how to install and use it on Ubuntu. 
+
+## Install
+
+Install rt-conf as a snap:
+
+```shell
+sudo snap install rt-conf --beta --devmode
+```
+
+````{admonition} Developer mode
+The snap must be installed with `--devmode` to allow IRQ configuration.
+This is due to issue [#67](https://github.com/canonical/rt-conf/issues/67). 
+
+When installed in developer mode, the snap will not update automatically.
+To force an update:
+```shell
+sudo snap refresh rt-conf
+```
+````
+
+Grant access to allow GRUB configuration on a system that supports it:
+```shell
+sudo snap connect rt-conf:etc-default-grub
+```
+rt-conf uses this access to write a drop-in GRUB config file at `/etc/default/grub.d/60_rt-conf.cfg`.
+This file is removed when uninstalling the rt-conf snap.
+
+## Configure
+
+The default configuration file is located at `/var/snap/rt-conf/common/config.yaml`:
+
+```{literalinclude} rt-conf-config.yaml
+:language: yaml
+```
+
+The configuration file includes several examples.
+Uncomment useful examples and modify them to meet the tuning requirements.
+If a configuration is commented out, rt-conf will not perform any operations. 
+Anything that is set on your system remains untouched.
+Refer to the {doc}`../reference/rt-conf-yaml` for more details.
+
+## Run
+
+Once ready with the configurations, run rt-conf:
+```shell
+sudo rt-conf
+```
+
+```{admonition} Kernel command line parameters
+Pay attention to the output as it shows platform-specific instructions to complete kernel command line configurations.
+
+Setting kernel command line via rt-conf is not supported on [Ubuntu Core][UC]. 
+Instead, refer to {ref}`ubuntu-core-kernel-cmdline`.
+```
+
+The kernel command line parameters are persisted on the system, but this is not the case for other configurations.
+The IRQ and CPU governance are reset to the system defaults after a reboot.
+The rt-conf snap has a oneshot service which runs on every boot to re-apply the non-persistent configurations. 
+This service runs only once and stops immediately after setting the configurations.
+
+If re-applying non-persistent configurations on boot is not wanted, disable the service:
+```shell
+sudo snap stop --disable rt-conf
+```
+
+### Change configuration path
+
+The configuration file path can be changed with [snap configurations][snap-config].
+For example:
+```shell
+sudo snap set rt-conf config-file=/home/ubuntu/rt-conf/config.yaml
+```
+
+```{note}
+The configuration file must be in a location accessible to the snap, such as a user home directory.
+
+The file must be owned by and writable to root only.
+```
+
+To revert to the default path:
+```shell
+sudo snap unset rt-conf config-file
+```
+
+### Verbose logging
+
+To enable debug logging set:
+```shell
+sudo snap set rt-conf verbose=true
+```
+
+% Links
+[UC]: https://ubuntu.com/core
+[snap-config]: https://snapcraft.io/docs/configuration-in-snaps

docs/reference/index.rst

@@ -8,3 +8,4 @@ Reference
    kernel-boot-parameters
    kernel-config-options
    releases
+   rt-conf-yaml

docs/reference/kernel-boot-parameters.rst

@@ -1,8 +1,12 @@
+.. _kernel-boot-parameters:
+
 Kernel boot parameters
 ======================
 
 This document lists several kernel boot parameters that are useful for tuning Real-time Ubuntu.
 
+.. _reference-irqaffinity:
+
 irqaffinity
 -----------
 
@@ -16,6 +20,8 @@ The information in this file is presented in a hexadecimal representation of the
 
 Note that ``irqaffinity`` is a `symmetric multiprocessing`_ (SMP) parameter, and therefore it does not apply to systems with only one CPU.
 
+.. _reference-isolcpus:
+
 isolcpus
 --------
 
@@ -32,13 +38,17 @@ For example, ``isolcpus=1,2,10-20`` isolates CPUs 1, 2, and 10 through 20.
 
 For further details, please refer to `kernel's command-line parameters`_ documentation.
 
+.. _reference-kthread_cpus:
+
 kthread_cpus
 ------------
 
 The ``kthread_cpus`` parameter refers to the list of CPUs specifically allocated for kernel usage.
 
 For instance, specifying ``kthread_cpus=0-3`` means that the kernel is allowed to run kernel threads on CPUs 0 through 3.
 
+.. _reference-nohz:
+
 nohz
 ----
 

docs/reference/rt-conf-yaml.md

@@ -0,0 +1,162 @@
+# RT Conf YAML configuration schema
+
+The following schema reflects all settings available in the configuration file of the `rt-conf` tool
+
+There are three top-level dictionaries in the configuration file:, {ref}`kcmd`, {ref}`irqt` and {ref}`cpug`.
+
+(kcmd)=
+## kernel_cmdline
+
+Type: `dict`
+
+_Optional_
+
+### kernel_cmdline.parameters
+
+Type: `list[string]`
+
+_Optional_
+
+{ref}`kernel-boot-parameters` that affects real-time behavior.
+
+```{admonition} Validated parameters
+
+`rt-conf` performs syntax validation on all parameters names. 
+In addition, `rt-conf` carries out syntax validation on values of the parameters which are common for real-time tuning. These parameters are:
+
+- {ref}`irqaffinity <reference-irqaffinity>`
+- {ref}`isolcpus <reference-isolcpus>`
+- {ref}`kthread_cpus <reference-kthread_cpus>`
+- {ref}`nohz <reference-nohz>`
+- nohz_full
+- rcu_nocbs
+
+<!-- TODO: add references for nohz_full and rcu_nocbs -->
+```
+
+(irqt)=
+## irq_tuning 
+
+Type: `list[dict]`
+
+_Optional_
+
+A list of configurations including the list of cpus to be applied and the filters.
+Runtime configurations that aren't persisted, related to IRQ affinity tuning.
+
+Example:
+
+```yaml
+irq_tuning:
+  - cpus: "2-3"
+    filter:
+      actions: "iwlwifi"
+      chip_name: "IR-PCI"
+      name: "edge"
+      type: "edge"
+```
+
+### irq_tuning[*].cpus
+
+Type `string`
+
+_Required_
+
+A string formatted as {ref}`cpu-lists`. 
+Specifies the list of CPUs which will handle the matched IRQs on the {ref}`filter <irqfilter>`.
+
+(irqfilter)=
+### irq_tuning[*].filter
+
+Type: `dict`
+
+_Required_
+
+A dictionary with keys related to IRQ properties of `/sys/kernel/irq/<IRQ-num>/`.
+
+#### irq_tuning[*].filter.actions
+
+Type: `regex string`
+
+_Optional_
+
+The IRQ action chain. A comma-separated list of zero or more device names associated with this interrupt.
+For network related, generally is the name of the network interface shown in `ip link show`. 
+
+#### irq_tuning[*].filter.chip_name
+
+Type: `regex string`
+
+_Optional_
+
+Chip name supplied by the associated device driver.
+
+Example: `IR-PCI-MSIX-0000:04:00.0`
+
+#### irq_tuning[*].filter.name
+
+Type: `regex string`
+
+_Optional_
+
+Human-readable flow handler name as defined by the irq chip driver.
+Example values are:
+  * `edge`
+  * `fasteoi`
+
+#### irq_tuning[*].filter.type
+
+Type: `enum`
+
+_Optional_
+
+The type of the interrupt.
+Valid values:
+  * `edge`
+  * `level` 
+
+(cpug)=
+## cpu_governance
+
+Type: `list[dict]`
+
+_Optional_
+
+Runtime configurations that aren't persisted, related to cpu power management.
+A list of dictionaries with the CPU scaling governor and the cpu list to be applied.
+
+Example:
+
+```yaml
+cpu_governance: 
+  - cpus: "0-1"
+    scaling_governor: "performance"
+```
+
+### cpu_governance[*].cpus
+
+Type: `string`
+
+_Required_
+
+A string formatted as {ref}`cpu-lists`. 
+Specifies which cpus are going to be configured with the scaling governor specified in the item.
+
+
+### cpu_governance[*].scaling_governor
+
+Type: `string`
+
+_Required_
+
+The chosen scaling governor.
+
+Valid values:
+  * `performance`: Run the CPU at the maximum frequency, get from `/sys/devices/system/cpu/cpuX/cpufreq/scaling_max_freq`.
+  * `powersave`: Run the CPU at the minimum frequency, get from `/sys/devices/system/cpu/cpuX/cpufreq/scaling_min_freq`. 
+  * `userspace`: Run the CPU at user specified frequencies, configurable via `/sys/devices/system/cpu/cpuX/cpufreq/scaling_setspeed`. 
+  * `ondemand`: Scales the frequency dynamically according to current load. Jumps to the highest frequency and then possibly back off as the idle time increases.
+  * `conservative`: Scales the frequency dynamically according to current load (more gradually than ondemand).
+  * `schedutil`: [Scheduler-driven](https://lwn.net/Articles/682391/) CPU frequency selection.
+
+