man: clarify that IOXyz= only applies to the unified hierarchy, and BlockIOXyz= to the legacy hierarchy

With this change for each setting we say which hierarachy it applies to briefly
in the first sentence of the description, plus in longer form in an extra
pargraph at the end, with a recommendation for the counterpart of the option in
the other hierarchy.

Also adds markup and the "=" suffix to all mentioned settings.

1 files changed, 84 insertions, 98 deletions

diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml
index 4edb1a25a8..313a49a959 100644
--- a/man/systemd.resource-control.xml
+++ b/man/systemd.resource-control.xml
@@ -252,14 +252,15 @@
         <term><varname>IOAccounting=</varname></term>
 
         <listitem>
-          <para>Turn on Block I/O accounting for this unit on unified
-          hierarchy. Takes a boolean argument. Note that turning on
-          block I/O accounting for one unit will also implicitly turn
-          it on for all units contained in the same slice and all for
-          its parent slices and the units contained therein. The
-          system default for this setting may be controlled with
-          <varname>DefaultIOAccounting=</varname> in
+          <para>Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the
+          system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly
+          turn it on for all units contained in the same slice and all for its parent slices and the units contained
+          therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname>
+          in
           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+          <para>This setting is supported only if the unified control group hierarchy is used. Use
+          <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para>
         </listitem>
       </varlistentry>
 
@@ -268,15 +269,12 @@
         <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term>
 
         <listitem>
-          <para>Set the default overall block I/O weight for the
-          executed processes on unified hierarchy. Takes a single
-          weight value (between 1 and 10000) to set the default block
-          I/O weight. This controls the <literal>io.weight</literal>
-          control group attribute, which defaults to 100. For details
-          about this control group attribute, see <ulink
-          url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.
-          The available I/O bandwidth is split up among all units
-          within one slice relative to their block I/O weight.</para>
+          <para>Set the default overall block I/O weight for the executed processes, if the unified control group
+          hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block
+          I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to
+          100. For details about this control group attribute, see <ulink
+          url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.  The available I/O
+          bandwidth is split up among all units within one slice relative to their block I/O weight.</para>
 
           <para>While <varname>StartupIOWeight=</varname> only applies
           to the startup phase of the system,
@@ -286,6 +284,10 @@
           differently than during runtime.</para>
 
           <para>Implies <literal>IOAccounting=true</literal>.</para>
+
+          <para>This setting is supported only if the unified control group hierarchy is used. Use
+          <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> on systems using the legacy
+          control group hierarchy.</para>
         </listitem>
       </varlistentry>
 
@@ -293,21 +295,19 @@
         <term><varname>IODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 
         <listitem>
-          <para>Set the per-device overall block I/O weight for the
-          executed processes on unified hierarchy. Takes a
-          space-separated pair of a file path and a weight value to
-          specify the device specific weight value, between 1 and
-          10000. (Example: "/dev/sda 1000"). The file path may be
-          specified as path to a block device node or as any other
-          file, in which case the backing block device of the file
-          system of the file is determined. This controls the
-          <literal>io.weight</literal> control group attribute, which
-          defaults to 100. Use this option multiple times to set
-          weights for multiple devices. For details about this control
-          group attribute, see <ulink
+          <para>Set the per-device overall block I/O weight for the executed processes, if the unified control group
+          hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify
+          the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). The file path may be
+          specified as path to a block device node or as any other file, in which case the backing block device of the
+          file system of the file is determined. This controls the <literal>io.weight</literal> control group
+          attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For
+          details about this control group attribute, see <ulink
           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para>
 
           <para>Implies <literal>IOAccounting=true</literal>.</para>
+
+          <para>This setting is supported only if the unified control group hierarchy is used. Use
+          <varname>BlockIODeviceWeight=</varname> on systems using the legacy control group hierarchy.</para>
         </listitem>
       </varlistentry>
 
@@ -316,27 +316,23 @@
         <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 
         <listitem>
