diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index f5ba7de8..dfa3211f 100644 --- a/docs/.custom_wordlist.txt +++ b/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 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/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`. 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 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..4fee81db 100644 --- a/docs/reference/kernel-boot-parameters.rst +++ b/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,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 ------------ @@ -39,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 new file mode 100644 index 00000000..18abe658 --- /dev/null +++ b/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 ` +- {ref}`isolcpus ` +- {ref}`kthread_cpus ` +- {ref}`nohz ` +- nohz_full +- 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)= +### 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. + +