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