1CXL-LIST(1) CXL-LIST(1)
2
6 cxl-list - List platform CXL objects, and their attributes, in json.
7
9 cxl list [<options>]
10 Walk the CXL capable device hierarchy in the system and list all device
12 instances along with some of their major attributes.
13 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 object may be an array of arrays with the inner array named
18 for the given object type. The top-level arrays are elided when the
19 objects can nest under a higher object-type in the hierarchy. The
20 potential top-level array names and their nesting properties are:
21 "anon memdevs"
23 (disabled memory devices) do not nest
24 "buses"
26 do not nest
27 "ports"
29 nest under buses
30 "endpoints"
32 nest under ports or buses (if ports are not emitted)
33 "memdevs"
35 nest under endpoints or ports (if endpoints are not emitted) or
36 buses (if endpoints and ports are not emitted)
37 "root decoders"
39 nest under buses
40 "port decoders"
42 nest under ports, or buses (if ports are not emitted)
43 "endpoint decoders"
45 nest under endpoints, or ports (if endpoints are not emitted) or
46 buses (if endpoints and ports are not emitted)
47 Filters can be specified as either a single identifier, a space
49 separated quoted string, or a comma separated list. When multiple
50 filter identifiers are specified within a filter string, like "-m
51 mem0,mem1,mem2", they are combined as an OR filter. When multiple
52 filter string types are specified, like "-m mem0,mem1,mem2 -p port10",
53 they are combined as an AND filter. So, "-m mem0,mem1,mem2 -p port10"
54 would only list objects that are beneath port10 AND map mem0, mem1, OR
55 mem2.
56 Given that many topology queries seek to answer questions relative to a
58 given memdev, buses, ports, endpoints, and decoders can be filtered by
59 one or more memdevs. For example:
60 # cxl list -P -p switch,endpoint -m mem0
62 [
63 {
64 "port":"port1",
65 "host":"ACPI0016:00",
66 "endpoints:port1":[
67 {
68 "endpoint":"endpoint2",
69 "host":"mem0"
70 }
71 ]
72 }
73 ]
74 Additionally, when provisioning new interleave configurations it is
76 useful to know which memdevs can be referenced by a given decoder like
77 a root decoder, or mapped by a given port if the decoders are not
78 configured.
79 # cxl list -Mu -d decoder0.0
81 {
82 "memdev":"mem0",
83 "pmem_size":"256.00 MiB (268.44 MB)",
84 "serial":"0",
85 "host":"0000:35:00.0"
86 }
87 Note that for the -m/--memdev=, -p/--port=, and -e/--endpoint= filters
89 a host device name can be substituted for the CXL object identifier.
90 For -m/--memdev= this is an endpoint PCI device name of the form
91 "DDDD:bb:dd.f" (D: Domain b: Bus d: Device f: Function) (see
92 /sys/bus/pci/devices), for -p/--port= this is an upstream switch port
93 PCI device name of the form "DDDD:bb:dd.f", or a PCI bus name of the
94 form "pciDDDD:bb", and for -e/--endpoint= the host device is CXL memory
95 device object name of the form "memX".
96 The --human option in addition to reformatting some fields to more
98 human friendly strings also unwraps the array to reduce the number of
99 lines of output.
100
102 # cxl list --memdevs
103 [
104 {
105 "memdev":"mem0",
106 "pmem_size":268435456,
107 "serial":0,
108 "host":"0000:35:00.0"
109 }
110 ]
111 # cxl list -BMu
113 [
114 {
115 "anon memdevs":[
116 {
117 "memdev":"mem0",
118 "pmem_size":"256.00 MiB (268.44 MB)",
119 "serial":"0"
120 }
121 ]
122 },
123 {
124 "buses":[
125 {
126 "bus":"root0",
127 "provider":"ACPI.CXL"
128 }
129 ]
130 }
131 ]
132
134 -m, --memdev=
135 Specify CXL memory device name(s) ("mem0"), device id(s) ("0"),
136 and/or host device name(s) ("0000:35:00.0") to filter the listing.
137 For example:
138 # cxl list -M --memdev="0 mem3 5"
140 [
141 {
142 "memdev":"mem0",
143 "pmem_size":268435456,
144 "serial":0
145 },
146 {
147 "memdev":"mem3",
148 "pmem_size":268435456,
149 "ram_size":268435456,
150 "serial":2
151 },
152 {
153 "memdev":"mem5",
154 "pmem_size":268435456,
155 "ram_size":268435456,
156 "serial":4
157 }
158 ]
159 -s, --serial=
161 Specify CXL memory device serial number(s) to filter the listing
162 -M, --memdevs
164 Include CXL memory devices in the listing
165 -i, --idle
167 Include idle (not enabled / zero-sized) devices in the listing
168 -H, --health
170 Include health information in the memdev listing. Example listing:
171 # cxl list -m mem0 -H
173 [
174 {
175 "memdev":"mem0",
176 "pmem_size":268435456,
177 "ram_size":268435456,
178 "health":{
179 "maintenance_needed":true,
180 "performance_degraded":true,
181 "hw_replacement_needed":true,
182 "media_normal":false,
183 "media_not_ready":false,
184 "media_persistence_lost":false,
185 "media_data_lost":true,
186 "media_powerloss_persistence_loss":false,
187 "media_shutdown_persistence_loss":false,
188 "media_persistence_loss_imminent":false,
189 "media_powerloss_data_loss":false,
190 "media_shutdown_data_loss":false,
191 "media_data_loss_imminent":false,
192 "ext_life_used":"normal",
193 "ext_temperature":"critical",
194 "ext_corrected_volatile":"warning",
195 "ext_corrected_persistent":"normal",
196 "life_used_percent":15,
197 "temperature":25,
198 "dirty_shutdowns":10,
199 "volatile_errors":20,
200 "pmem_errors":30
201 }
202 }
203 ]
204 -I, --partition
206 Include partition information in the memdev listing. Example
207 listing:
208 # cxl list -m mem0 -I
210 [
211 {
212 "memdev":"mem0",
213 "ram_size":273535729664,
214 "partition_info":{
215 "total_size":273535729664,
216 "volatile_only_size":0,
217 "persistent_only_size":0,
218 "partition_alignment_size":268435456
219 "active_volatile_size":273535729664,
220 "active_persistent_size":0,
221 "next_volatile_size":0,
222 "next_persistent_size":0,
223 }
224 }
225 ]
226 -A, --alert-config
228 Include alert configuration in the memdev listing. Example listing:
229 # cxl list -m mem0 -A
231 [
232 {
233 "memdev":"mem0",
234 "pmem_size":0,
235 "ram_size":273535729664,
236 "alert_config":{
237 "life_used_prog_warn_threshold_valid":false,
238 "dev_over_temperature_prog_warn_threshold_valid":false,
239 "dev_under_temperature_prog_warn_threshold_valid":false,
240 "corrected_volatile_mem_err_prog_warn_threshold_valid":true,
241 "corrected_pmem_err_prog_warn_threshold_valid":false,
242 "life_used_prog_warn_threshold_writable":false,
243 "dev_over_temperature_prog_warn_threshold_writable":false,
244 "dev_under_temperature_prog_warn_threshold_writable":false,
245 "corrected_volatile_mem_err_prog_warn_threshold_writable":true,
246 "corrected_pmem_err_prog_warn_threshold_writable":false,
247 "life_used_crit_alert_threshold":0,
248 "life_used_prog_warn_threshold":0,
249 "dev_over_temperature_crit_alert_threshold":0,
250 "dev_under_temperature_crit_alert_threshold":0,
251 "dev_over_temperature_prog_warn_threshold":0,
252 "dev_under_temperature_prog_warn_threshold":0,
253 "corrected_volatile_mem_err_prog_warn_threshold":0,
254 "corrected_pmem_err_prog_warn_threshold":0
255 },
256 }
257 ]
258 -B, --buses
260 Include bus / CXL root object(s) in the listing. Typically, on ACPI
261 systems the bus object is a singleton associated with the ACPI0017
262 device, but there are test scenarios where there may be multiple
263 CXL memory hierarchies.
264 # cxl list -B
266 [
267 {
268 "bus":"root3",
269 "provider":"cxl_test"
270 },
271 {
272 "bus":"root0",
273 "provider":"ACPI.CXL"
274 }
275 ]
276 -b, --bus=
278 Specify CXL root device name(s), device id(s), and / or CXL bus
279 provider names to filter the listing. The supported provider names
280 are "ACPI.CXL" and "cxl_test".
281 -P, --ports
283 Include port objects (CXL / PCIe root ports + Upstream Switch
284 Ports) in the listing.
285 -p, --port=
287 Specify CXL Port device name(s) ("port2"), device id(s) ("2"), host
288 device name(s) ("pci0000:34"), and / or port type name(s) to filter
289 the listing. The supported port type names are "root" and "switch".
290 Note that a bus object is also a port, so the following two
291 syntaxes are equivalent:
292 # cxl list -B
294 # cxl list -P -p root -S
295 ...where the '-S/--single' is required since descendant ports are always
297 included in a port listing and '-S/--single' stops after listing the
298 bus. Additionally, endpoint objects are ports so the following commands
299 are equivalent, and no '-S/--single' is required as endpoint ports are
300 terminal:
301 # cxl list -E
303 # cxl list -P -p endpoint
304 By default, only 'switch' ports are listed, i.e.
306 # cxl list -P
308 # cxl list -P -p switch
309 ...are equivalent.
311 -S, --single
313 Specify whether the listing should emit all the objects that are
314 descendants of a port that matches the port filter, or only direct
315 descendants of the individual ports that match the filter. By
316 default all descendant objects are listed.
317 -E, --endpoints
319 Include endpoint objects (CXL Memory Device decoders) in the
320 listing.
321 # cxl list -E
323 [
324 {
325 "endpoint":"endpoint2",
326 "host":"mem0"
327 }
328 ]
329 -e, --endpoint
331 Specify CXL endpoint device name(s), or device id(s) to filter the
332 emitted endpoint(s).
333 -D, --decoders
335 Include decoder objects (CXL Memory decode capability instances in
336 buses, ports, and endpoints) in the listing.
337 -d, --decoder
339 Specify CXL decoder device name(s), device id(s), or decoder type
340 names to filter the emitted decoder(s). The format for a decoder
341 name is "decoder<port_id>.<instance_id>". The possible decoder type
342 names are "root", "switch", or "endpoint", similar to the port
343 filter syntax.
344 -T, --targets
346 Extend decoder listings with downstream port target information,
347 port and bus listings with the downstream port information, and /
348 or regions with mapping information.
349 # cxl list -BTu -b ACPI.CXL
351 {
352 "bus":"root0",
353 "provider":"ACPI.CXL",
354 "nr_dports":1,
355 "dports":[
356 {
357 "dport":"ACPI0016:00",
358 "alias":"pci0000:34",
359 "id":"0"
360 }
361 ]
362 }
363 -R, --regions
365 Include region objects in the listing.
366 -X, --dax
368 Append DAX information to region listings
369 # cxl list -RXu
371 {
372 "region":"region4",
373 "resource":"0xf010000000",
374 "size":"512.00 MiB (536.87 MB)",
375 "interleave_ways":2,
376 "interleave_granularity":4096,
377 "decode_state":"commit",
378 "daxregion":{
379 "id":4,
380 "size":"512.00 MiB (536.87 MB)",
381 "align":2097152,
382 "devices":[
383 {
384 "chardev":"dax4.0",
385 "size":"512.00 MiB (536.87 MB)",
386 "target_node":0,
387 "align":2097152,
388 "mode":"system-ram",
389 "online_memblocks":0,
390 "total_memblocks":4
391 }
392 ]
393 }
394 }
395 -r, --region
397 Specify CXL region device name(s), or device id(s), to filter the
398 listing.
399 -v, --verbose
401 Increase verbosity of the output. This can be specified multiple
402 times to be even more verbose on the informational and
403 miscellaneous output, and can be used to override omitted flags for
404 showing specific information. Note that cxl list --verbose
405 --verbose is equivalent to cxl list -vv.
406 • -v Enable --memdevs, --regions, --buses, --ports, --decoders,
408 and --targets.
409 • -vv Everything -v provides, plus include disabled devices with
411 --idle.
412 • -vvv Everything -vv provides, plus enable --health and
414 --partition.
415 --debug
417 If the cxl tool was built with debug enabled, turn on debug
418 messages.
419 -u, --human
421 By default the command will output machine-friendly raw-integer
422 data. Instead, with this flag, numbers representing storage size
423 will be formatted as human readable strings with units, other
424 fields are converted to hexadecimal strings.
425
427 Copyright © 2016 - 2022, Intel Corporation. License GPLv2: GNU GPL
428 version 2 http://gnu.org/licenses/gpl.html. This is free software: you
429 are free to change and redistribute it. There is NO WARRANTY, to the
430 extent permitted by law.
431
433 linkcxl:ndctl-list[1]
434 08/03/2023 CXL-LIST(1)