-          <para>Set the per-device overall block I/O bandwidth maximum
-          limit for the executed processes on unified hierarchy. This
-          limit is not work-conserving and the executed processes are
-          not allowed to use more even if the device has idle
-          capacity.  Takes a space-separated pair of a file path and a
-          bandwidth value (in bytes per second) to specify the device
-          specific bandwidth. The file path may be a path to a block
-          device node, or as any other file in which case the backing
-          block device of the file system of the file is used. If the
-          bandwidth is suffixed with K, M, G, or T, the specified
-          bandwidth is parsed as Kilobytes, Megabytes, Gigabytes, or
-          Terabytes, respectively, to the base of 1000. (Example:
-          "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
-          controls the <literal>io.max</literal> control group
-          attributes. Use this option multiple times to set bandwidth
-          limits for multiple devices. For details about this control
-          group attribute, see <ulink
+          <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified
+          control group hierarchy is used on the system. This limit is not work-conserving and the executed processes
+          are not allowed to use more even if the device has idle capacity.  Takes a space-separated pair of a file
+          path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may
+          be a path to a block device node, or as any other file in which case the backing block device of the file
+          system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is
+          parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example:
+          "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control
+          group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details
+          about this control group attribute, see <ulink
           url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.
           </para>
 
           <para>Implies <literal>IOAccounting=true</literal>.</para>
+
+          <para>This setting is supported only if the unified control group hierarchy is used. Use
+          <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para>
         </listitem>
       </varlistentry>
 
@@ -344,16 +340,15 @@
         <term><varname>BlockIOAccounting=</varname></term>
 
         <listitem>
-          <para>Use IOAccounting on unified hierarchy.</para>
-
-          <para>Turn on Block I/O accounting for this unit. Takes a
-          boolean argument. Note that turning on block I/O accounting
-          for one unit will also implicitly turn it on for all units
-          contained in the same slice and all for its parent slices
-          and the units contained therein. The system default for this
-          setting may be controlled with
+          <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the
+          system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly
+          turn it on for all units contained in the same slice and all for its parent slices and the units contained
+          therein. The system default for this setting may be controlled with
           <varname>DefaultBlockIOAccounting=</varname> in
           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+          <para>This setting is supported only if the legacy control group hierarchy is used. Use
+          <varname>IOAccounting=</varname> on systems using the unified control group hierarchy.</para>
         </listitem>
       </varlistentry>
 
@@ -361,18 +356,13 @@
         <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term>
         <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term>
 
-        <listitem><para>Use IOWeight and StartupIOWeight on unified
-        hierarchy.</para>
-
-        <para>Set the default overall block I/O weight for the
-        executed processes. Takes a single weight value (between 10
-        and 1000) to set the default block I/O weight. This controls
-        the <literal>blkio.weight</literal> control group attribute,
-        which defaults to 500. For details about this control group
-        attribute, see <ulink
+        <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control
+        group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default
+        block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to
+        500. For details about this control group attribute, see <ulink
         url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
-        The available I/O bandwidth is split up among all units within
-        one slice relative to their block I/O weight.</para>
+        The available I/O bandwidth is split up among all units within one slice relative to their block I/O
+        weight.</para>
 
         <para>While <varname>StartupBlockIOWeight=</varname> only
         applies to the startup phase of the system,
@@ -383,31 +373,32 @@
 
         <para>Implies
         <literal>BlockIOAccounting=true</literal>.</para>
-        </listitem>
+
+        <para>This setting is supported only if the legacy control group hierarchy is used. Use
+        <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> on systems using the unified control group
+        hierarchy.</para>
+
+      </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term>
 
         <listitem>
-          <para>Use IODeviceWeight on unified hierarchy.</para>
-
-          <para>Set the per-device overall block I/O weight for the
-          executed processes. Takes a space-separated pair of a file
-          path and a weight value to specify the device specific
-          weight value, between 10 and 1000. (Example: "/dev/sda
-          500"). The file path may be specified as path to a block
-          device node or as any other file, in which case the backing
-          block device of the file system of the file is
-          determined. This controls the
-          <literal>blkio.weight_device</literal> control group
-          attribute, which defaults to 1000. Use this option multiple
-          times to set weights for multiple devices. For details about
-          this control group attribute, see <ulink
+          <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group
+          hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify
+          the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be
+          specified as path to a block device node or as any other file, in which case the backing block device of the
+          file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group
+          attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For
+          details about this control group attribute, see <ulink
           url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para>
 
           <para>Implies
           <literal>BlockIOAccounting=true</literal>.</para>
+
+          <para>This setting is supported only if the legacy control group hierarchy is used. Use
+          <varname>IODeviceWeight=</varname> on systems using the unified control group hierarchy.</para>
         </listitem>
       </varlistentry>
 
@@ -416,30 +407,25 @@
         <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term>
 
         <listitem>
-          <para>Use IOReadBandwidthMax and IOWriteBandwidthMax on
-          unified hierarchy.</para>
-
-          <para>Set the per-device overall block I/O bandwidth limit
-          for the executed processes. Takes a space-separated pair of
-          a file path and a bandwidth value (in bytes per second) to
-          specify the device specific bandwidth. The file path may be
-          a path to a block device node, or as any other file in which
-          case the backing block device of the file system of the file
-          is used. If the bandwidth is suffixed with K, M, G, or T,
-          the specified bandwidth is parsed as Kilobytes, Megabytes,
-          Gigabytes, or Terabytes, respectively, to the base of
-          1000. (Example:
-          "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This
-          controls the <literal>blkio.throttle.read_bps_device</literal> and
-          <literal>blkio.throttle.write_bps_device</literal> control group
-          attributes. Use this option multiple times to set bandwidth
-          limits for multiple devices. For details about these control
-          group attributes, see <ulink
+          <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control
+          group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in
+          bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device
+          node, or as any other file in which case the backing block device of the file system of the file is used. If
+          the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes,
+          Gigabytes, or Terabytes, respectively, to the base of 1000. (Example:
+          "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the
+          <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal>
+          control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For
+          details about these control group attributes, see <ulink
           url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.
           </para>
 
           <para>Implies
           <literal>BlockIOAccounting=true</literal>.</para>
+
+          <para>This setting is supported only if the legacy control group hierarchy is used. Use
+          <varname>IOReadBandwidthMax=</varname> and <varname>IOWriteBandwidthMax=</varname> on systems using the
+          unified control group hierarchy.</para>
         </listitem>
       </varlistentry>