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

[Dave Jiang <dave.jiang@intel.com>]

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.jiang@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.
> 
>