doc: add reference for rt-conf tool config.yaml (#95)

Author: locnnil

docs/.custom_wordlist.txt

@@ -104,6 +104,7 @@ NMI
 NMIs
 NOCB
 nohz
+ondemand
 optimization
 OSAL
 oslat

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/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,3 +1,5 @@
+.. _kernel-boot-parameters:
+
 Kernel boot parameters
 ======================
 

docs/reference/rt-conf-yaml.md

@@ -0,0 +1,190 @@
+# 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_
+
+{ref}`kernel-boot-parameters` that affects real-time behavior
+
+
+### kernel_cmdline.isolcpus
+
+Type: `string`
+
+_Optional_
+
+A string formatted as {ref}`cpu-lists`. 
+Isolate CPUs from general execution.
+
+### kernel_cmdline.nohz
+
+Type: `enum`
+
+_Optional_
+
+Enable/disable dynamic ticks during idle time.
+
+Valid values are:
+  * `on`: **Enables** dynamic ticks
+  * `off`:**Disables** dynamic ticks
+
+### kernel_cmdline.nohz_full
+
+Type: `string`
+
+_Optional_
+
+A string formatted as {ref}`cpu-lists`. 
+Specifies the adaptive-ticks cpus, which means the specified list of CPUs whose tick will be stopped whenever possible.
+The boot CPU will be forced outside the range to maintain the timekeeping.
+
+### kernel_cmdline.kthread_cpus
+
+Type: `string`
+
+_Optional_
+
+A string formatted as {ref}`cpu-lists`. 
+Specifies the list of CPUs to be allocated for kernel threads.
+
+### kernel_cmdline.irqaffinity
+
+Type: `string`
+
+_Optional_
+
+A string formatted as {ref}`cpu-lists`. 
+Specifies the list of CPUs for IRQ handling.
+
+(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.
+