[ndctl] cxl/list: Clarify "-B" vs "-P -p root"

Commit Message

Dan Williams July 27, 2022, 1:54 a.m. UTC

Matthew notes that 'cxl list' documentation claims that 'cxl list -B' and
'cxl list -P -p root' are equivalent. Which they are not:


$ cxl list -B
[
  {
    "bus":"root0",
    "provider":"ACPI.CXL"
  }
]

$ cxl list -P -p root
[
  {
    "bus":"root0",
    "provider":"ACPI.CXL",
    "ports:root0":[
      {
        "port":"port1",
        "host":"ACPI0016:00"
      }
    ]
  }
]

Clarify that '--single' needs to be appended to '-P -p root' to make it
equivalent to 'cxl list -B'. This is due to the behavior that listing ports
includes all descendants of a port that matches the filter. In the case of
'-P -p root' that results in all enabled ports.

$ cxl list -P -p root -S
[
  {
    "bus":"root0",
    "provider":"ACPI.CXL"
  }
]

Reported-by: Matthew Ho <[e-mail]>
Cc: Adam Manzanares <[e-mail]>
Signed-off-by: Dan Williams <[e-mail]>
---
Matthew, Adam, from today's discussion, turns out the deeper
documentation is not needed and the host bridge being included is by
design of showing enabled descdendants in a -P listing. Here's the
smaller doc fixup for that.

 Documentation/cxl/cxl-list.txt |   20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

Patch

diff --git a/Documentation/cxl/cxl-list.txt b/Documentation/cxl/cxl-list.txt
index f6aba0c5c1fa..088ea700c154 100644
--- a/Documentation/cxl/cxl-list.txt
+++ b/Documentation/cxl/cxl-list.txt
@@ -255,19 +255,27 @@  OPTIONS
 --port=::
 	Specify CXL Port device name(s), device id(s), and or port type
 	names to filter the listing. The supported port type names are "root"
-	and "switch". Note that since a bus object is also a port, the following
-	two syntaxes are equivalent:
+	and "switch". Note that a bus object is also a port, so the
+	following two syntaxes are equivalent:
 ----
 # cxl list -B
-# cxl list -P -p root
+# cxl list -P -p root -S
 ----
-	Additionally, endpoint objects are also ports so the following commands
-	are also equivalent.
+	...where the '-S/--single' is required since descendant ports are always
+	included in a port listing and '-S/--single' stops after listing the
+	bus.  Additionally, endpoint objects are ports so the following commands
+	are equivalent, and no '-S/--single' is required as endpoint ports are
+	terminal:
 ----
 # cxl list -E
 # cxl list -P -p endpoint
 ----
-	By default, only 'switch' ports are listed.
+	By default, only 'switch' ports are listed, i.e.
+----
+# cxl list -P
+# cxl list -P -p switch
+----
+	...are equivalent.
 
 -S::
 --single::