1CXL-LIST(1)                                                        CXL-LIST(1)
2
3
4

NAME

6       cxl-list - List platform CXL objects, and their attributes, in json.
7

SYNOPSIS

9       cxl list [<options>]
10
11       Walk the CXL capable device hierarchy in the system and list all device
12       instances along with some of their major attributes.
13
14       Options can be specified to limit the output to specific objects. When
15       a single object type is specified the return json object is an array of
16       just those objects, when multiple objects types are specified the
17       returned the returned object may be an array of arrays with the inner
18       array named for the given object type. The top-level arrays are ellided
19       when the objects can nest under a higher object-type in the
20       hierararchy. The potential top-level array names and their nesting
21       properties are:
22
23       "anon memdevs"
24           (disabled memory devices) do not nest
25
26       "buses"
27           do not nest
28
29       "ports"
30           nest under buses
31
32       "endpoints"
33           nest under ports or buses (if ports are not emitted)
34
35       "memdevs"
36           nest under endpoints or ports (if endpoints are not emitted) or
37           buses (if endpoints and ports are not emitted)
38
39       "root decoders"
40           nest under buses
41
42       "port decoders"
43           nest under ports, or buses (if ports are not emitted)
44
45       "endpoint decoders"
46           nest under endpoints, or ports (if endpoints are not emitted) or
47           buses (if endpoints and ports are not emitted)
48
49       Filters can by specifed as either a single identidier, a space
50       separated quoted string, or a comma separated list. When multiple
51       filter identifiers are specified within a filter string, like "-m
52       mem0,mem1,mem2", they are combined as an OR filter. When multiple
53       filter string types are specified, like "-m mem0,mem1,mem2 -p port10",
54       they are combined as an AND filter. So, "-m mem0,mem1,mem2 -p port10"
55       would only list objects that are beneath port10 AND map mem0, mem1, OR
56       mem2.
57
58       Given that many topology queries seek to answer questions relative to a
59       given memdev, buses, ports, endpoints, and decoders can be filtered by
60       one or more memdevs. For example:
61
62       # cxl list -P -p switch,endpoint -m mem0
63       [
64         {
65           "port":"port1",
66           "host":"ACPI0016:00",
67           "endpoints:port1":[
68             {
69               "endpoint":"endpoint2",
70               "host":"mem0"
71             }
72           ]
73         }
74       ]
75
76       Additionally, when provisioning new interleave configurations it is
77       useful to know which memdevs can be referenced by a given decoder like
78       a root decoder, or mapped by a given port if the decoders are not
79       configured.
80
81       # cxl list -Mu -d decoder0.0
82       {
83         "memdev":"mem0",
84         "pmem_size":"256.00 MiB (268.44 MB)",
85         "ram_size":0,
86         "serial":"0",
87         "host":"0000:35:00.0"
88       }
89
90       The --human option in addition to reformatting some fields to more
91       human friendly strings also unwraps the array to reduce the number of
92       lines of output.
93

EXAMPLE

95           # cxl list --memdevs
96           [
97             {
98               "memdev":"mem0",
99               "pmem_size":268435456,
100               "ram_size":0,
101               "serial":0,
102               "host":"0000:35:00.0"
103             }
104           ]
105
106           # cxl list -BMu
107           [
108             {
109               "anon memdevs":[
110                 {
111                   "memdev":"mem0",
112                   "pmem_size":"256.00 MiB (268.44 MB)",
113                   "ram_size":0,
114                   "serial":"0"
115                 }
116               ]
117             },
118             {
119               "buses":[
120                 {
121                   "bus":"root0",
122                   "provider":"ACPI.CXL"
123                 }
124               ]
125             }
126           ]
127

OPTIONS

