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 <[email protected]> --- 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
