Add RT Conf documentation #98

farshidtz · 2025-03-21T07:53:34Z

PRs:

Completed docs:

Reference / RT Conf YAML configuration schema
How to tune Real-time Ubuntu using rt-conf

The snap must be released to beta before publishing this doc.

Preview

EdoardoBarbieriCanonical

Added minor comments.

EdoardoBarbieriCanonical · 2025-07-11T08:31:16Z

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

+# 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. 


Should we state "[...] on Ubuntu with the real-time kernel" / "[...] on Real-time Ubuntu"? I know it's already in the title, so maybe it's repetitive.

i agree. either of @EdoardoBarbieriCanonical 's suggestion works.
it would be helpful for SEO since your keywords should be featured at the start of your doc / guide.

EdoardoBarbieriCanonical · 2025-07-11T08:32:10Z

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

+
+````{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). 


What's the expected timeframe for fixing this bug?

EdoardoBarbieriCanonical · 2025-07-11T08:33:38Z

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

+```{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]. 


Is the word "parameters" missing here?

EdoardoBarbieriCanonical · 2025-07-11T08:38:08Z

docs/reference/rt-conf-yaml.md

+_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`. 


I don't find the second sentence very clear. Do you mean to say "For network-related purposes, the IRQ action chain is generally the name of the network interface, shown in ip link show."?

AnneCYH · 2025-07-24T03:19:11Z

docs/how-to/index.rst

   Tune IRQ affinity <tune-irq-affinity>
   Isolate CPUs from general execution with cpusets <isolate-workload-cpusets>
-
+   Tune Real-Time Ubuntu using rt-conf <rt-conf-cli>


Suggested change

Tune Real-Time Ubuntu using rt-conf <rt-conf-cli>

Tune Real-time Ubuntu using rt-conf <rt-conf-cli>

AnneCYH · 2025-07-24T03:22:33Z

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

 For that, refer to :doc:`modify-kernel-boot-parameters`.


+.. _cpu-lists:


we don't necessarily need a fix here.
but i think we should have a better structure for naming our targets.
as the doc set grows we can run into conflicts since similar headings can easily appear across pages.

E.g. cpu-configs-cpu-lists or something along this convention would be a more robust target.

AnneCYH · 2025-07-24T03:25:15Z

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

@@ -0,0 +1,103 @@
+# How-to tune Real-Time Ubuntu using rt-conf


Suggested change

# How-to tune Real-Time Ubuntu using rt-conf

# How-to tune Real-time Ubuntu using rt-conf

AnneCYH · 2025-07-24T03:30:34Z

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

@@ -0,0 +1,103 @@
+# How-to tune Real-Time Ubuntu using rt-conf
+
+*rt-conf* is a tool that helps users tune their system for real-time responsiveness. 


we don't typically italicize the tool names.

Also would you want to link to the rt-conf repo as part of this intro?
https://github.com/canonical/rt-conf

AnneCYH · 2025-07-24T03:34:56Z

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

+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.


Suggested change

This file is removed when uninstalling the rt-conf snap.

This file is removed when you uninstall the rt-conf snap.

AnneCYH · 2025-07-24T03:35:10Z

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

+```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`.


Suggested change

rt-conf uses this access to write a drop-in GRUB config file at `/etc/default/grub.d/60_rt-conf.cfg`.

rt-conf uses this access to write a drop-in GRUB config file at {file}`/etc/default/grub.d/60_rt-conf.cfg`.

AnneCYH · 2025-07-24T03:35:22Z

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

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


Suggested change

AnneCYH · 2025-07-24T03:36:13Z

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

@@ -0,0 +1,103 @@
+# How-to tune Real-Time Ubuntu using rt-conf
+
+*rt-conf* is a tool that helps users tune their system for real-time responsiveness. 


Suggested change

*rt-conf* is a tool that helps users tune their system for real-time responsiveness.

*rt-conf* is a tool that can be used to tune your system for real-time responsiveness.

Speaking to the user.

AnneCYH · 2025-07-24T03:38:45Z

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

+# 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. 


Suggested change

This guide describes how to install and use it on Ubuntu.

This guide describes how to install and use it on Real-time Ubuntu.

AnneCYH · 2025-07-24T04:10:45Z

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

+
+The default configuration file is located at `/var/snap/rt-conf/common/config.yaml`:
+
+```{literalinclude} rt-conf-config.yaml


I don't think it's a good idea to maintain this file here since it can change upstream in rt-conf without warning -- unless we want to keep this version a little different from the upstream one?

I would suggest pulling this file into real-time-ubuntu from upstream since it's a literal include without further explanation / annotations / modifications in the YAML file itself.

We can copy the file over each time the doc builds with the urllib library.

Add this to the "import" section of conf.py:
from urllib.request import urlretrieve

Add this towards the end of conf.py:
# Import files from external URLs urlretrieve ( "https://raw.githubusercontent.com/canonical/rt-conf/refs/heads/main/config.yaml", "how-to/rt-conf-config.yaml" )

I agree that this isn't ideal.

The config file that is in the main branch of the source may not always be compatible with the revisions users install from latest/stable. Main branch is usually ahead, with newer additions.

As discussed, I'll drop the full config example and try to add smaller excerpts to the reference.

AnneCYH · 2025-07-24T04:16:29Z

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

+sudo snap stop --disable rt-conf
+```
+
+### Change configuration path