129       -m, --memdev=
130           Specify CXL memory device name(s), or device id(s), to filter the
131           listing. For example:
132
133           # cxl list -M --memdev="0 mem3 5"
134           [
135             {
136               "memdev":"mem0",
137               "pmem_size":268435456,
138               "ram_size":0,
139               "serial":0
140             },
141             {
142               "memdev":"mem3",
143               "pmem_size":268435456,
144               "ram_size":268435456,
145               "serial":2
146             },
147             {
148               "memdev":"mem5",
149               "pmem_size":268435456,
150               "ram_size":268435456,
151               "serial":4
152             }
153           ]
154
155       -s, --serial=
156           Specify CXL memory device serial number(s) to filter the listing
157
158       -M, --memdevs
159           Include CXL memory devices in the listing
160
161       -i, --idle
162           Include idle (not enabled / zero-sized) devices in the listing
163
164       -H, --health
165           Include health information in the memdev listing. Example listing:
166
167           # cxl list -m mem0 -H
168           [
169             {
170               "memdev":"mem0",
171               "pmem_size":268435456,
172               "ram_size":268435456,
173               "health":{
174                 "maintenance_needed":true,
175                 "performance_degraded":true,
176                 "hw_replacement_needed":true,
177                 "media_normal":false,
178                 "media_not_ready":false,
179                 "media_persistence_lost":false,
180                 "media_data_lost":true,
181                 "media_powerloss_persistence_loss":false,
182                 "media_shutdown_persistence_loss":false,
183                 "media_persistence_loss_imminent":false,
184                 "media_powerloss_data_loss":false,
185                 "media_shutdown_data_loss":false,
186                 "media_data_loss_imminent":false,
187                 "ext_life_used":"normal",
188                 "ext_temperature":"critical",
189                 "ext_corrected_volatile":"warning",
190                 "ext_corrected_persistent":"normal",
191                 "life_used_percent":15,
192                 "temperature":25,
193                 "dirty_shutdowns":10,
194                 "volatile_errors":20,
195                 "pmem_errors":30
196               }
197             }
198           ]
199
200       -I, --partition
201           Include partition information in the memdev listing. Example
202           listing:
203
204           # cxl list -m mem0 -I
205           [
206             {
207               "memdev":"mem0",
208               "pmem_size":0,
209               "ram_size":273535729664,
210               "partition_info":{
211                 "total_size":273535729664,
212                 "volatile_only_size":0,
213                 "persistent_only_size":0,
214                 "partition_alignment_size":268435456
215                 "active_volatile_size":273535729664,
216                 "active_persistent_size":0,
217                 "next_volatile_size":0,
218                 "next_persistent_size":0,
219               }
220             }
221           ]
222
223       -B, --buses
224           Include bus / CXL root object(s) in the listing. Typically, on ACPI
225           systems the bus object is a singleton associated with the ACPI0017
226           device, but there are test scenerios where there may be multiple
227           CXL memory hierarchies.
228
229           # cxl list -B
230           [
231             {
232               "bus":"root3",
233               "provider":"cxl_test"
234             },
235             {
236               "bus":"root0",
237               "provider":"ACPI.CXL"
238             }
239           ]
240
241       -b, --bus=
242           Specify CXL root device name(s), device id(s), and / or CXL bus
243           provider names to filter the listing. The supported provider names
244           are "ACPI.CXL" and "cxl_test".
245
246       -P, --ports
247           Include port objects (CXL / PCIe root ports + Upstream Switch
248           Ports) in the listing.
249
250       -p, --port=
251           Specify CXL Port device name(s), device id(s), and or port type
252           names to filter the listing. The supported port type names are
253           "root" and "switch". Note that since a bus object is also a port,
254           the following two syntaxes are equivalent:
255
256           # cxl list -B
257           # cxl list -P -p root
258
259           Additionally, endpoint objects are also ports so the following commands
260           are also equivalent.
261
262           # cxl list -E
263           # cxl list -P -p endpoint
264
265           By default, only 'switch' ports are listed.
266
267       -S, --single
268           Specify whether the listing should emit all the objects that are
269           descendants of a port that matches the port filter, or only direct
270           descendants of the individual ports that match the filter. By
271           default all descendant objects are listed.
272
273       -E, --endpoints
274           Include endpoint objects (CXL Memory Device decoders) in the
275           listing.
276
277           # cxl list -E
278           [
279             {
280               "endpoint":"endpoint2",
281               "host":"mem0"
282             }
283           ]
284
285       -e, --endpoint
286           Specify CXL endpoint device name(s), or device id(s) to filter the
287           emitted endpoint(s).
288
289       -D, --decoders
290           Include decoder objects (CXL Memory decode capability instances in
291           buses, ports, and endpoints) in the listing.
292
293       -d, --decoder
294           Specify CXL decoder device name(s), device id(s), or decoder type
295           names to filter the emitted decoder(s). The format for a decoder
296           name is "decoder<port_id>.<instance_id>". The possible decoder type
297           names are "root", "switch", or "endpoint", similar to the port
298           filter syntax.
299
300       -T, --targets
301           Extend decoder listings with downstream port target information,
302           and / or port and bus listings with the downstream port
303           information.
304
305           # cxl list -BTu -b ACPI.CXL
306           {
307             "bus":"root0",
308             "provider":"ACPI.CXL",
309             "nr_dports":1,
310             "dports":[
311               {
312                 "dport":"ACPI0016:00",
313                 "alias":"pci0000:34",
314                 "id":"0"
315               }
316             ]
317           }
318
319       --debug
320           If the cxl tool was built with debug enabled, turn on debug
321           messages.
322
323       -u, --human
324           By default the command will output machine-friendly raw-integer
325           data. Instead, with this flag, numbers representing storage size
326           will be formatted as human readable strings with units, other
327           fields are converted to hexadecimal strings.
328
330       Copyright © 2016 - 2022, Intel Corporation. License GPLv2: GNU GPL
331       version 2 http://gnu.org/licenses/gpl.html. This is free software: you
332       are free to change and redistribute it. There is NO WARRANTY, to the
333       extent permitted by law.
334

SEE ALSO

336       linkcxl:ndctl-list[1]
337
338
339
340                                  03/08/2022                       CXL-LIST(1)
Impressum