Blame SOURCES/0188-cxl-list-Clarify-B-vs-P-p-root.patch

e0018b
From db55c5254d932d8d1be1fc082ea7a919def47a5d Mon Sep 17 00:00:00 2001
e0018b
From: Dan Williams <dan.j.williams@intel.com>
e0018b
Date: Tue, 26 Jul 2022 18:54:54 -0700
e0018b
Subject: [PATCH 188/217] cxl/list: Clarify "-B" vs "-P -p root"
e0018b
e0018b
Matthew notes that 'cxl list' documentation claims that 'cxl list -B' and
e0018b
'cxl list -P -p root' are equivalent. Which they are not:
e0018b
e0018b
$ cxl list -B
e0018b
[
e0018b
  {
e0018b
    "bus":"root0",
e0018b
    "provider":"ACPI.CXL"
e0018b
  }
e0018b
]
e0018b
e0018b
$ cxl list -P -p root
e0018b
[
e0018b
  {
e0018b
    "bus":"root0",
e0018b
    "provider":"ACPI.CXL",
e0018b
    "ports:root0":[
e0018b
      {
e0018b
        "port":"port1",
e0018b
        "host":"ACPI0016:00"
e0018b
      }
e0018b
    ]
e0018b
  }
e0018b
]
e0018b
e0018b
Clarify that '--single' needs to be appended to '-P -p root' to make it
e0018b
equivalent to 'cxl list -B'. This is due to the behavior that listing ports
e0018b
includes all descendants of a port that matches the filter. In the case of
e0018b
'-P -p root' that results in all enabled ports.
e0018b
e0018b
$ cxl list -P -p root -S
e0018b
[
e0018b
  {
e0018b
    "bus":"root0",
e0018b
    "provider":"ACPI.CXL"
e0018b
  }
e0018b
]
e0018b
e0018b
Link: https://lore.kernel.org/r/165888675979.3375698.5785835464908538946.stgit@dwillia2-xfh.jf.intel.com
e0018b
Cc: Adam Manzanares <a.manzanares@samsung.com>
e0018b
Reported-by: Matthew Ho <sunfishho12@gmail.com>
e0018b
Signed-off-by: Dan Williams <dan.j.williams@intel.com>
e0018b
Signed-off-by: Vishal Verma <vishal.l.verma@intel.com>
e0018b
---
e0018b
 Documentation/cxl/cxl-list.txt | 20 ++++++++++++++------
e0018b
 1 file changed, 14 insertions(+), 6 deletions(-)
e0018b
e0018b
diff --git a/Documentation/cxl/cxl-list.txt b/Documentation/cxl/cxl-list.txt
e0018b
index f6aba0c..088ea70 100644
e0018b
--- a/Documentation/cxl/cxl-list.txt
e0018b
+++ b/Documentation/cxl/cxl-list.txt
e0018b
@@ -255,19 +255,27 @@ OPTIONS
e0018b
 --port=::
e0018b
 	Specify CXL Port device name(s), device id(s), and or port type
e0018b
 	names to filter the listing. The supported port type names are "root"
e0018b
-	and "switch". Note that since a bus object is also a port, the following
e0018b
-	two syntaxes are equivalent:
e0018b
+	and "switch". Note that a bus object is also a port, so the
e0018b
+	following two syntaxes are equivalent:
e0018b
 ----
e0018b
 # cxl list -B
e0018b
-# cxl list -P -p root
e0018b
+# cxl list -P -p root -S
e0018b
 ----
e0018b
-	Additionally, endpoint objects are also ports so the following commands
e0018b
-	are also equivalent.
e0018b
+	...where the '-S/--single' is required since descendant ports are always
e0018b
+	included in a port listing and '-S/--single' stops after listing the
e0018b
+	bus.  Additionally, endpoint objects are ports so the following commands
e0018b
+	are equivalent, and no '-S/--single' is required as endpoint ports are
e0018b
+	terminal:
e0018b
 ----
e0018b
 # cxl list -E
e0018b
 # cxl list -P -p endpoint
e0018b
 ----
e0018b
-	By default, only 'switch' ports are listed.
e0018b
+	By default, only 'switch' ports are listed, i.e.
e0018b
+----
e0018b
+# cxl list -P
e0018b
+# cxl list -P -p switch
e0018b
+----
e0018b
+	...are equivalent.
e0018b
 
e0018b
 -S::
e0018b
 --single::
e0018b
-- 
e0018b
2.27.0
e0018b