i think the section on "Change configuration file path" should be under the "Configure" section instead of "Run.

AnneCYH · 2025-07-24T04:16:44Z

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

+sudo snap stop --disable rt-conf
+```
+
+### Change configuration path


Suggested change

### Change configuration path

### Change configuration file path

suggest moving it up.

AnneCYH · 2025-07-24T04:17:34Z

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

+```
+
+```{note}
+The configuration file must be in a location accessible to the snap, such as a user home directory.


Suggested change

The configuration file must be in a location accessible to the snap, such as a user home directory.

The configuration file must be in a location accessible to the snap, such as a user's home directory.

AnneCYH

hey @farshidtz , just some suggestions for your consideration.
Thanks!

AnneCYH

Hey @farshidtz , thanks for this.
I left some comments; do consider and lemme know if you have any questions, thanks!

AnneCYH · 2025-07-24T09:10:10Z

docs/reference/rt-conf-yaml.md

@@ -0,0 +1,208 @@
+# rt-conf YAML configuration schema
+
+The following schema reflects all settings available in the configuration file of the `rt-conf` tool


Suggested change

The following schema reflects all settings available in the configuration file of the `rt-conf` tool

The following schema reflects all settings available in the configuration file of the `rt-conf` tool.

AnneCYH · 2025-07-24T09:14:51Z

docs/reference/rt-conf-yaml.md

+
+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`.


Suggested change

There are three top-level dictionaries in the configuration file:, {ref}`kcmd`, {ref}`irqt` and {ref}`cpug`.

There are three top-level dictionaries in the configuration file: {ref}`kcmd`, {ref}`irqt` and {ref}`cpug`.

AnneCYH · 2025-07-24T09:27:22Z

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

@@ -0,0 +1,103 @@
+# How-to tune Real-Time Ubuntu using rt-conf


Suggested change

# How-to tune Real-Time Ubuntu using rt-conf

(tune-rt-conf)=

# How-to tune Real-Time Ubuntu using rt-conf

AnneCYH · 2025-07-24T09:27:54Z

docs/reference/rt-conf-yaml.md

+# rt-conf YAML configuration schema
+
+The following schema reflects all settings available in the configuration file of the `rt-conf` tool
+


Suggested change

```{seealso}

- {ref}`tune-rt-conf`

```

AnneCYH · 2025-07-24T09:47:35Z

docs/reference/rt-conf-yaml.md

+
+_Optional_
+
+{ref}`kernel-boot-parameters` that affects real-time behavior


Suggested change

{ref}`kernel-boot-parameters` that affects real-time behavior

{ref}`kernel-boot-parameters` that affect real-time behavior.

AnneCYH · 2025-07-25T09:13:46Z

docs/reference/rt-conf-yaml.md

+
+Human-readable flow handler name as defined by the irq chip driver.
+Example values are:
+  * `edge`


the potential values are arbitary right? as in anything is possible?

AnneCYH · 2025-07-25T09:14:28Z

docs/reference/rt-conf-yaml.md

+
+_Optional_
+
+Runtime configurations that aren't persisted, related to cpu power management.


Same comment as previously. I am not clear how these 2 sentences are "connected". I am missing something but it's not clear what.

AnneCYH · 2025-07-25T09:14:48Z

docs/reference/rt-conf-yaml.md

+_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.


Suggested change

A list of dictionaries with the CPU scaling governor and the cpu list to be applied.

A list of dictionaries with the CPU scaling governor and the CPU list to be applied.

Anyways please do a quick search-and-replace to keep the use of CPU consistent.

AnneCYH · 2025-07-25T09:15:38Z

docs/reference/rt-conf-yaml.md

+_Required_
+
+A string formatted as {ref}`cpu-lists`. 
+Specifies which cpus are going to be configured with the scaling governor specified in the item.


I'll limit my comments but reword to say what the user does with the command. Do apply this to the rest of the params.

Suggested change

Specifies which cpus are going to be configured with the scaling governor specified in the item.

Specify which CPUs are going to be configured with the scaling governor specified in the item.

AnneCYH · 2025-07-25T09:16:07Z

docs/reference/rt-conf-yaml.md

+
+_Required_
+
+The chosen scaling governor.


Suggested change

The chosen scaling governor.

Chose the scaling governor.

