From 9ab4bab2ed13bfc234061062c8be46cc781abb4d Mon Sep 17 00:00:00 2001 From: Lincoln Wallace Date: Fri, 21 Mar 2025 04:48:13 -0300 Subject: [PATCH 1/4] doc: add reference for rt-conf tool config.yaml (#95) --- docs/.custom_wordlist.txt | 1 + docs/how-to/cpu-boot-configs.rst | 2 + docs/reference/index.rst | 1 + docs/reference/kernel-boot-parameters.rst | 2 + docs/reference/rt-conf-yaml.md | 190 ++++++++++++++++++++++ 5 files changed, 196 insertions(+) create mode 100644 docs/reference/rt-conf-yaml.md diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 9495deee..6f53d508 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -191,6 +191,7 @@ mutex mutexes ng nohz +ondemand optimization oslat osnoise diff --git a/docs/how-to/cpu-boot-configs.rst b/docs/how-to/cpu-boot-configs.rst index 8cbd029e..58e85df4 100644 --- a/docs/how-to/cpu-boot-configs.rst +++ b/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 --------- diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 338f2794..72ff7279 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -8,3 +8,4 @@ Reference kernel-boot-parameters kernel-config-options releases + rt-conf-yaml diff --git a/docs/reference/kernel-boot-parameters.rst b/docs/reference/kernel-boot-parameters.rst index c87b359e..f312d7df 100644 --- a/docs/reference/kernel-boot-parameters.rst +++ b/docs/reference/kernel-boot-parameters.rst @@ -1,3 +1,5 @@ +.. _kernel-boot-parameters: + Kernel boot parameters ====================== diff --git a/docs/reference/rt-conf-yaml.md b/docs/reference/rt-conf-yaml.md new file mode 100644 index 00000000..35202127 --- /dev/null +++ b/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)= +### irq_tuning[*].filter + +Type: `dict` + +_Required_ + +A dictionary with keys related to IRQ properties of `/sys/kernel/irq//`. + +#### 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. + From de25bc837e55f26f4f7880ebea623c46ff9521c7 Mon Sep 17 00:00:00 2001 From: Lincoln Wallace Date: Fri, 29 Aug 2025 11:13:54 -0300 Subject: [PATCH 2/4] Update rt-conf yaml reference (#155) * feat: update rt-conf yaml reference Signed-off-by: Lincoln Wallace * chore(.custom_wordlist): ignore nocbs Signed-off-by: Lincoln Wallace * feat: put validated parameters information on an admonition note Signed-off-by: Lincoln Wallace * fix: change append -> parameters Signed-off-by: Lincoln Wallace * refact: improve explanation regarding validated values Co-authored-by: Farshid Tavakolizadeh Signed-off-by: Lincoln Wallace * feat: specify the type for the list itens Signed-off-by: Lincoln Wallace * fix: add period to end sentence Signed-off-by: Lincoln Wallace * feat!: drop url Signed-off-by: Lincoln Wallace * feat: add requirement level for kernel-cmdline.parameters key Signed-off-by: Lincoln Wallace * feat: drop table and add simple bulleted list with references Note that nohz_full and rcu_nocbs aren't present on the reference Signed-off-by: Lincoln Wallace --------- Signed-off-by: Lincoln Wallace Co-authored-by: Farshid Tavakolizadeh --- docs/.custom_wordlist.txt | 1 + docs/reference/kernel-boot-parameters.rst | 8 ++++ docs/reference/rt-conf-yaml.md | 58 ++++++----------------- 3 files changed, 24 insertions(+), 43 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 6f53d508..17f41954 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -48,6 +48,7 @@ Mutexes NMI NMIs NOCB +nocbs OSAL OSNOISE OSS diff --git a/docs/reference/kernel-boot-parameters.rst b/docs/reference/kernel-boot-parameters.rst index f312d7df..4fee81db 100644 --- a/docs/reference/kernel-boot-parameters.rst +++ b/docs/reference/kernel-boot-parameters.rst @@ -5,6 +5,8 @@ Kernel boot parameters This document lists several kernel boot parameters that are useful for tuning Real-time Ubuntu. +.. _reference-irqaffinity: + irqaffinity ----------- @@ -18,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 -------- @@ -34,6 +38,8 @@ 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 ------------ @@ -41,6 +47,8 @@ The ``kthread_cpus`` parameter refers to the list of CPUs specifically allocated 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 ---- diff --git a/docs/reference/rt-conf-yaml.md b/docs/reference/rt-conf-yaml.md index 35202127..18abe658 100644 --- a/docs/reference/rt-conf-yaml.md +++ b/docs/reference/rt-conf-yaml.md @@ -11,57 +11,28 @@ Type: `dict` _Optional_ -{ref}`kernel-boot-parameters` that affects real-time behavior +### kernel_cmdline.parameters - -### 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` +Type: `list[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 +{ref}`kernel-boot-parameters` that affects real-time behavior. -Type: `string` - -_Optional_ +```{admonition} Validated parameters -A string formatted as {ref}`cpu-lists`. -Specifies the list of CPUs to be allocated for kernel threads. +`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: -### kernel_cmdline.irqaffinity +- {ref}`irqaffinity ` +- {ref}`isolcpus ` +- {ref}`kthread_cpus ` +- {ref}`nohz ` +- nohz_full +- rcu_nocbs -Type: `string` - -_Optional_ - -A string formatted as {ref}`cpu-lists`. -Specifies the list of CPUs for IRQ handling. + +``` (irqt)= ## irq_tuning @@ -188,3 +159,4 @@ Valid values: * `conservative`: Scales the frequency dynamically according to current load (more gradually than ondemand). * `schedutil`: [Scheduler-driven](https://lwn.net/Articles/682391/) CPU frequency selection. + From 9a25fcb220be5f2d066cd3abcbbdc0572c1de734 Mon Sep 17 00:00:00 2001 From: Lincoln Wallace Date: Sun, 19 Oct 2025 12:04:22 -0300 Subject: [PATCH 3/4] feat: add how-to for rt-conf cli usage Signed-off-by: Lincoln Wallace --- docs/how-to/rt-conf-cli.md | 98 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/how-to/rt-conf-cli.md diff --git a/docs/how-to/rt-conf-cli.md b/docs/how-to/rt-conf-cli.md new file mode 100644 index 00000000..8e7fd367 --- /dev/null +++ b/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 From faf59ce205ada2025084f28fd7b88e6b507b0494 Mon Sep 17 00:00:00 2001 From: Lincoln Wallace Date: Sun, 19 Oct 2025 12:08:47 -0300 Subject: [PATCH 4/4] chore: add the rt-conf how-to on index Signed-off-by: Lincoln Wallace --- docs/how-to/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 2a1e8199..dcc29766 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -36,6 +36,7 @@ Configure Real-time Ubuntu Core: Create a Real-time Ubuntu Core image Install real-time kernel on Ubuntu Core + Tune Real-Time Ubuntu using rt-conf For tuning an existing Ubuntu Core system, refer to :ref:`ubuntu-core-kernel-cmdline`.