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:

sudo snap install rt-conf --beta --devmode

Developer mode

The snap must be installed with --devmode to allow IRQ configuration. This is due to issue #67.

When installed in developer mode, the snap will not update automatically. To force an update:

sudo snap refresh rt-conf

Grant access to allow GRUB configuration on a system that supports it:

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:

# Several fields use the CPU Lists format. 
# For the CPU Lists spec, refer to
# https://docs.kernel.org/admin-guide/kernel-parameters.html#cpu-lists

# Kernel command line parameters
# TODO add reboot requirement
kernel_cmdline:
  # Isolate CPUs from general execution
  # Format: CPU Lists
  # isolcpus: "2-3"

  # Enable/disable dynamic ticks during idle time
  # Supported values: on | off
  # nohz: "on"

  # Enable/disable full dynamic ticks
  # Format: CPU Lists
  # nohz_full: "2-3"

  # Allocated CPUs for kernel threads
  # Format: CPU Lists
  # kthread_cpus: "0-1"

  # Allocate CPUs for IRQ handling
  # Format: CPU Lists
  # irqaffinity: "0-1"

# Runtime options for IRQ affinity
irq_tuning:
  # - # CPUs to which the IRQs are to be moved
  #   # Format: range, e.g. 0-2
  #   cpus: "2-3"
  #   # Arguments used to filter IRQs
  #   filter:
  #     actions: "iwlwifi"
  #     chip_name: "IR-PCI"
  #     name: "edge"
  #     type: "edge"

# Runtime options for CPU frequency scaling
cpu_governance: 
  #  - # CPUs to which the scaling_governor options are to be applied
  #    # Format: CPU Lists
  #    cpus: "0-1"
  #    # CPU frequency scaling governor
  #    # Supported values depends on the system, typically: performance, powersave
  #    scaling_governor: "performance"
  #    # Minimum CPU frequency
  #    # Format: frequency with unit, one of "GHz", "MHz", "kHz", "Hz"
  #    min_freq: "1GHz"
  #    # Maximum CPU frequency
  #    # Format: same as min_frequency
  #    max_freq: "5.2gHz"

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 rt-conf YAML configuration schema for more details.

Run

Once ready with the configurations, run rt-conf:

sudo rt-conf

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. Instead, refer to Modify boot parameters on Ubuntu Core.

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:

sudo snap stop --disable rt-conf

Change configuration path

The configuration file path can be changed with snap configurations. For example:

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:

sudo snap unset rt-conf config-file

Verbose logging

To enable debug logging set:

sudo snap set rt-conf verbose=true