* feat: update rt-conf yaml reference Signed-off-by: Lincoln Wallace <[email protected]> * chore(.custom_wordlist): ignore nocbs Signed-off-by: Lincoln Wallace <[email protected]> * feat: put validated parameters information on an admonition note Signed-off-by: Lincoln Wallace <[email protected]> * fix: change append -> parameters Signed-off-by: Lincoln Wallace <[email protected]> * refact: improve explanation regarding validated values Co-authored-by: Farshid Tavakolizadeh <[email protected]> Signed-off-by: Lincoln Wallace <[email protected]> * feat: specify the type for the list itens Signed-off-by: Lincoln Wallace <[email protected]> * fix: add period to end sentence Signed-off-by: Lincoln Wallace <[email protected]> * feat!: drop url Signed-off-by: Lincoln Wallace <[email protected]> * feat: add requirement level for kernel-cmdline.parameters key Signed-off-by: Lincoln Wallace <[email protected]> * 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 <[email protected]> --------- Signed-off-by: Lincoln Wallace <[email protected]> Co-authored-by: Farshid Tavakolizadeh <[email protected]>

farshidtz · 2025-10-19T14:10:40Z

@locnnil looks like the how-to (docs/how-to/rt-conf-cli.md) has gone missing with the history rewrites. Please recover it.

Signed-off-by: Lincoln Wallace <[email protected]>

locnnil force-pushed the rt-conf branch 2 times, most recently from df9840f to d7ccef2 Compare April 2, 2025 18:25

farshidtz requested a review from odadacharles April 3, 2025 12:27

farshidtz removed the request for review from odadacharles June 30, 2025 14:23

farshidtz marked this pull request as ready for review July 3, 2025 16:10

farshidtz requested review from AnneCYH and EdoardoBarbieriCanonical July 3, 2025 16:11

EdoardoBarbieriCanonical reviewed Jul 11, 2025

View reviewed changes

AnneCYH reviewed Jul 24, 2025

View reviewed changes

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

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

```

Copy link

Collaborator

AnneCYH Jul 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

AnneCYH reviewed Jul 24, 2025

View reviewed changes

AnneCYH requested changes Jul 24, 2025

View reviewed changes

AnneCYH requested changes Jul 25, 2025

View reviewed changes

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

9ab4bab

locnnil force-pushed the rt-conf branch from 7e6c4dc to 9ab4bab Compare August 27, 2025 13:18

locnnil and others added 3 commits August 27, 2025 13:04

Merge branch 'main' into rt-conf

bb08f77

Merge branch 'main' into rt-conf

21a071d

farshidtz marked this pull request as draft October 19, 2025 14:08

locnnil added 3 commits October 19, 2025 12:01

Merge branch 'main' into rt-conf

432195e

feat: add how-to for rt-conf cli usage

9a25fcb

Signed-off-by: Lincoln Wallace <[email protected]>

chore: add the rt-conf how-to on index

faf59ce

Signed-off-by: Lincoln Wallace <[email protected]>

	Tune Real-Time Ubuntu using rt-conf <rt-conf-cli>
	Tune Real-time Ubuntu using rt-conf <rt-conf-cli>

		For that, refer to :doc:`modify-kernel-boot-parameters`.


		.. _cpu-lists:

		@@ -0,0 +1,103 @@
		# How-to tune Real-Time Ubuntu using rt-conf

		@@ -0,0 +1,103 @@
		# 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 file is removed when uninstalling the rt-conf snap.
	This file is removed when you uninstall the rt-conf snap.

	rt-conf uses this access to write a drop-in GRUB config file at `/etc/default/grub.d/60_rt-conf.cfg`.
	rt-conf uses this access to write a drop-in GRUB config file at {file}`/etc/default/grub.d/60_rt-conf.cfg`.

	rt-conf is a tool that helps users tune their system for real-time responsiveness.
	rt-conf is a tool that can be used to tune your system for real-time responsiveness.

	This guide describes how to install and use it on Ubuntu.
	This guide describes how to install and use it on Real-time Ubuntu.


		The default configuration file is located at `/var/snap/rt-conf/common/config.yaml`:

		```{literalinclude} rt-conf-config.yaml

	### Change configuration path
	### Change configuration file path

	The configuration file must be in a location accessible to the snap, such as a user home directory.
	The configuration file must be in a location accessible to the snap, such as a user's home directory.

		@@ -0,0 +1,208 @@
		# rt-conf YAML configuration schema

		The following schema reflects all settings available in the configuration file of the `rt-conf` tool


		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`.

	# How-to tune Real-Time Ubuntu using rt-conf
	(tune-rt-conf)=
	# How-to tune Real-Time Ubuntu using rt-conf

+```{seealso}
+- {ref}`tune-rt-conf`
+```


		_Optional_

		{ref}`kernel-boot-parameters` that affects real-time behavior


		_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.
	A list of dictionaries with the CPU scaling governor and the CPU list to be applied.

	Specifies which cpus are going to be configured with the scaling governor specified in the item.
	Specify which CPUs are going to be configured with the scaling governor specified in the item.

Add RT Conf documentation #98

Are you sure you want to change the base?

Add RT Conf documentation #98

Uh oh!

Conversation

farshidtz commented Mar 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EdoardoBarbieriCanonical left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

farshidtz Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnneCYH left a comment

Choose a reason for hiding this comment

Uh oh!

AnneCYH left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

farshidtz commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

farshidtz commented Mar 21, 2025 •

edited

Loading

farshidtz Jul 24, 2025 •

edited

Loading

farshidtz commented Oct 19, 2025 •

edited

Loading