Added user-facing documentation: initial commit

.gitignore

@@ -2,3 +2,4 @@
 *.pyo
 tuned-*.tar.bz2
 *~
+*.html

doc/tuned-documentation/assemblies/assembly_customizing-tuned-profiles.adoc

@@ -0,0 +1,44 @@
+:parent-context-of-customizing-tuned-profiles: {context}
+
+[id='customizing-tuned-profiles_{context}']
+= Customizing Tuned profiles
+
+:context: customizing-tuned-profiles
+
+You can create or modify *Tuned* profiles to optimize system performance for your intended use case.
+
+[id='prerequisites-{context}']
+== Prerequisites
+
+* Install and enable *Tuned* as described in xref:installing-and-enabling-tuned_getting-started-with-tuned[].
+
+
+include::modules/performance/con_tuned-profiles.adoc[leveloffset=+1]
+
+include::modules/performance/con_inheritance-between-tuned-profiles.adoc[leveloffset=+1]
+
+include::modules/performance/con_static-and-dynamic-tuning-in-tuned.adoc[leveloffset=+1]
+
+include::modules/performance/con_tuned-plug-ins.adoc[leveloffset=+1]
+
+include::modules/performance/ref_available-tuned-plug-ins.adoc[leveloffset=+1]
+
+include::modules/performance/con_variables-and-built-in-functions-in-tuned-profiles.adoc[leveloffset=+1]
+
+include::modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc[leveloffset=+1]
+
+include::modules/performance/proc_creating-new-tuned-profiles.adoc[leveloffset=+1]
+
+include::modules/performance/proc_modifying-existing-tuned-profiles.adoc[leveloffset=+1]
+
+// Commented out because the module hasn't been written yet
+// include::modules/performance/proc_creating-tuned-plug-ins.adoc[leveloffset=+1]
+
+
+[id='related-information-{context}']
+== Related information
+
+* The `tuned.conf(5)` man page
+* The *Tuned* project website: link:https://tuned-project.org/[]
+
+:context: {parent-context-of-customizing-tuned-profiles}

doc/tuned-documentation/assemblies/assembly_getting-started-with-tuned.adoc

