Add a script for generation of plugin docs from docstrings
The script simply joins an introduction text with the docstrings of all plugin classes.
This commit is contained in:
Pavol Žáčik
parent
c082797fd0
commit
71b41394e2
6 changed files with 47 additions and 243 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -3,3 +3,4 @@
|
||||||
tuned-*.tar.bz2
|
tuned-*.tar.bz2
|
||||||
*~
|
*~
|
||||||
*.html
|
*.html
|
||||||
|
doc/manual/modules/performance/ref_available-tuned-plug-ins.adoc
|
||||||
|
|
|
||||||
2
Makefile
2
Makefile
|
|
@ -68,7 +68,7 @@ release-cp: release-dir
|
||||||
tuned-adm.bash dbus.conf recommend.conf tuned-main.conf 00_tuned \
|
tuned-adm.bash dbus.conf recommend.conf tuned-main.conf 00_tuned \
|
||||||
92-tuned.install bootcmdline modules.conf com.redhat.tuned.policy \
|
92-tuned.install bootcmdline modules.conf com.redhat.tuned.policy \
|
||||||
tuned-gui.py tuned-gui.glade tuned-ppd.py \
|
tuned-gui.py tuned-gui.glade tuned-ppd.py \
|
||||||
tuned-gui.desktop functions $(VERSIONED_NAME)
|
tuned-gui.desktop functions compile_plugin_docs.py $(VERSIONED_NAME)
|
||||||
cp -a doc experiments libexec man profiles systemtap tuned contrib icons \
|
cp -a doc experiments libexec man profiles systemtap tuned contrib icons \
|
||||||
tests $(VERSIONED_NAME)
|
tests $(VERSIONED_NAME)
|
||||||
|
|
||||||
|
|
|
||||||
36
compile_plugin_docs.py
Normal file
36
compile_plugin_docs.py
Normal file
|
|
@ -0,0 +1,36 @@
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import os
|
||||||
|
import inspect
|
||||||
|
from tuned.utils.plugin_loader import PluginLoader
|
||||||
|
from tuned.plugins.base import Plugin
|
||||||
|
|
||||||
|
|
||||||
|
class DocLoader(PluginLoader):
|
||||||
|
def __init__(self):
|
||||||
|
super(DocLoader, self).__init__()
|
||||||
|
|
||||||
|
def _set_loader_parameters(self):
|
||||||
|
self._namespace = "tuned.plugins"
|
||||||
|
self._prefix = "plugin_"
|
||||||
|
self._interface = Plugin
|
||||||
|
|
||||||
|
parser = argparse.ArgumentParser()
|
||||||
|
parser.add_argument("intro")
|
||||||
|
parser.add_argument("out")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
with open(args.intro, "r") as intro_file:
|
||||||
|
intro = intro_file.read()
|
||||||
|
|
||||||
|
all_plugins = sorted(DocLoader().load_all_plugins(), key=lambda x: x.__module__)
|
||||||
|
|
||||||
|
with open(args.out, "w") as out_file:
|
||||||
|
out_file.write(intro)
|
||||||
|
for plugin in all_plugins:
|
||||||
|
plugin_file = inspect.getfile(plugin)
|
||||||
|
plugin_name = os.path.basename(plugin_file)[7:-3]
|
||||||
|
out_file.write("\n")
|
||||||
|
out_file.write(f"== **{plugin_name}**\n")
|
||||||
|
out_file.write(inspect.cleandoc(plugin.__doc__))
|
||||||
|
out_file.write("\n")
|
||||||
|
|
@ -1,10 +1,12 @@
|
||||||
.PHONY: clean
|
.PHONY: clean
|
||||||
|
|
||||||
index.html: master.adoc assemblies/*.adoc meta/*.adoc modules/performance/*.adoc
|
index.html: master.adoc assemblies/*.adoc meta/*.adoc modules/performance/*.adoc ../../tuned/plugins/plugin_*.py
|
||||||
|
python3 ../../compile_plugin_docs.py modules/performance/ref_available-tuned-plug-ins_intro.adoc modules/performance/ref_available-tuned-plug-ins.adoc
|
||||||
asciidoctor -o index.html master.adoc || asciidoc -o index.html master.adoc
|
asciidoctor -o index.html master.adoc || asciidoc -o index.html master.adoc
|
||||||
|
|
||||||
install: index.html
|
install: index.html
|
||||||
install -Dpm 0644 index.html $(DESTDIR)$(DOCDIR)/manual/index.html
|
install -Dpm 0644 index.html $(DESTDIR)$(DOCDIR)/manual/index.html
|
||||||
|
|
||||||
clean:
|
clean:
|
||||||
|
rm -f modules/performance/ref_available-tuned-plug-ins.adoc
|
||||||
rm -f *.html
|
rm -f *.html
|
||||||
|
|
|
||||||
|
|
@ -1,241 +0,0 @@
|
||||||
:_module-type: REFERENCE
|
|
||||||
[id="available-tuned-plug-ins_{context}"]
|
|
||||||
= Available TuneD plug-ins
|
|
||||||
|
|
||||||
[role="_abstract"]
|
|
||||||
This section lists all monitoring and tuning plug-ins currently available in *TuneD*.
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
== Monitoring plug-ins
|
|
||||||
|
|
||||||
Currently, the following monitoring plug-ins are implemented:
|
|
||||||
|
|
||||||
`disk`::
|
|
||||||
Gets disk load (number of IO operations) per device and measurement interval.
|
|
||||||
|
|
||||||
`net`::
|
|
||||||
Gets network load (number of transferred packets) per network card and measurement interval.
|
|
||||||
|
|
||||||
`load`::
|
|
||||||
Gets CPU load per CPU and measurement interval.
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
== Tuning plug-ins
|
|
||||||
|
|
||||||
Currently, the following tuning plug-ins are implemented. Only some of these plug-ins implement dynamic tuning. Options supported by plug-ins are also listed:
|
|
||||||
|
|
||||||
`cpu`::
|
|
||||||
Sets the CPU governor to the value specified by the [option]`governor` option and dynamically changes the Power Management Quality of Service (PM QoS) CPU Direct Memory Access (DMA) latency according to the CPU load.
|
|
||||||
+
|
|
||||||
If the CPU load is lower than the value specified by the [option]`load_threshold` option, the latency is set to the value specified by the [option]`latency_high` option, otherwise it is set to the value specified by [option]`latency_low`.
|
|
||||||
+
|
|
||||||
You can also force the latency to a specific value and prevent it from dynamically changing further. To do so, set the [option]`force_latency` option to the required latency value.
|
|
||||||
|
|
||||||
`eeepc_she`::
|
|
||||||
Dynamically sets the front-side bus (FSB) speed according to the CPU load.
|
|
||||||
+
|
|
||||||
This feature can be found on some netbooks and is also known as the ASUS Super Hybrid Engine (SHE).
|
|
||||||
+
|
|
||||||
If the CPU load is lower or equal to the value specified by the [option]`load_threshold_powersave` option, the plug-in sets the FSB speed to the value specified by the [option]`she_powersave` option. If the CPU load is higher or equal to the value specified by the [option]`load_threshold_normal` option, it sets the FSB speed to the value specified by the [option]`she_normal` option.
|
|
||||||
+
|
|
||||||
Static tuning is not supported and the plug-in is transparently disabled if *TuneD* does not detect the hardware support for this feature.
|
|
||||||
|
|
||||||
`net`::
|
|
||||||
Configures the Wake-on-LAN functionality to the values specified by the [option]`wake_on_lan` option. It uses the same syntax as the `ethtool` utility. It also dynamically changes the interface speed according to the interface utilization.
|
|
||||||
|
|
||||||
`sysctl`::
|
|
||||||
Sets various `sysctl` settings specified by the plug-in options.
|
|
||||||
+
|
|
||||||
The syntax is ``[replaceable]__name__=[replaceable]__value__``, where [replaceable]_name_ is the same as the name provided by the `sysctl` utility.
|
|
||||||
+
|
|
||||||
Use the `sysctl` plug-in if you need to change system settings that are not covered by other plug-ins available in *TuneD*. If the settings are covered by some specific plug-ins, prefer these plug-ins.
|
|
||||||
|
|
||||||
`usb`::
|
|
||||||
Sets autosuspend timeout of USB devices to the value specified by the [option]`autosuspend` parameter.
|
|
||||||
+
|
|
||||||
The value `0` means that autosuspend is disabled.
|
|
||||||
|
|
||||||
`vm`::
|
|
||||||
Enables or disables transparent huge pages depending on the Boolean value of the [option]`transparent_hugepages` option.
|
|
||||||
+
|
|
||||||
Valid values of the [option]`transparent_hugepages` option are:
|
|
||||||
+
|
|
||||||
--
|
|
||||||
* "always"
|
|
||||||
* "never"
|
|
||||||
* "madvise"
|
|
||||||
--
|
|
||||||
|
|
||||||
`audio`::
|
|
||||||
Sets the autosuspend timeout for audio codecs to the value specified by the [option]`timeout` option.
|
|
||||||
+
|
|
||||||
Currently, the `snd_hda_intel` and `snd_ac97_codec` codecs are supported. The value `0` means that the autosuspend is disabled. You can also enforce the controller reset by setting the Boolean option [option]`reset_controller` to `true`.
|
|
||||||
|
|
||||||
`disk`::
|
|
||||||
Sets the disk elevator to the value specified by the [option]`elevator` option.
|
|
||||||
+
|
|
||||||
It also sets:
|
|
||||||
+
|
|
||||||
--
|
|
||||||
* APM to the value specified by the [option]`apm` option
|
|
||||||
* Scheduler quantum to the value specified by the [option]`scheduler_quantum` option
|
|
||||||
* Disk spindown timeout to the value specified by the [option]`spindown` option
|
|
||||||
* Disk readahead to the value specified by the [option]`readahead` parameter
|
|
||||||
* The current disk readahead to a value multiplied by the constant specified by the [option]`readahead_multiply` option
|
|
||||||
--
|
|
||||||
+
|
|
||||||
In addition, this plug-in dynamically changes the advanced power management and spindown timeout setting for the drive according to the current drive utilization. The dynamic tuning can be controlled by the Boolean option [option]`dynamic` and is enabled by default.
|
|
||||||
|
|
||||||
`scsi_host`::
|
|
||||||
Tunes options for SCSI hosts.
|
|
||||||
+
|
|
||||||
It sets Aggressive Link Power Management (ALPM) to the value specified by the [option]`alpm` option.
|
|
||||||
|
|
||||||
`mounts`::
|
|
||||||
Enables or disables barriers for mounts according to the Boolean value of the [option]`disable_barriers` option.
|
|
||||||
|
|
||||||
`scheduler`::
|
|
||||||
Allows tuning of scheduling priorities, processes/threads/IRQs affinities, and CPU cores isolation.
|
|
||||||
+
|
|
||||||
The scheduler plugin uses perf event loop to catch newly created processes. By default it listens to perf.RECORD_COMM and
|
|
||||||
perf.RECORD_EXIT events. By setting `perf_process_fork` parameter to `true`, perf.RECORD_FORK events will be also listened to.
|
|
||||||
In other words, child processes created by the fork() system call will be processed. Since child processes inherit CPU affinity
|
|
||||||
from their parents, the `scheduler` plugin usually does not need to explicitly process these events. As processing perf events
|
|
||||||
can pose a significant CPU overhead, the `perf_process_fork` parameter is set to `false` by default and child processes
|
|
||||||
are not processed by the scheduler plugin.
|
|
||||||
+
|
|
||||||
For perf events mmapped buffer is used. Under heavy load the buffer may overflow. In such cases the `scheduler` plugin
|
|
||||||
may start missing events and not process some newly created processes. Increasing the buffer size may help. The buffer size
|
|
||||||
can be set with the `perf_mmap_pages` parameter. Value of this parameter has to be power of 2. If it is not the power of 2,
|
|
||||||
the nearest bigger power of 2 value is calculated from it and this calculated value is used. If the `perf_mmap_pages`
|
|
||||||
parameter is omitted, the default kernel value is used, which should be 128 for the recent kernels (tested on kernel-5.9.8).
|
|
||||||
+
|
|
||||||
The `default_irq_smp_affinity` parameter controls the values *TuneD* writes to `/proc/irq/default_smp_affinity`.
|
|
||||||
The following values are supported:
|
|
||||||
+
|
|
||||||
--
|
|
||||||
`calc`::
|
|
||||||
Content of `/proc/irq/default_smp_affinity` will be calculated from the `isolated_cores` parameter.
|
|
||||||
Non-isolated cores are calculated as an inversion of the `isolated_cores`. Then the intersection of the non-isolated cores
|
|
||||||
and the previous content of `/proc/irq/default_smp_affinity` is written to `/proc/irq/default_smp_affinity`.
|
|
||||||
If the intersection is an empty set, then just the non-isolated cores are written to `/proc/irq/default_smp_affinity`.
|
|
||||||
This behavior is the default if the parameter `default_irq_smp_affinity` is omitted.
|
|
||||||
`ignore`::
|
|
||||||
*TuneD* will not touch `/proc/irq/default_smp_affinity`.
|
|
||||||
cpulist such as `1,3-4`::
|
|
||||||
The cpulist is unpacked and written directly to `/proc/irq/default_smp_affinity`.
|
|
||||||
--
|
|
||||||
|
|
||||||
`script`::
|
|
||||||
Executes an external script or binary when the profile is loaded or unloaded. You can choose an arbitrary executable.
|
|
||||||
+
|
|
||||||
IMPORTANT: The `script` plug-in is provided mainly for compatibility with earlier releases. Prefer other *TuneD* plug-ins if they cover the required functionality.
|
|
||||||
+
|
|
||||||
*TuneD* calls the executable with one of the following arguments:
|
|
||||||
+
|
|
||||||
--
|
|
||||||
** `start` when loading the profile
|
|
||||||
** `stop` when unloading the profile
|
|
||||||
--
|
|
||||||
+
|
|
||||||
You need to correctly implement the `stop` action in your executable and revert all settings that you changed during the `start` action. Otherwise, the roll-back step after changing your *TuneD* profile will not work.
|
|
||||||
+
|
|
||||||
Bash scripts can import the [filename]`/usr/lib/tuned/functions` Bash library and use the functions defined there. Use these functions only for functionality that is not natively provided by *TuneD*. If a function name starts with an underscore, such as `_wifi_set_power_level`, consider the function private and do not use it in your scripts, because it might change in the future.
|
|
||||||
+
|
|
||||||
Specify the path to the executable using the `script` parameter in the plug-in configuration.
|
|
||||||
+
|
|
||||||
.Running a Bash script from a profile
|
|
||||||
====
|
|
||||||
To run a Bash script named `script.sh` that is located in the profile directory, use:
|
|
||||||
|
|
||||||
----
|
|
||||||
[script]
|
|
||||||
script=${i:PROFILE_DIR}/script.sh
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
`sysfs`::
|
|
||||||
Sets various `sysfs` settings specified by the plug-in options.
|
|
||||||
+
|
|
||||||
The syntax is ``[replaceable]__name__=[replaceable]__value__``, where [replaceable]_name_ is the `sysfs` path to use.
|
|
||||||
+
|
|
||||||
Use this plugin in case you need to change some settings that are not covered by other plug-ins. Prefer specific plug-ins if they cover the required settings.
|
|
||||||
|
|
||||||
`video`::
|
|
||||||
Sets various powersave levels on video cards. Currently, only the Radeon cards are supported.
|
|
||||||
+
|
|
||||||
The powersave level can be specified by using the [option]`radeon_powersave` option. Supported values are:
|
|
||||||
+
|
|
||||||
--
|
|
||||||
* `default`
|
|
||||||
* `auto`
|
|
||||||
* `low`
|
|
||||||
* `mid`
|
|
||||||
* `high`
|
|
||||||
* `dynpm`
|
|
||||||
* `dpm-battery`
|
|
||||||
* `dpm-balanced`
|
|
||||||
* `dpm-perfomance`
|
|
||||||
--
|
|
||||||
+
|
|
||||||
For details, see link:http://www.x.org/wiki/RadeonFeature#KMS_Power_Management_Options[www.x.org]. Note that this plug-in is experimental and the option might change in future releases.
|
|
||||||
|
|
||||||
`bootloader`::
|
|
||||||
Adds options to the kernel command line. This plug-in supports only the GRUB 2 boot loader.
|
|
||||||
+
|
|
||||||
Customized non-standard location of the GRUB 2 configuration file can be specified by the [option]`grub2_cfg_file` option.
|
|
||||||
+
|
|
||||||
The kernel options are added to the current GRUB configuration and its templates. The system needs to be rebooted for the kernel options to take effect.
|
|
||||||
+
|
|
||||||
Switching to another profile or manually stopping the `tuned` service removes the additional options. If you shut down or reboot the system, the kernel options persist in the [filename]`grub.cfg` file.
|
|
||||||
+
|
|
||||||
The kernel options can be specified by the following syntax:
|
|
||||||
+
|
|
||||||
[subs=+quotes]
|
|
||||||
----
|
|
||||||
cmdline=[replaceable]_arg1_ [replaceable]_arg2_ ... [replaceable]_argN_
|
|
||||||
----
|
|
||||||
+
|
|
||||||
--
|
|
||||||
.Modifying the kernel command line
|
|
||||||
====
|
|
||||||
For example, to add the [option]`quiet` kernel option to a *TuneD* profile, include the following lines in the [filename]`tuned.conf` file:
|
|
||||||
|
|
||||||
----
|
|
||||||
[bootloader]
|
|
||||||
cmdline=quiet
|
|
||||||
----
|
|
||||||
|
|
||||||
The following is an example of a custom profile that adds the [option]`isolcpus=2` option to the kernel command line:
|
|
||||||
|
|
||||||
----
|
|
||||||
[bootloader]
|
|
||||||
cmdline=isolcpus=2
|
|
||||||
----
|
|
||||||
|
|
||||||
====
|
|
||||||
--
|
|
||||||
|
|
||||||
`acpi`::
|
|
||||||
|
|
||||||
Configures the ACPI driver.
|
|
||||||
+
|
|
||||||
The only currently supported option is
|
|
||||||
[option]`platform_profile`, which sets the ACPI
|
|
||||||
platform profile sysfs attribute,
|
|
||||||
a generic power/performance preference API for other drivers.
|
|
||||||
Multiple profiles can be specified, separated by `|`.
|
|
||||||
The first available profile is selected.
|
|
||||||
+
|
|
||||||
--
|
|
||||||
.Selecting a platform profile
|
|
||||||
====
|
|
||||||
----
|
|
||||||
[acpi]
|
|
||||||
platform_profile=low-power|quiet
|
|
||||||
----
|
|
||||||
Using this option, *TuneD* will try to set the platform profile
|
|
||||||
to `low-power`. If that fails (e.g, because the system does not
|
|
||||||
support the profile), it will try to set it to `quiet`.
|
|
||||||
====
|
|
||||||
--
|
|
||||||
|
|
@ -0,0 +1,6 @@
|
||||||
|
:_module-type: REFERENCE
|
||||||
|
[id="available-tuned-plug-ins_{context}"]
|
||||||
|
= Available TuneD plug-ins
|
||||||
|
|
||||||
|
[role="_abstract"]
|
||||||
|
This section lists all monitoring and tuning plug-ins currently available in *TuneD*.
|
||||||
Loading…
Reference in a new issue