diff mbox series

[NDCTL] cxl: Augment documentation on cxl operational behavior

Message ID 169878439580.80025.16527732447076656149.stgit@djiang5-mobl3
State New, archived
Headers show
Series [NDCTL] cxl: Augment documentation on cxl operational behavior | expand

Commit Message

Dave Jiang Oct. 31, 2023, 8:33 p.m. UTC
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>
---
 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

Comments

Dave Jiang Oct. 31, 2023, 8:34 p.m. UTC | #1
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.
> 
>
Cao, Quanquan/曹 全全 Nov. 9, 2023, 12:46 p.m. UTC | #2
在 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.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.
>>

Hi Dave,

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

Reviewed-by: Quanquan Cao <caoqq@fujitsu.com>
Verma, Vishal L Nov. 14, 2023, 10:43 p.m. UTC | #3
On Tue, 2023-10-31 at 13:33 -0700, Dave Jiang wrote:

I think a more specific subject like:

cxl/Documentation: Clarify that no-op is a success for xable commands

is better?

> If a cxl operation is executed resulting in no-op, the tool will still

.. cxl enable or disable operation ..

> 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>
> ---
>  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/operations.txt b/Documentation/cxl/operations.txt
> new file mode 100644

Maybe call this xable-no-op.txt, 'operations' sounds a bit vague.

> 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

..enable or disable command..

> +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,

.. the target can be 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.

Looking at the man page for say disable-memdev, and seeing a region
command in the example feels slightly awkward.. I wonder if we can just
drop the example, and rely only on the text description.
diff mbox series

Patch

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.