[PATCH v8 7/7] Documentation: Add docs for protocol and poison injection commands

[Ben Cheatham <Benjamin.Cheatham@amd.com>]

Add man pages for the 'cxl-inject-protocol-error', 'cxl-inject-media-poison',
and 'cxl-clear-media-poison' commands. These man pages show usage and examples
for each of their use cases.

Signed-off-by: Ben Cheatham <Benjamin.Cheatham@amd.com>
---
 Documentation/cxl/cxl-clear-media-poison.txt  |  85 ++++++++++++++
 Documentation/cxl/cxl-inject-media-poison.txt |  85 ++++++++++++++
 .../cxl/cxl-inject-protocol-error.txt         | 105 ++++++++++++++++++
 Documentation/cxl/meson.build                 |   3 +
 4 files changed, 278 insertions(+)
 create mode 100644 Documentation/cxl/cxl-clear-media-poison.txt
 create mode 100644 Documentation/cxl/cxl-inject-media-poison.txt
 create mode 100644 Documentation/cxl/cxl-inject-protocol-error.txt

diff --git a/Documentation/cxl/cxl-clear-media-poison.txt b/Documentation/cxl/cxl-clear-media-poison.txt
new file mode 100644
index 0000000..3c997b5
--- /dev/null
+++ b/Documentation/cxl/cxl-clear-media-poison.txt
@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: GPL-2.0
+
+cxl-clear-media-poison(1)
+=========================
+
+NAME
+----
+cxl-clear-media-poison - Clear poison from CXL memory
+
+SYNOPSIS
+--------
+[verse]
+'cxl clear-media-poison' <memdev> [<options>]
+
+Clear poison from a CXL memory device's memory. CXL memdevs can be specified
+by device name (e.g. "mem0"), device id ("X" in "memX"), or host device name
+("0000:35:00.0").
+
+To see if a device has poison that can be cleared use the 'cxl-list' command
+with the '-L'/'--media-errors' option. An example of a device that has had
+poison injected at device physical address (a.k.a. "offset") 0x1000:
+
+----
+# cxl list -m mem0 -L -u
+{
+  "memdev":"mem0",
+  "ram_size":"1024.00 MiB (1073.74 MB)",
+  "ram_qos_class":42,
+  "serial":"0x0",
+  "numa_node:1,
+  "host":"0000:35:00.0",
+  "media_errors":[
+    {
+	  "offset":"0x1000",
+	  "length":64,
+	  "source":"Injected"
+	}
+  ]
+}
+
+----
+
+A device physical address is required to clear poison from a CXL memdev. The
+'-a'/'--address' option is used to specify the address to clear poison at.
+The address can be given in either decimal or hexadecimal. An example using
+the example device above:
+
+----
+# cxl clear-media-poison mem0 -a 0x1000
+poison cleared at mem0:0x1000
+
+# cxl list -m mem0 -L -u
+{
+  "memdev":"mem0",
+  "ram_size":"1024.00 MiB (1073.74 MB)",
+  "ram_qos_class":42,
+  "serial":"0x0",
+  "numa_node:1,
+  "host":"0000:35:00.0",
+  "media_errors":[
+  ]
+}
+
+----
+
+See the 'inject-media-poison' command for how to inject poison into a CXL
+memory device.
+
+This command depends on the CXL debug filesystem (normally mounted at
+"/sys/kernel/debug/cxl") to clear device poison.
+
+OPTIONS
+-------
+-a::
+--address::
+	Device physical address (DPA) to clear poison at. Address can
+	be specified in hex or decimal.
+
+--debug::
+	Enable debug output
+
+SEE ALSO
+--------
+linkcxl:cxl-list[1]
+linkcxl:cxl-clear-media-poison[1]
diff --git a/Documentation/cxl/cxl-inject-media-poison.txt b/Documentation/cxl/cxl-inject-media-poison.txt
new file mode 100644
index 0000000..d35f1dc
--- /dev/null
+++ b/Documentation/cxl/cxl-inject-media-poison.txt
@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: GPL-2.0
+
+cxl-inject-media-poison(1)
+==========================
+
+NAME
+----
+cxl-inject-media-poison - Inject poison into CXL memory
+
+SYNOPSIS
+--------
+[verse]
+'cxl inject-media-poison' <memdev> [<options>]
+
+WARNING: Poison injection can cause system instability and should only be used
+for debugging hardware and software error recovery flows. Use at your own risk!
+
+Inject poison into a CXL memory device's memory. CXL memdevs can be specified
+by device name (e.g. "mem0"), device id ("X" in "memX"), or host device name
+("0000:35:00.0").
+
+Poison can only be used with CXL memory devices with poison injection support.
+To see which CXL devices support poison injection, see the "poison_injectable"
+attribute under the device in 'cxl-list'. An example of a device that
+supports poison injection:
+
+----
+# cxl list -u -m mem0
+{
+	"memdev":"mem0",
+	"ram_size":"256.00 MiB (268.44 MB)",
+	"serial":"0",
+	"host":"0000:0d:00.0",
+	"firmware_version":"BWFW VERSION 00",
+	"poison_injectable":true
+}
+
+----
+
+A device physical address is required for poison injection. The '-a'/'--address'
+option is used to specify the device physical address to inject poison to. The
+address can be given in either decimal or hexadecimal. For example:
+
+----
+# cxl inject-media-poison mem0 -a 0x1000
+poison inject at mem0:0x1000
+# cxl list -m mem0 -u --media-errors
+{
+  "memdev":"mem0",
+  "ram_size":"256.00 MiB (268.44 MB)",
+  "serial":"0",
+  "host":"0000:0d:00.0",
+  "firmware_version":"BWFW VERSION 00",
+  "media_errors":[
+    {
+      "offset":"0x1000",
+      "length":64,
+      "source":"Injected"
+    }
+  ]
+}
+
+----
+
+See the 'clear-media-poison' command for how to clear poison from a CXL
+memory device.
+
+This command relies on the CXL debugfs to inject poison (normally mounted
+at "/sys/kernel/debug/cxl"). If the CXL debugfs is inaccesible, the
+"poison_injectable" attribute will always be set to "false".
+
+OPTIONS
+-------
+-a::
+--address::
+	Device physical address (DPA) to use for poison injection. Address can
+	be specified in hex or decimal. Required for poison injection.
+
+--debug::
+	Enable debug output
+
+SEE ALSO
+--------
+linkcxl:cxl-list[1]
+linkcxl:cxl-clear-media-poison[1]
diff --git a/Documentation/cxl/cxl-inject-protocol-error.txt b/Documentation/cxl/cxl-inject-protocol-error.txt
new file mode 100644
index 0000000..196b6f6
--- /dev/null
+++ b/Documentation/cxl/cxl-inject-protocol-error.txt
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: GPL-2.0
+
+cxl-inject-protocol-error(1)
+============================
+
+NAME
+----
+cxl-inject-protocol-error - Inject CXL protocol errors into CXL downstream ports
+
+SYNOPSIS
+--------
+[verse]
+'cxl inject-protocol-error' <dport> [<options>]
+
+WARNING: Error injection can cause system instability and should only be used
+for debugging hardware and software error recovery flows. Use at your own risk!
+
+Inject a CXL protocol error into a CXL downstream port (dport). Donwstream ports
+that support error injection will have their 'protocol_injectable' attribute
+in 'cxl-list' set to true.
+
+The '-p'/'--protocol' and '-s'/'--severity' options are required for error injection.
+The '-p' option is used to specify the CXL protocol to inject an error on; either
+"mem" (CXL.mem) or "cache" (CXL.cache). The '-s' option specifies the severity
+of the error and can be one of: "correctable", "uncorrectable", or "fatal".
+
+The types of errors (and severities) available depends on the platform. To find
+the available error types for injection, see the "injectable_protocol_errors"
+attribute under the applicable CXL bus object in the output of 'cxl-list'.
+For example:
+
+----
+
+# cxl list -B
+[
+  {
+	"bus":"root0",
+	"provider":"ACPI.CXL",
+	"injectable_protocol_errors":[
+	  "mem-correctable",
+	  "mem-fatal",
+	]
+  }
+]
+
+----
+
+The dport to inject an error into is specified by host name (e.g. "0000:0e:01.1").
+Here's an example injection using the example bus listing above:
+
+----
+
+# cxl list -TP
+ [
+  {
+    "port":"port1",
+    "host":"pci0000:e0",
+    "depth":1,
+    "decoders_committed":1,
+    "nr_dports":1,
+    "dports":[
+      {
+        "dport":"0000:e0:01.1",
+        "alias":"device:02",
+        "id":0,
+        "protocol_injectable":true
+      }
+    ]
+  }
+]
+
+# cxl inject-protocol-error "0000:e0:01.1" -p mem -s correctable
+cxl inject-protocol-error: inject_proto_err: injected mem-correctable protocol error.
+
+----
+
+CXL protocol (CXL.cache/mem) error injection requires the platform to support
+ACPI v6.5+ error injection (EINJ). In addition to platform support, the
+CONFIG_ACPI_APEI_EINJ and CONFIG_ACPI_APEI_EINJ_CXL kernel configuration options
+must be enabled. For more information, view the Linux kernel documentation on EINJ.
+
+This command depends on the CXL debug filesystem (normally mounted at
+"/sys/kernel/debug/cxl") to inject protocol errors. If the CXL debugfs is not
+accessible the "protocol_injectable" attribute of dports will always be
+set to false, and the "injectable_protocol_errors" attribute of CXL busses
+will always be empty.
+
+OPTIONS
+-------
+-p::
+--protocol::
+	Which CXL protocol to inject an error on. Can be either "mem" (CXL.mem)
+	or "cache (CXL.cache).
+
+-s::
+--severity::
+	Severity level of error to be injected. Can be one of the following:
+	"correctable", "uncorrectable", or "fatal".
+
+--debug::
+	Enable debug output
+
+SEE ALSO
+--------
+linkcxl:cxl-list[1]
diff --git a/Documentation/cxl/meson.build b/Documentation/cxl/meson.build
index 8085c1c..c4b22ab 100644
--- a/Documentation/cxl/meson.build
+++ b/Documentation/cxl/meson.build
@@ -50,6 +50,9 @@ cxl_manpages = [
   'cxl-update-firmware.txt',
   'cxl-set-alert-config.txt',
   'cxl-wait-sanitize.txt',
+  'cxl-inject-protocol-error.txt',
+  'cxl-inject-media-poison.txt',
+  'cxl-clear-media-poison.txt',
 ]
 
 foreach man : cxl_manpages
-- 
2.52.0