Re: [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior

[Cao , Quanquan/曹 全全]

在 2023/11/1 4:34, Dave Jiang 写道:

On 10/31/23 13:33, Dave Jiang wrote:

If a cxl operation is executed resulting in no-op, the tool will still
emit the number of targets the operation has succeeded on. For example, if
disable-region is issued and the region is already disabled, the tool will
still report 1 region disabled. Add verbiage to man pages to document the
behavior.

Signed-off-by: Dave Jiang <dave.ji...@intel.com>

Cc Quanquan

---
  Documentation/cxl/cxl-disable-bus.txt    |    2 ++
  Documentation/cxl/cxl-disable-memdev.txt |    1 +
  Documentation/cxl/cxl-disable-port.txt   |    2 ++
  Documentation/cxl/cxl-disable-region.txt |    2 ++
  Documentation/cxl/cxl-enable-memdev.txt  |    2 ++
  Documentation/cxl/cxl-enable-port.txt    |    2 ++
  Documentation/cxl/cxl-enable-region.txt  |    2 ++
  Documentation/cxl/meson.build            |    1 +
  Documentation/cxl/operations.txt         |   17 +++++++++++++++++
  9 files changed, 31 insertions(+)
  create mode 100644 Documentation/cxl/operations.txt

diff --git a/Documentation/cxl/cxl-disable-bus.txt 
b/Documentation/cxl/cxl-disable-bus.txt
index 65f695cd06c8..992a25ec8506 100644
--- a/Documentation/cxl/cxl-disable-bus.txt
+++ b/Documentation/cxl/cxl-disable-bus.txt
@@ -15,6 +15,8 @@ SYNOPSIS
  For test and debug scenarios, disable a CXL bus and any associated
  memory devices from CXL.mem operations.

+include::operations.txt[]

+
  OPTIONS
  -------
  -f::
diff --git a/Documentation/cxl/cxl-disable-memdev.txt 
b/Documentation/cxl/cxl-disable-memdev.txt
index d39780250939..fc7eeee61c3e 100644
--- a/Documentation/cxl/cxl-disable-memdev.txt
+++ b/Documentation/cxl/cxl-disable-memdev.txt
@@ -12,6 +12,7 @@ SYNOPSIS
  [verse]
  'cxl disable-memdev' <mem0> [<mem1>..<memN>] [<options>]

+include::operations.txt[] OPTIONS

  -------
diff --git a/Documentation/cxl/cxl-disable-port.txt 
b/Documentation/cxl/cxl-disable-port.txt
index 7a22efc3b821..451aa01fefdd 100644
--- a/Documentation/cxl/cxl-disable-port.txt
+++ b/Documentation/cxl/cxl-disable-port.txt
@@ -15,6 +15,8 @@ SYNOPSIS
  For test and debug scenarios, disable a CXL port and any memory devices
  dependent on this port being active for CXL.mem operation.

+include::operations.txt[]

+
  OPTIONS
  -------
  -e::
diff --git a/Documentation/cxl/cxl-disable-region.txt 
b/Documentation/cxl/cxl-disable-region.txt
index 6a39aee6ea69..4b0625e40bf6 100644
--- a/Documentation/cxl/cxl-disable-region.txt
+++ b/Documentation/cxl/cxl-disable-region.txt
@@ -21,6 +21,8 @@ EXAMPLE
  disabled 2 regions
  ----

+include::operations.txt[]

+
  OPTIONS
  -------
  include::bus-option.txt[]
diff --git a/Documentation/cxl/cxl-enable-memdev.txt 
b/Documentation/cxl/cxl-enable-memdev.txt
index 5b5ed66eadc5..436f063e5517 100644
--- a/Documentation/cxl/cxl-enable-memdev.txt
+++ b/Documentation/cxl/cxl-enable-memdev.txt
@@ -18,6 +18,8 @@ it again. This involves detecting the state of the HDM (Host 
Managed
  Device Memory) Decoders and validating that CXL.mem is enabled for each
  port in the device's hierarchy.

+include::operations.txt[]

+
  OPTIONS
  -------
  <memory device(s)>::
diff --git a/Documentation/cxl/cxl-enable-port.txt 
b/Documentation/cxl/cxl-enable-port.txt
index 50b53d1f48d1..8b51023d2e16 100644
--- a/Documentation/cxl/cxl-enable-port.txt
+++ b/Documentation/cxl/cxl-enable-port.txt
@@ -18,6 +18,8 @@ again. This involves detecting the state of the HDM (Host 
Managed Device
  Memory) Decoders and validating that CXL.mem is enabled for each port in
  the device's hierarchy.

+include::operations.txt[]

+
  OPTIONS
  -------
  -e::
diff --git a/Documentation/cxl/cxl-enable-region.txt 
b/Documentation/cxl/cxl-enable-region.txt
index f6ef00fb945d..f3d3d9db1674 100644
--- a/Documentation/cxl/cxl-enable-region.txt
+++ b/Documentation/cxl/cxl-enable-region.txt
@@ -21,6 +21,8 @@ EXAMPLE
  enabled 2 regions
  ----

+include::operations.txt[]

+
  OPTIONS
  -------
  include::bus-option.txt[]
diff --git a/Documentation/cxl/meson.build b/Documentation/cxl/meson.build
index c5533572ef75..7c70956c3b53 100644
--- a/Documentation/cxl/meson.build
+++ b/Documentation/cxl/meson.build
@@ -25,6 +25,7 @@ filedeps = [
    'debug-option.txt',
    'region-description.txt',
    'decoder-option.txt',
+  'operations.txt',
  ]

cxl_manpages = [

diff --git a/Documentation/cxl/operations.txt b/Documentation/cxl/operations.txt
new file mode 100644
index 000000000000..046e2bc19532
--- /dev/null
+++ b/Documentation/cxl/operations.txt
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: gpl-2.0
+
+Given any en/disabling operation, if the operation is a no-op due to the
+current state of a target, it is still considered successful when executed
+even if no actual operation is performed. The target applies to a bus,
+decoder, memdev, or region.
+
+For example:
+If a CXL region is already disabled and the cxl disable-region is called:
+
+----
+# cxl disable-region region0
+disabled 1 regions
+----
+
+The operation will still succeed with the number of regions operated on
+reported, even if the operation is a non-action.

Hi Dave,

Thanks for adding this description. It's easier for our user to understand.

Reviewed-by: Quanquan Cao <ca...@fujitsu.com>