@@ -0,0 +1,84 @@
+:parent-context-of-getting-started-with-tuned: {context}
+
+[id='getting-started-with-tuned_{context}']
+= Getting started with Tuned
+
+:context: getting-started-with-tuned
+
+////
+ifdef::internal[]
+[cols="1,4"]
+|===
+| Included in |
+monitor-and-automate/monitoring-and-managing-system-status-and-performance
+| User story |
+As a sysadmin, I need a high-level understanding of the tools and procedures to use to tune the performance of my system.
+| Jira |
+https://projects.engineering.redhat.com/browse/RHELPLAN-3290
+| BZ |
+https://bugzilla.redhat.com/show_bug.cgi?id=1546385
+| SMEs |
+Jiří Škarvada
+| SME Ack |
+No
+| Peer Ack |
+No
+|===
+endif::[]
+////
+
+As a system administrator, you can use the *Tuned* service to optimize the performance profile of your system for a variety of use cases.
+
+////
+This is a suggested Table of Contents, taken from BZ#1340944:
+
+* Tuned introduction & overview
+* Tuned (service) + available parameters
+* The config files description: /etc/tuned/*
+* tuned-adm (use content currently in the PTG and update/expand)
+* Plug-ins and their parameters -- move from the guide part of the PTG, rewrite, update.
+* Profiles -- move from the guide part of the PTG, rewrite, update
+   ** how to create profiles and inheritance (the guide part will link here for details)
+   ** description of profiles that are provided with tuned in RHEL 7
+   ** customizing profiles
+* Creating plug-ins 
+   ** will be probably short, not a priority
+   ** jkarvad will provide a first draft
+* Manual pages -- updated and expanded
+////
+
+// [id='prerequisites-{context}']
+// == Prerequisites
+// 
+// * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+// * You can also link to other modules or assemblies the user must follow before starting this assembly.
+// * Delete the section title and bullets if the assembly has no prerequisites.
+
+
+include::modules/performance/con_the-purpose-of-tuned.adoc[leveloffset=+1]
+
+include::modules/performance/con_tuned-profiles.adoc[leveloffset=+1]
+
+include::modules/performance/ref_tuned-profiles-distributed-with-red-hat-enterprise-linux.adoc[leveloffset=+1]
+
+include::modules/performance/con_static-and-dynamic-tuning-in-tuned.adoc[leveloffset=+1]
+
+include::modules/performance/con_tuned-no-daemon-mode.adoc[leveloffset=+1]
+
+include::modules/performance/proc_installing-and-enabling-tuned.adoc[leveloffset=+1]
+
+include::modules/performance/proc_listing-available-tuned-profiles.adoc[leveloffset=+1]
+
+include::modules/performance/proc_setting-a-tuned-profile.adoc[leveloffset=+1]
+
+include::modules/performance/proc_disabling-tuned.adoc[leveloffset=+1]
+
+
+[id='related-information-{context}']
+== Related information
+
+* The `tuned(8)` man page 
+* The `tuned-adm(8)` man page
+* The *Tuned* project website: link:https://tuned-project.org/[]
+
+:context: {parent-context-of-getting-started-with-tuned}

doc/tuned-documentation/assemblies/assembly_optimizing-power-usage.adoc

@@ -0,0 +1,49 @@
+:parent-context-of-optimizing-power-usage: {context}
+
+[id='optimizing-power-usage_{context}']
+= Optimizing power usage
+
+:context: optimizing-power-usage
+
+ifdef::internal[]
+[cols="1,4"]
+|===
+| Included in |
+LIST OF ASSEMBLIES
+| User story |
+USER STORY
+| Jira |
+JIRA LINK
+| BZ |
+BUGZILLA LINK
+| SMEs |
+SME NAMES
+| SME Ack |
+YES/NO
+| Peer Ack |
+YES/NO
+|===
+endif::[]
+
+This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. Can include more than one paragraph. Consider using the information from the user story.
+
+[id='prerequisites-{context}']
+== Prerequisites
+
+* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+* You can also link to other modules or assemblies the user must follow before starting this assembly.
+* Delete the section title and bullets if the assembly has no prerequisites.
+
+
+include::modules/performance/proc_creating-a-tuned-profile-from-powertop-suggestions.adoc[leveloffset=+1]
+
+
+
+[id='related-information-{context}']
+== Related information
+
+* A bulleted list of links to other material closely related to the contents of the concept module.
+* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+
+:context: {parent-context-of-optimizing-power-usage}

doc/tuned-documentation/assemblies/modules

@@ -0,0 +1 @@
+../modules

doc/tuned-documentation/master.adoc

@@ -0,0 +1,38 @@
+:revnumber: 2.10.0
+:revdate: 2019-01-04
+:keywords: documentation, tuned, performance, power, linux
+:toc:
+
+// The revnumber attribute is intended to show the Tuned version for which the document has been updated
+
+[id="{tuned-documentation}"]
+= Tuned documentation: Optimizing system throughput, latency, and power consumption
+
+// Load externally defined attributes
+include::meta/attributes.adoc[]
+
+// Set context for all included assemblies
+:context: tuned-documentation
+
+// This flag turns on internal, debug information in all included assemblies
+// :internal:
+
+// Abstract (Preamble):
+
+This documentation explains how to use the *Tuned* service to monitor and optimize the throughput, latency, and power consumption of your system in different scenarios.
+
+// The following is copied from the standard Red Hat legal notice
+// as used in all Red Hat documentation.
+// TODO: Figure out what the proper legal usage is.
+////
+.Legal notice
+The text of and illustrations in this document are licensed under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at link:http://creativecommons.org/licenses/by-sa/3.0/[]. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
+////
+
+include::assemblies/assembly_getting-started-with-tuned.adoc[leveloffset=+1]
+
+include::assemblies/assembly_customizing-tuned-profiles.adoc[leveloffset=+1]
+
+// Commenting this out because the user story isn't finished
+// include::assemblies/assembly_optimizing-power-usage.adoc[leveloffset=+1]
+

doc/tuned-documentation/meta/attributes.adoc

@@ -0,0 +1,26 @@
+// This flag is used to compile an upstream, vendor-agnostic
+// book from the same source as the downstream RHEL documentation.
+// Modules can check if the flag is defined and enable different
+// content based on it.
+:upstream:
+
+:Year: 2019
+
+// The following attribute is necessary for images to work
+:imagesdir: images
+
+// Red Hat and divisions
+:RH: Red{nbsp}Hat
+:CCS: Customer Content Services
+:OrgName: {RH}
+:OrgDiv: {CCS}
+
+// The product (RHEL)
+:ProductName: {RH} Enterprise{nbsp}Linux
+:RHEL: {ProductName}
+:ProductShortName: RHEL
+// This is the version displayed under "Red Hat Enterprise Linux"
+:ProductNumber: 8
+:RHEL8: {RHEL}{nbsp}8
+:ProductRelease: Beta
+

doc/tuned-documentation/modules/performance/con_inheritance-between-tuned-profiles.adoc

@@ -0,0 +1,39 @@
+[id="inheritance-between-tuned-profiles_{context}"]
+= Inheritance between Tuned profiles
+
+*Tuned* profiles can be based on other profiles and modify only certain aspects of their parent profile.
+
+The `[main]` section of *Tuned* profiles recognizes the [option]`include` option:
+
+[subs=+quotes]
+----
+[main]
+include=[replaceable]_parent_
+----
+
+All settings from the [replaceable]_parent_ profile are loaded in this _child_ profile. In the following sections, the _child_ profile can override certain settings inherited from the [replaceable]_parent_ profile or add new settings not present in the [replaceable]_parent_ profile.
+
+You can create your own _child_ profile in the [filename]`/etc/tuned/` directory based on a pre-installed profile in [filename]`/usr/lib/tuned/` with only some parameters adjusted.
+
+If the [replaceable]_parent_ profile is updated, such as after a *Tuned* upgrade, the changes are reflected in the _child_ profile. 
+
+
+.A power-saving profile based on balanced
+====
+The following is an example of a custom profile that extends the `balanced` profile and sets Aggressive Link Power Management (ALPM) for all devices to the maximum powersaving.
+
+----
+[main]
+include=balanced
+
+[scsi_host]
+alpm=min_power
+----
+====
+
+
+[discrete]
+== Additional resources
+
+* The `tuned.conf(5)` man page
+

doc/tuned-documentation/modules/performance/con_static-and-dynamic-tuning-in-tuned.adoc

@@ -0,0 +1,39 @@
+[id="static-and-dynamic-tuning-in-tuned_{context}"]
+= Static and dynamic tuning in Tuned
+
+This section explains the difference between the two categories of system tuning that *Tuned* applies: _static_ and _dynamic_.
+
+// TODO: Move some of this content into a separate module ("Enabling dynamic tuning"). It seems to be necessary to (1) enable dynamic tuning globally *and* (2) manually enable it in performance-oriented profiles.
+
+Static tuning::
+Mainly consists of the application of predefined `sysctl` and `sysfs` settings and one-shot activation of several configuration tools such as `ethtool`.
+
+Dynamic tuning::
+Watches how various system components are used throughout the uptime of your system. *Tuned* adjusts system settings dynamically based on that monitoring information.
++
+For example, the hard drive is used heavily during startup and login, but is barely used later when the user might mainly work with applications such as web browsers or email clients. Similarly, the CPU and network devices are used differently at different times. *Tuned* monitors the activity of these components and reacts to the changes in their use.
++
+By default, dynamic tuning is disabled. To enable it, edit the [filename]`/etc/tuned/tuned-main.conf` file and change the [option]`dynamic_tuning` option to `1`. *Tuned* then periodically analyzes system statistics and uses them to update your system tuning settings. To configure the time interval in seconds between these updates, use the [option]`update_interval` option.
++
+Currently implemented dynamic tuning algorithms try to balance the performance and powersave, and are therefore disabled in the performance profiles. Dynamic tuning for individual plug-ins can be enabled or disabled in the *Tuned* profiles.
+
+// Internal note: Dynamic tuning is still disabled as of RHEL 8.0 Beta.
+
+.Static and dynamic tuning on a workstation
+====
+On a typical office workstation, the Ethernet network interface is inactive most of the time. Only a few emails go in and out or some web pages might be loaded.
+
+For those kinds of loads, the network interface does not have to run at full speed all the time, as it does by default. *Tuned* has a monitoring and tuning plug-in for network devices that can detect this low activity and then automatically lower the speed of that interface, typically resulting in a lower power usage.
+
+If the activity on the interface increases for a longer period of time, for example because a DVD image is being downloaded or an email with a large attachment is opened, *Tuned* detects this and sets the interface speed to maximum to offer the best performance while the activity level is high.
+
+This principle is used for other plug-ins for CPU and disks as well.
+====
+
+
+// [discrete]
+// == Additional resources
+// 
+// * A bulleted list of links to other material closely related to the contents of the concept module.
+// * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

doc/tuned-documentation/modules/performance/con_the-purpose-of-tuned.adoc

@@ -0,0 +1,23 @@
+[id="the-purpose-of-tuned_{context}"]
+= The purpose of Tuned
+
+*Tuned* is a service that monitors your system and optimizes the performance under certain workloads. The core of *Tuned* are _profiles_, which tune your system for different use cases.
+
+*Tuned* is distributed with a number of predefined profiles for use cases such as:
+
+* High throughput
+* Low latency
+* Saving power
+
+It is possible to modify the rules defined for each profile and customize how to tune a particular device. When you switch to another profile or deactivate *Tuned*, all changes made to the system settings by the previous profile revert back to their original state.
+
+You can also configure *Tuned* to react to changes in device usage and adjusts settings to improve performance of active devices and reduce power consumption of inactive devices.
+
+// The tuned tuning service can adapt the operating system to perform better under certain workloads by setting a tuning profile.
+
+// [discrete]
+// == Additional resources
+// 
+// * A bulleted list of links to other material closely related to the contents of the concept module.
+// * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

doc/tuned-documentation/modules/performance/con_tuned-no-daemon-mode.adoc

@@ -0,0 +1,25 @@
+[id="tuned-no-daemon-mode_{context}"]
+= Tuned no-daemon mode
+
+// TODO: Should this be a procedure? A user story? Is there a common use case?
+
+You can run *Tuned* in `no-daemon` mode, which does not require any resident memory. In this mode, *Tuned* applies the settings and exits.
+
+By default, `no-daemon` mode is disabled because a lot of *Tuned* functionality is missing in this mode, including:
+
+* D-Bus support
+* Hot-plug support
+* Rollback support for settings
+
+To enable `no-daemon` mode, include the following line in the [filename]`/etc/tuned/tuned-main.conf` file:
+
+----
+daemon = 0
+----
+
+// [discrete]
+// == Additional resources
+// 
+// * A bulleted list of links to other material closely related to the contents of the concept module.
+// * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

doc/tuned-documentation/modules/performance/con_tuned-plug-ins.adoc

@@ -0,0 +1,112 @@
+[id="tuned-plug-ins_{context}"]
+= Tuned plug-ins
+
+Plug-ins are modules in *Tuned* profiles that *Tuned* uses to monitor or optimize different devices on the system.
+
+*Tuned* uses two types of plug-ins:
+
+* monitoring plug-ins
+* tuning plug-ins
+
+[discrete]
+== Monitoring plug-ins
+
+Monitoring plug-ins are used to get information from a running system. The output of the monitoring plug-ins can be used by tuning plug-ins for dynamic tuning.
+
+Monitoring plug-ins are automatically instantiated whenever their metrics are needed by any of the enabled tuning plug-ins. If two tuning plug-ins require the same data, only one instance of the monitoring plug-in is created and the data is shared.
+
+[discrete]
+== Tuning plug-ins
+
+Each tuning plug-in tunes an individual subsystem and takes several parameters that are populated from the tuned profiles. Each subsystem can have multiple devices, such as multiple CPUs or network cards, that are handled by individual instances of the tuning plug-ins. Specific settings for individual devices are also supported. 
+
+[discrete]
+== Syntax for plug-ins in Tuned profiles
+
+Sections describing plug-in instances are formatted in the following way:
+
+[subs=quotes]
+----
+[_NAME_]
+type=_TYPE_
+devices=_DEVICES_
+----
+
+NAME::
+is the name of the plug-in instance as it is used in the logs. It can be an arbitrary string. 
+
+TYPE::
+is the type of the tuning plug-in. 
+
+DEVICES::
+is the list of devices that this plug-in instance handles. 
++
+The `devices` line can contain a list, a wildcard (`\*`), and negation (`!`). If there is no `devices` line, all devices present or later attached on the system of the [replaceable]_TYPE_ are handled by the plug-in instance. This is same as using the [option]`devices=*` option.
++
+.Matching block devices with a plug-in
+====
+The following example matches all block devices starting with `sd`, such as `sda` or `sdb`, and does not disable barriers on them:
+
+----
+[data_disk]
+type=disk
+devices=sd*
+disable_barriers=false
+----
+
+The following example matches all block devices except `sda1` and `sda2`:
+
+----
+[data_disk]
+type=disk
+devices=!sda1, !sda2 
+disable_barriers=false
+----
+
+====
+
+If no instance of a plug-in is specified, the plug-in is not enabled. 
+
+If the plug-in supports more options, they can be also specified in the plug-in section. If the option is not specified and it was not previously specified in the included plug-in, the default value is used.
+
+[discrete]
+== Short plug-in syntax
+
+If you do not need custom names for the plug-in instance and there is only one definition of the instance in your configuration file, *Tuned* supports the following short syntax:
+
+[subs=quotes]
+----
+[_TYPE_]
+devices=_DEVICES_
+----
+
+In this case, it is possible to omit the `type` line. The instance is then referred to with a name, same as the type. The previous example could be then rewritten into:
+
+.Matching block devices using the short syntax
+====
+----
+[disk]
+devices=sdb*
+disable_barriers=false
+----
+====
+
+[discrete]
+== Conflicting plug-in definitions in a profile
+
+If the same section is specified more than once using the `include` option, the settings are merged. If they cannot be merged due to a conflict, the last conflicting definition overrides the previous settings. If you do not know what was previously defined, you can use the [option]`replace` Boolean option and set it to `true`. This causes all the previous definitions with the same name to be overwritten and the merge does not happen.
+
+You can also disable the plug-in by specifying the [option]`enabled=false` option. This has the same effect as if the instance was never defined. Disabling the plug-in is useful if you are redefining the previous definition from the [option]`include` option and do not want the plug-in to be active in your custom profile.
+
+[discrete]
+== Functionality not implemented in any plug-in
+
+*Tuned* includes the ability to run any shell command as part of enabling or disabling a tuning profile. This enables you to extend *Tuned* profiles with functionality that has not been integrated into Tuned yet.
+
+You can specify arbitrary shell commands using the `script` plug-in.
+
+[discrete]
+== Additional resources
+
+* The `tuned.conf(5)` man page
+

doc/tuned-documentation/modules/performance/con_tuned-profiles.adoc

@@ -0,0 +1,73 @@
+[id="tuned-profiles_{context}"]
+= Tuned profiles
+
+A detailed analysis of a system can be very time-consuming. *Tuned* provides a number of predefined profiles for typical use cases. You can also create, modify, and delete profiles.
+
+The profiles provided with *Tuned* are divided into the following categories:
+
+* Power-saving profiles
+* Performance-boosting profiles
+
+The performance-boosting profiles include profiles that focus on the following aspects:
+
+* Low latency for storage and network
+* High throughput for storage and network
+* Virtual machine performance
+* Virtualization host performance
+
+[discrete]
+== The default profile
+
+During the installation, the best profile for your system is selected automatically. Currently, the default profile is selected according to the following customizable rules:
+
+[options="header",cols="2,2,3"]
+|===
+| Environment | Default profile | Goal
+| Compute nodes | `throughput-performance` | The best throughput performance
+| Virtual machines | `virtual-guest` | The best performance. If you are not interested in the best performance, you can change it to the `balanced` or `powersave` profile.
+| Other cases | `balanced` | Balanced performance and power consumption
+|===
+
+
+[discrete]
+== Merged profiles
+
+As an experimental feature, it is possible to select more profiles at once. *Tuned* will try to merge them during the load.
+
+If there are conflicts, the settings from the last specified profile takes precedence.
+
+.Low power consumption in a virtual guest
+====
+The following example optimizes the system to run in a virtual machine for the best performance and concurrently tunes it for low power consumption, while the low power consumption is the priority:
+
+----
+# tuned-adm profile virtual-guest powersave
+----
+====
+
+WARNING: Merging is done automatically without checking whether the resulting combination of parameters makes sense. Consequently, the feature might tune some parameters the opposite way, which might be counterproductive: for example, setting the disk for high throughput by using the `throughput-performance` profile and concurrently setting the disk spindown to the low value by the `spindown-disk` profile.
+
+[discrete]
+== The location of profiles
+
+*Tuned* stores profiles in the following directories:
+
+[filename]`/usr/lib/tuned/`::
+Distribution-specific profiles are stored in the  directory. Each profile has its own directory. The profile consists of the main configuration file called `tuned.conf`, and optionally other files, for example helper scripts.
+
+[filename]`/etc/tuned/`::
+If you need to customize a profile, copy the profile directory into the  directory, which is used for custom profiles. If there are two profiles of the same name, the custom profile located in [filename]`/etc/tuned/` is used.
+
+
+[discrete]
+== The syntax of profile configuration
+
+The `tuned.conf` file can contain one `[main]` section and other sections for configuring plug-in instances. However, all sections are optional.
+
+Lines starting with the hash sign (`#`) are comments.
+
+[discrete]
+== Additional resources
+
+* The `tuned.conf(5)` man page.
+

doc/tuned-documentation/modules/performance/con_variables-and-built-in-functions-in-tuned-profiles.adoc

@@ -0,0 +1,96 @@
+[id="variables-and-built-in-functions-in-tuned-profiles_{context}"]
+= Variables and built-in functions in Tuned profiles
+
+Variables and built-in functions expand at run time when a *Tuned* profile is activated.
+
+Using *Tuned* variables reduces the amount of necessary typing in *Tuned* profiles. You can also:
+
+* Use various built-in functions together with *Tuned* variables
+* Create custom functions in Python and add them to *Tuned* in the form of plug-ins
+
+[discrete]
+== Variables
+
+There are no predefined variables in *Tuned* profiles. You can define your own variables by creating the `[variables]` section in a profile and using the following syntax:
+
+[subs=+quotes]
+----
+[variables]
+
+[replaceable]__variable_name__=[replaceable]__value__
+----
+
+To expand the value of a variable in a profile, use the following syntax:
+
+[subs=+quotes]
+----
+${[replaceable]__variable_name__}
+----
+
+.Isolating CPU cores using variables
+====
+In the following example, the `${isolated_cores}` variable expands to `1,2`; hence the kernel boots with the [option]`isolcpus=1,2` option:
+
+----
+[variables]
+isolated_cores=1,2
+
+[bootloader]
+cmdline=isolcpus=${isolated_cores}
+----
+
+The variables can be specified in a separate file. For example, you can add the following lines to [filename]`tuned.conf`:
+
+[subs=+quotes]
+----
+[variables]
+include=/etc/tuned/[replaceable]_my-variables.conf_
+
+[bootloader]
+cmdline=isolcpus=${isolated_cores}
+----
+
+If you add the [option]`isolated_cores=1,2` option to the [filename]`/etc/tuned/my-variables.conf` file, the kernel boots with the [option]`isolcpus=1,2` option.
+
+====
+
+
+[discrete]
+== Functions
+
+To call a function, use the following syntax:
+
+[subs=+quotes]
+----
+${f:[replaceable]__function_name__:[replaceable]__argument_1__:[replaceable]__argument_2__}
+----
+
+To expand the directory path where the profile and the `tuned.conf` file are located, use the `PROFILE_DIR` function, which requires special syntax:
+
+----
+${i:PROFILE_DIR}
+----
+
+
+
+.Isolating CPU cores using variables and built-in functions
+====
+In the following example, the `${non_isolated_cores}` variable expands to `0,3-5`, and the `cpulist_invert` built-in function is called with the `0,3-5` argument:
+
+----
+[variables]
+non_isolated_cores=0,3-5
+
+[bootloader]
+cmdline=isolcpus=${f:cpulist_invert:${non_isolated_cores}}
+----
+
+The `cpulist_invert` function inverts the list of CPUs. For a 6-CPU machine, the inversion is `1,2`, and the kernel boots with the [option]`isolcpus=1,2` command-line option.
+
+====
+
+[discrete]
+== Additional resources
+
+* The `tuned.conf(5)` man page
+

doc/tuned-documentation/modules/performance/proc_creating-a-tuned-profile-from-powertop-suggestions.adoc

@@ -0,0 +1,33 @@
+[id="creating-a-tuned-profile-from-powertop-suggestions_{context}"]
+= Creating a Tuned profile from PowerTOP suggestions
+
+The powertop2tuned utility is a tool that allows you to create custom tuned profiles from the PowerTOP suggestions.
+
+[discrete]
+== Prerequisites
+
+*  To install the powertop2tuned application, run the following command as root:
+
+yum install tuned-utils
+
+[discrete]
+== Procedure
+
+To create a custom profile, run the following command as root:
+
+powertop2tuned new_profile_name
+
+By default it creates the profile in the /etc/tuned directory and it bases it on the currently selected tuned profile. For safety reasons all PowerTOP tunings are initially disabled in the new profile. To enable them uncomment the tunings of your interest in the /etc/tuned/profile/tuned.conf. You can use the --enable or -e option that will generate the new profile with most of the tunings suggested by PowerTOP enabled. Some dangerous tunings like the USB autosuspend will still be disabled. If you really need them you will have to uncomment them manually. By default, the new profile is not activated. To activate it run the following command:
+
+tuned-adm profile new_profile_name
+
+For a complete list of the options powertop2tuned supports, type in the following command:
+
+powertop2tuned --help
+
+[discrete]
+== Additional resources
+
+* A bulleted list of links to other material closely related to the contents of the procedure module.
+* For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

doc/tuned-documentation/modules/performance/proc_creating-new-tuned-profiles.adoc

@@ -0,0 +1,70 @@
+[id="creating-new-tuned-profiles_{context}"]
+= Creating new Tuned profiles
+
+This procedure creates a new *Tuned* profile with custom performance rules.
+
+[discrete]
+== Prerequisites
+
+* The `tuned` service is installed and running. See xref:installing-and-enabling-tuned_getting-started-with-tuned[] for details.
+
+[discrete]
+== Procedure
+
+. In the [filename]`/etc/tuned/` directory, create a new directory named the same as the profile that you want to create:
++
+[subs=+quotes]
+----
+# mkdir /etc/tuned/[replaceable]_my-profile_
+----
+
+. In the new directory, create a file named [filename]`tuned.conf`. Add a `[main]` section and plug-in definitions in it, according to your requirements.
++
+For example, see the configuration of the `balanced` profile:
++
+----
+[main]
+summary=General non-specialized tuned profile
+
+[cpu]
+governor=conservative
+energy_perf_bias=normal
+
+[audio]
+timeout=10
+
+[video]
+radeon_powersave=dpm-balanced, auto
+
+[scsi_host]
+alpm=medium_power
+----
+
+. To activate the profile, use:
++
+[subs=+quotes]
+----
+# tuned-adm profile [replaceable]_my-profile_
+----
+
+. Verify that the *Tuned* profile is active and the system settings are applied:
++
+[subs=+quotes]
+----
+$ tuned-adm active
+
+Current active profile: [replaceable]_my-profile_
+----
++
+----
+$ tuned-adm verify
+
+Verfication succeeded, current system settings match the preset profile.
+See tuned log file ('/var/log/tuned/tuned.log') for details.
+----
+
+[discrete]
+== Additional resources
+
+* The `tuned.conf(5)` man page
+

doc/tuned-documentation/modules/performance/proc_creating-tuned-plug-ins.adoc

@@ -0,0 +1,27 @@
+[id="creating-tuned-plug-ins_{context}"]
+= Creating Tuned plug-ins
+
+This paragraph is the procedure module introduction: a short description of the procedure.
+
+[discrete]
+== Prerequisites
+
+* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+* You can also link to other modules or assemblies the user must follow before starting this assembly.
+* Delete the section title and bullets if the assembly has no prerequisites.
+
+[discrete]
+== Procedure
+
+. Start each step with an active verb.
+
+. Include one command or action per step.
+
+. Use an unnumbered bullet (*) if the procedure includes only one step.
+
+[discrete]
+== Additional resources
+
+* A bulleted list of links to other material closely related to the contents of the procedure module.
+* For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

doc/tuned-documentation/modules/performance/proc_disabling-tuned.adoc

@@ -0,0 +1,34 @@
+[id="disabling-tuned_{context}"]
+= Disabling Tuned
+
+This procedure disables *Tuned* and resets all affected system settings to their original state before *Tuned* modified them.
+
+// [discrete]
+// == Prerequisites
+// 
+// * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+// * You can also link to other modules or assemblies the user must follow before starting this assembly.
+// * Delete the section title and bullets if the assembly has no prerequisites.
+
+[discrete]
+== Procedure
+
+* To disable all tunings temporarily:
++
+----
+# tuned-adm off
+----
++
+The tunings are applied again after the `tuned` service restarts.
+
+* Alternatively, to stop and disable the `tuned` service permanently:
++
+----
+# systemctl disable --now tuned
+----
+
+[discrete]
+== Additional resources
+
+* The `tuned-adm(8)` man page.
+

doc/tuned-documentation/modules/performance/proc_installing-and-enabling-tuned.adoc

@@ -0,0 +1,56 @@
+[id="installing-and-enabling-tuned_{context}"]
+= Installing and enabling Tuned
+
+This procedure installs and enables the *Tuned* service, installs *Tuned* profiles, and presets a default *Tuned* profile for your system.
+
+// [discrete]
+// == Prerequisites
+// 
+// * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+// * You can also link to other modules or assemblies the user must follow before starting this assembly.
+// * Delete the section title and bullets if the assembly has no prerequisites.
+
+[discrete]
+== Procedure
+
+. Install the [package]`tuned` package:
++
+----
+# yum install tuned
+----
+
+. Enable and start the `tuned` service:
++
+----
+# systemctl enable --now tuned
+----
+
+. Optionally, install *Tuned* profiles for real-time systems or for {RHEL} Atomic Host:
++
+----
+# yum install tuned-profiles-realtime tuned-profiles-nfv \
+              tuned-profiles-atomic
+----
+
+. Verify that a *Tuned* profile is active and applied:
++
+[subs=+quotes]
+----
+$ tuned-adm active
+
+Current active profile: [replaceable]_balanced_
+----
++
+----
+$ tuned-adm verify
+
+Verfication succeeded, current system settings match the preset profile.
+See tuned log file ('/var/log/tuned/tuned.log') for details.
+----
+
+
+// [discrete]
+// == Additional resources
+// 
+// * The `tuned-adm(8)` man page.
+

doc/tuned-documentation/modules/performance/proc_listing-available-tuned-profiles.adoc

@@ -0,0 +1,49 @@
+[id="listing-available-tuned-profiles_{context}"]
+= Listing available Tuned profiles
+
+This procedure lists all *Tuned* profiles that are currently available on your system.
+
+//No prerequisites are needed
+////
+[discrete]
+== Prerequisites
+
+* The `tuned` service is running. See xref:installing-and-enabling-tuned_{context}[] for details.
+////
+
+[discrete]
+== Procedure
+
+* To list all available *Tuned* profiles on your system, use:
++
+[subs=+quotes,options=+nowrap]
+----
+$ tuned-adm list
+
+Available profiles:
+- balanced               - General non-specialized tuned profile
+- desktop                - Optimize for the desktop use-case
+- latency-performance    - Optimize for deterministic performance at the cost of increased power consumption
+- network-latency        - Optimize for deterministic performance at the cost of increased power consumption, focused on low latency network performance
+- network-throughput     - Optimize for streaming network throughput, generally only necessary on older CPUs or 40G+ networks
+- powersave              - Optimize for low power consumption
+- throughput-performance - Broadly applicable tuning that provides excellent performance across a variety of common server workloads
+- virtual-guest          - Optimize for running inside a virtual guest
+- virtual-host           - Optimize for running KVM guests
+Current active profile: [replaceable]_balanced_
+----
+
+* To display only the currently active profile, use:
++
+[subs=+quotes]
+----
+$ tuned-adm active
+
+Current active profile: [replaceable]_balanced_
+----
+
+[discrete]
+== Additional resources
+
+* The `tuned-adm(8)` man page.
+

doc/tuned-documentation/modules/performance/proc_modifying-existing-tuned-profiles.adoc

@@ -0,0 +1,84 @@
+[id="modifying-existing-tuned-profiles_{context}"]
+= Modifying existing Tuned profiles
+
+This procedure creates a modified child profile based on an existing *Tuned* profile.
+
+[discrete]
+== Prerequisites
+
+* The `tuned` service is installed and running. See xref:installing-and-enabling-tuned_getting-started-with-tuned[] for details.
+
+[discrete]
+== Procedure
+
+. In the [filename]`/etc/tuned/` directory, create a new directory named the same as the profile that you want to create:
++
+[subs=+quotes]
+----
+# mkdir /etc/tuned/[replaceable]_modified-profile_
+----
+
+. In the new directory, create a file named [filename]`tuned.conf`, and set the `[main]` section as follows:
++
+[subs=+quotes]
+----
+[main]
+include=[replaceable]_parent-profile_
+----
++
+Replace [replaceable]_parent-profile_ with the name of the profile you are modifying.
+
+. Include your profile modifications.
++
+--
+.Lowering swappiness in the throughput-performance profile
+====
+To use the settings from the `throughput-performance` profile and change the value of `vm.swappiness` to 5, instead of the default 10, use:
+
+----
+[main]
+include=throughput-performance
+
+[sysctl]
+vm.swappiness=5
+----
+====
+--
+
+. To activate the profile, use:
++
+[subs=+quotes]
+----
+# tuned-adm profile [replaceable]_modified-profile_
+----
+
+. Verify that the *Tuned* profile is active and the system settings are applied:
++
+[subs=+quotes]
+----
+$ tuned-adm active
+
+Current active profile: [replaceable]_my-profile_
+----
++
+----
+$ tuned-adm verify
+
+Verfication succeeded, current system settings match the preset profile.
+See tuned log file ('/var/log/tuned/tuned.log') for details.
+----
+
+// .An alternative approach
+// . Alternatively, copy the directory with a system profile from /user/lib/tuned/ to /etc/tuned/. For example:
+// +
+// ----
+// # cp -r /usr/lib/tuned/throughput-performance /etc/tuned
+// ----
+// 
+// . Then, edit the profile in /etc/tuned according to your needs. Note that if there are two profiles of the same name, the profile located in /etc/tuned/ is loaded. The disadvantage of this approach is that if a system profile is updated after a tuned upgrade, the changes will not be reflected in the now-outdated modified version. 
+
+[discrete]
+== Additional resources
+
+* The `tuned.conf(5)` man page
+

doc/tuned-documentation/modules/performance/proc_setting-a-tuned-profile.adoc

@@ -0,0 +1,67 @@
+[id="setting-a-tuned-profile_{context}"]
+= Setting a Tuned profile
+
+This procedure activates a selected *Tuned* profile on your system.
+
+[discrete]
+== Prerequisites
+
+* The `tuned` service is running. See xref:installing-and-enabling-tuned_{context}[] for details.
+
+[discrete]
+== Procedure
+
+. Optionally, you can let *Tuned* recommend the most suitable profile for your system:
++
+[subs=+quotes]
+----
+# tuned-adm recommend
+
+[replaceable]_balanced_
+----
+
+. Activate a profile:
++
+[subs=+quotes]
+----
+# tuned-adm profile [replaceable]_selected-profile_
+----
++
+Alternatively, you can activate a combination of multiple profiles:
++
+[subs=+quotes]
+----
+# tuned-adm profile [replaceable]_profile1_ [replaceable]_profile2_
+----
++
+.A virtual machine optimized for low power consumption
+====
+The following example optimizes the system to run in a virtual machine with the best performance and concurrently tunes it for low power consumption, while the low power consumption is the priority:
+
+----
+# tuned-adm profile virtual-guest powersave
+----
+====
+
+. Verify that the *Tuned* profile is active and applied:
++
+[subs=+quotes]
+----
+$ tuned-adm active
+
+Current active profile: [replaceable]_selected-profile_
+----
++
+----
+$ tuned-adm verify
+
+Verfication succeeded, current system settings match the preset profile.
+See tuned log file ('/var/log/tuned/tuned.log') for details.
+----
+
+
+[discrete]
+== Additional resources
+
+* The `tuned-adm(8)` man page
+

doc/tuned-documentation/modules/performance/ref_available-tuned-plug-ins.adoc

@@ -0,0 +1,159 @@
+[id="available-tuned-plug-ins_{context}"]
+= Available Tuned plug-ins
+
+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.
+
+`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. 
+
+`script`::
+Can be used for the execution of an external script that is run when the profile is loaded or unloaded.
++
+The script is called by one argument which can be `start` or `stop`, depending on whether the script is called during the profile load or unload. The script file name can be specified by the `script` parameter.
++
+You need to correctly implement the stop action in your script and revert all settings that you changed during the start action. Otherwise, the roll-back step after changing your *Tuned* profile will not work. 
++
+The `functions` Bash helper script is installed by default and enables you to import and use various functions defined in it. 
++
+Note that this plug-in is provided mainly for backwards compatibility, and it is recommended that you use it as the last resort and prefer other plug-ins if they cover the required settings. 
+
+`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
+----
+
+====
+--
+

doc/tuned-documentation/modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc

@@ -0,0 +1,56 @@
+[id="built-in-functions-available-in-tuned-profiles_{context}"]
+= Built-in functions available in Tuned profiles
+
+The following built-in functions are available in all Tuned profiles:
+
+`PROFILE_DIR`::
+Returns the directory path where the profile and the `tuned.conf` file are located.
+
+`exec`::
+Executes a process and returns its output.
+
+`assertion`::
+Compares two arguments. If they _do not match_, the function logs text from the first argument and aborts profile loading.
+
+`assertion_non_equal`::
+Compares two arguments. If they _match_, the function logs text from the first argument and aborts profile loading.
+
+`kb2s`::
+Converts kilobytes to disk sectors.
+
+`s2kb`::
+Converts disk sectors to kilobytes.
+
+`strip`::
+Creates a string from all passed arguments and deletes both leading and trailing white space.
+
+`virt_check`::
+Checks whether *Tuned* is running inside a virtual machine (VM) or on bare metal:
++
+* Inside a VM, the function returns the first argument.
+* On bare metal, the function returns the second argument, even in case of an error.
+
+`cpulist_invert`::
+Inverts a list of CPUs to make its complement. For example, on a system with 4 CPUs, numbered from 0 to 3, the inversion of the list `0,2,3` is `1`.
+
+`cpulist2hex`::
+Converts a CPU list to a hexadecimal CPU mask.
+
+`cpulist2hex_invert`::
+Converts a CPU list to a hexadecimal CPU mask and inverts it.
+
+`hex2cpulist`::
+Converts a hexadecimal CPU mask to a CPU list.
+
+`cpulist_online`::
+Checks whether the CPUs from the list are online. Returns the list containing only online CPUs.
+
+`cpulist_present`::
+Checks whether the CPUs from the list are present. Returns the list containing only present CPUs.
+
+`cpulist_unpack`::
+Unpacks a CPU list in the form of `1-3,4` to `1,2,3,4`.
+
+`cpulist_pack`::
+Packs a CPU list in the form of `1,2,3,5` to `1-3,5`.
+

doc/tuned-documentation/modules/performance/ref_tuned-profiles-distributed-with-red-hat-enterprise-linux.adoc

@@ -0,0 +1,104 @@
+[id="tuned-profiles-distributed-with-red-hat-enterprise-linux_{context}"]
+= Tuned profiles distributed with Red Hat Enterprise Linux
+
+The following is a list of profiles that are installed with *Tuned* on {RHEL}:
+
+NOTE: There might be more product-specific or third-party *Tuned* profiles available. Such profiles are usually provided by separate RPM packages.
+
+
+`balanced`::
+The default power-saving profile. It is intended to be a compromise between performance and power consumption. It uses auto-scaling and auto-tuning whenever possible. The only drawback is the increased latency. In the current *Tuned* release, it enables the CPU, disk, audio, and video plugins, and activates the `conservative` CPU governor. The `radeon_powersave` option uses the `dpm-balanced` value if it is supported, otherwise it is set to `auto`. 
+
+`powersave`::
+A profile for maximum power saving performance. It can throttle the performance in order to minimize the actual power consumption. In the current *Tuned* release it enables USB autosuspend, WiFi power saving, and Aggressive Link Power Management (ALPM) power savings for SATA host adapters. It also schedules multi-core power savings for systems with a low wakeup rate and activates the `ondemand` governor. It enables AC97 audio power saving or, depending on your system, HDA-Intel power savings with a 10 seconds timeout. If your system contains a supported Radeon graphics card with enabled KMS, the profile configures it to automatic power saving. On ASUS Eee PCs, a dynamic Super Hybrid Engine is enabled.
++
+[NOTE]
+--
+In certain cases, the `balanced` profile is more efficient compared to the `powersave` profile.
+
+Consider there is a defined amount of work that needs to be done, for example a video file that needs to be transcoded. Your machine might consume less energy if the transcoding is done on the full power, because the task is finished quickly, the machine starts to idle, and it can automatically step-down to very efficient power save modes. On the other hand, if you transcode the file with a throttled machine, the machine consumes less power during the transcoding, but the process takes longer and the overall consumed energy can be higher.
+
+That is why the `balanced` profile can be generally a better option. 
+--
+
+`throughput-performance`::
+A server profile optimized for high throughput. It disables power savings mechanisms and enables `sysctl` settings that improve the throughput performance of the disk and network IO. CPU governor is set to `performance`. 
+
+`latency-performance`::
+A server profile optimized for low latency. It disables power savings mechanisms and enables `sysctl` settings that improve latency. CPU governor is set to `performance` and the CPU is locked to the low C states (by PM QoS). 
+
+`network-latency`::
+A profile for low latency network tuning. It is based on the `latency-performance` profile. It additionally disables transparent huge pages and NUMA balancing, and tunes several other network-related `sysctl` parameters. 
+
+`network-throughput`::
+A profile for throughput network tuning. It is based on the `throughput-performance` profile. It additionally increases kernel network buffers. 
+
+`virtual-guest`::
+A profile designed for virtual guests based on the `throughput-performance` profile that, among other tasks, decreases virtual memory swappiness and increases disk readahead values. It does not disable disk barriers. 
+
+`virtual-host`::
+A profile designed for virtual hosts based on the `throughput-performance` profile that, among other tasks, decreases virtual memory swappiness, increases disk readahead values, and enables a more aggressive value of dirty pages writeback.
+
+`oracle`::
+A profile optimized for Oracle databases loads based on `throughput-performance` profile. It additionally disables transparent huge pages and modifies other performance-related kernel parameters. This profile is provided by the [package]`tuned-profiles-oracle` package.
+
+`desktop`::
+A profile optimized for desktops, based on the `balanced` profile. It additionally enables scheduler autogroups for better response of interactive applications. 
+
+// The below section is commented out for the reason: the package is about to be dropped https://docs.google.com/document/d/1sC0aqHdvNj1sCPMJjWQKTxmfZ_CFDxAZZCTcoiJ5kGg/edit?disco=uiAAAACO8spDQ
+////
+[discrete]
+== Compat profiles
+
+// Additional predefined profiles can be installed with the [package]`tuned-profiles-compat` package available in the Optional channel. These profiles are intended for backward compatibility and are no longer developed.
+Additional predefined profiles can be installed with the [package]`tuned-profiles-compat` package. These profiles are intended for backward compatibility and are no longer developed.
+
+The generalized profiles from the base package mostly perform the same or better. If you do not have a specific reason for using them, please prefer the above mentioned profiles from the base package.
+
+The compat profiles are following:
+
+`default`::
+This has the lowest impact on power saving of the available profiles and only enables CPU and disk plugins of *Tuned*. 
+
+`desktop-powersave`::
+A power-saving profile directed at desktop systems. Enables ALPM power saving for SATA host adapters as well as the CPU, Ethernet, and disk plug-ins of *Tuned*. 
+
+`laptop-ac-powersave`::
+A medium-impact power-saving profile directed at laptops running on AC. Enables ALPM power saving for SATA host adapters, Wi-Fi power saving, as well as the CPU, Ethernet, and disk plug-ins of *Tuned*. 
+
+`laptop-battery-powersave`::
+A high-impact power-saving profile directed at laptops running on battery. In the current *Tuned* implementation, it is an alias for the `powersave` profile. 
+
+`spindown-disk`::
+A power-saving profile for machines with classic HDDs to minimize the spindown timeout. It enables USB autosuspend, disables Bluetooth, enables Wi-Fi power saving, disables logs syncing, increases disk write-back time, and lowers disk swappiness. All partitions are remounted with the `noatime` option. 
+
+`enterprise-storage`::
+A server profile directed at enterprise-class storage, maximizing I/O throughput. It activates the same settings as the `throughput-performance` profile, multiplies readahead settings, and disables barriers on non-root and non-boot partitions. 
+////
+
+[discrete]
+== Profiles for {RHEL} Atomic Host
+
+Profiles optimized for {RHEL} Atomic Host are provided by the [package]`tuned-profiles-atomic` package. The *Tuned* profiles for {RHEL} Atomic Host are:
+
+`atomic-host`::
+A profile optimized for {RHEL} Atomic Host, when used as a host system on a bare-metal server, based on the `throughput-performance` profile. It additionally increases SELinux AVC cache, PID limit, and tunes `netfilter` connections tracking. 
+
+`atomic-guest`::
+A profile optimized for {RHEL} Atomic Host, when used as a guest system based on the `virtual-guest` profile. It additionally increases SELinux AVC cache, PID limit, and tunes `netfilter` connections tracking. 
+
+Use the `atomic-host` profile on physical machines, and the `atomic-guest` profile on virtual machines.
+
+[discrete]
+== Real-time profiles
+
+// TODO: What are these? Profiles for real-time-enabled systems? Profiles that make your system real-time?
+
+The following real-time profiles are available:
+
+`realtime`::
+Available from the [package]`tuned-profiles-realtime` package.
+
+`realtime-virtual-host` and `realtime-virtual-guest`::
+Available from the [package]`tuned-profiles-nfv` package.
+