Apply known iocost solutions to block devices

Meta's resource control demo project[0] includes a benchmark tool that can
be used to calculate the best iocost solutions for a given SSD.

  [0]: https://github.com/facebookexperimental/resctl-demo

A project[1] has now been started to create a publicly available database
of results that can be used to apply them automatically.

  [1]: https://github.com/iocost-benchmark/iocost-benchmarks

This change adds a new tool that gets triggered by a udev rule for any
block device and queries the hwdb for known solutions. The format for
the hwdb file that is currently generated by the github action looks like
this:

  # This file was auto-generated on Tue, 23 Aug 2022 13:03:57 +0000.
  # From the following commit:
  # https://github.com/iocost-benchmark/iocost-benchmarks/commit/ca82acfe93c40f21d3b513c055779f43f1126f88
  #
  # Match key format:
  # block:<devpath>:name:<model name>:

  # 12 points, MOF=[1.346,1.346], aMOF=[1.249,1.249]
  block:*:name:HFS256GD9TNG-62A0A:fwver:*:
    IOCOST_SOLUTIONS=isolation isolated-bandwidth bandwidth naive
    IOCOST_MODEL_ISOLATION=rbps=1091439492 rseqiops=52286 rrandiops=63784 wbps=192329466 wseqiops=12309 wrandiops=16119
    IOCOST_QOS_ISOLATION=rpct=0.00 rlat=8807 wpct=0.00 wlat=59023 min=100.00 max=100.00
    IOCOST_MODEL_ISOLATED_BANDWIDTH=rbps=1091439492 rseqiops=52286 rrandiops=63784 wbps=192329466 wseqiops=12309 wrandiops=16119
    IOCOST_QOS_ISOLATED_BANDWIDTH=rpct=0.00 rlat=8807 wpct=0.00 wlat=59023 min=100.00 max=100.00
    IOCOST_MODEL_BANDWIDTH=rbps=1091439492 rseqiops=52286 rrandiops=63784 wbps=192329466 wseqiops=12309 wrandiops=16119
    IOCOST_QOS_BANDWIDTH=rpct=0.00 rlat=8807 wpct=0.00 wlat=59023 min=100.00 max=100.00
    IOCOST_MODEL_NAIVE=rbps=1091439492 rseqiops=52286 rrandiops=63784 wbps=192329466 wseqiops=12309 wrandiops=16119
    IOCOST_QOS_NAIVE=rpct=99.00 rlat=8807 wpct=99.00 wlat=59023 min=75.00 max=100.00

The IOCOST_SOLUTIONS key lists the solutions available for that device
in the preferred order for higher isolation, which is a reasonable
default for most client systems. This can be overriden to choose better
defaults for custom use cases, like the various data center workloads.

The tool can also be used to query the known solutions for a specific
device or to apply a non-default solution (say, isolation or bandwidth).

Co-authored-by: Santosh Mahto <santosh.mahto@collabora.com>

2 files changed, 77 insertions, 0 deletions

diff --git a/man/iocost.conf.xml b/man/iocost.conf.xml
new file mode 100644
index 0000000000..be74244267
--- /dev/null
+++ b/man/iocost.conf.xml
@@ -0,0 +1,76 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="iocost.conf" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <refentryinfo>
+    <title>iocost.conf</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>iocost.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>iocost.conf</refname>
+    <refpurpose>Configuration files for the iocost solution manager</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para>
+      <filename>/etc/systemd/iocost.conf</filename>
+      <filename>/etc/systemd/iocost.conf.d/*.conf</filename>
+    </para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>This file configures the behavior of <literal>iocost</literal>, a tool mostly used by
+    <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry> rules
+    to automatically apply I/O cost solutions to <filename>/sys/fs/cgroup/io.cost.*</filename>.</para>
+
+    <para>The qos and model values are calculated based on benchmarks collected on the
+    <ulink url="https://github.com/iocost-benchmark/iocost-benchmarks">iocost-benchmark</ulink>
+    project and turned into a set of solutions that go from most to least isolated.
+    Isolation allows the system to remain responsive in face of high I/O load.
+    Which solutions are available for a device can be queried from the udev metadata attached to it. By
+    default the naive solution is used, which provides the most bandwidth.</para>
+  </refsect1>
+
+  <xi:include href="standard-conf.xml" xpointer="main-conf" />
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>All options are configured in the [IOCost] section:</para>
+
+    <variablelist class='config-directives'>
+
+      <varlistentry>
+        <term><varname>TargetSolution=</varname></term>
+
+        <listitem><para>Chooses which I/O cost solution (identified by named string) should be used
+        for the devices in this system. The known solutions can be queried from the udev metadata
+        attached to the devices. If a device does not have the specified solution, the first one
+        listed in <varname>IOCOST_SOLUTIONS</varname> is used instead.</para>
+
+        <para>E.g. <literal>TargetSolution=isolated-bandwidth</literal>.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <ulink url="https://github.com/iocost-benchmark/iocost-benchmarks">The iocost-benchmarks github project</ulink>,
+      <ulink url="https://github.com/facebookexperimental/resctl-demo/tree/main/resctl-bench/doc">The resctl-bench
+      documentation details how the values are obtained</ulink>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/rules/meson.build b/man/rules/meson.build
index cdf98eaaf0..ca3b471281 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -24,6 +24,7 @@ manpages = [
  ['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'],
  ['hwdb', '7', [], 'ENABLE_HWDB'],
  ['integritytab', '5', [], 'HAVE_LIBCRYPTSETUP'],
+ ['iocost.conf', '5', [], ''],
  ['journal-remote.conf', '5', ['journal-remote.conf.d'], 'HAVE_MICROHTTPD'],
  ['journal-upload.conf', '5', ['journal-upload.conf.d'], 'HAVE_MICROHTTPD'],
  ['journalctl', '1', [], ''],