* [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior
@ 2023-10-31 20:33 Dave Jiang
2023-10-31 20:34 ` Dave Jiang
2023-11-14 22:43 ` Verma, Vishal L
0 siblings, 2 replies; 4+ messages in thread
From: Dave Jiang @ 2023-10-31 20:33 UTC (permalink / raw)
To: vishal.l.verma; +Cc: linux-cxl, nvdimm
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
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.
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior
2023-10-31 20:33 [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior Dave Jiang
@ 2023-10-31 20:34 ` Dave Jiang
2023-11-09 12:46 ` Cao, Quanquan/曹 全全
2023-11-14 22:43 ` Verma, Vishal L
1 sibling, 1 reply; 4+ messages in thread
From: Dave Jiang @ 2023-10-31 20:34 UTC (permalink / raw)
To: vishal.l.verma; +Cc: linux-cxl, nvdimm, caoqq
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.
>
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior
2023-10-31 20:34 ` Dave Jiang
@ 2023-11-09 12:46 ` Cao, Quanquan/曹 全全
0 siblings, 0 replies; 4+ messages in thread
From: Cao, Quanquan/曹 全全 @ 2023-11-09 12:46 UTC (permalink / raw)
To: Dave Jiang, vishal.l.verma; +Cc: linux-cxl, nvdimm
在 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>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior
2023-10-31 20:33 [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior Dave Jiang
2023-10-31 20:34 ` Dave Jiang
@ 2023-11-14 22:43 ` Verma, Vishal L
1 sibling, 0 replies; 4+ messages in thread
From: Verma, Vishal L @ 2023-11-14 22:43 UTC (permalink / raw)
To: Jiang, Dave; +Cc: linux-cxl, nvdimm
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2023-11-14 22:43 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-10-31 20:33 [NDCTL PATCH] cxl: Augment documentation on cxl operational behavior Dave Jiang
2023-10-31 20:34 ` Dave Jiang
2023-11-09 12:46 ` Cao, Quanquan/曹 全全
2023-11-14 22:43 ` Verma, Vishal L
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.