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 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 "anon memdevs"
24 (disabled memory devices) do not nest
25 "buses"
27 do not nest
28 "ports"
30 nest under buses
31 "endpoints"
33 nest under ports or buses (if ports are not emitted)
34 "memdevs"
36 nest under endpoints or ports (if endpoints are not emitted) or
37 buses (if endpoints and ports are not emitted)
38 "root decoders"
40 nest under buses
41 "port decoders"
43 nest under ports, or buses (if ports are not emitted)
44 "endpoint decoders"
46 nest under endpoints, or ports (if endpoints are not emitted) or
47 buses (if endpoints and ports are not emitted)
48 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 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 # 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 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 # cxl list -Mu -d decoder0.0
82 {
83 "memdev":"mem0",
84 "pmem_size":"256.00 MiB (268.44 MB)",
85 "serial":"0",
86 "host":"0000:35:00.0"
87 }
88 Note that for the -m/--memdev=, -p/--port=, and -e/--endpoint= filters
90 a host device name can be substituted for the CXL object identifier.
91 For -m/--memdev= this is an endpoint PCI device name of the form
92 "DDDD:bb:dd.f" (D: Domain b: Bus d: Device f: Function) (see
93 /sys/bus/pci/devices), for -p/--port= this is an upstream switch port
94 PCI device name of the form "DDDD:bb:dd.f", or a PCI bus name of the
95 form "pciDDDD:bb", and for -e/--endpoint= the host device is CXL memory
96 device object name of the form "memX".
97 The --human option in addition to reformatting some fields to more
99 human friendly strings also unwraps the array to reduce the number of
100 lines of output.
101
103 # cxl list --memdevs
104 [
105 {
106 "memdev":"mem0",
107 "pmem_size":268435456,
108 "serial":0,
109 "host":"0000:35:00.0"
110 }
111 ]
112 # cxl list -BMu
114 [
115 {
116 "anon memdevs":[
117 {
118 "memdev":"mem0",
119 "pmem_size":"256.00 MiB (268.44 MB)",
120 "serial":"0"
121 }
122 ]
123 },
124 {
125 "buses":[
126 {
127 "bus":"root0",
128 "provider":"ACPI.CXL"
129 }
130 ]
131 }
132 ]
133
135 -m, --memdev=
136 Specify CXL memory device name(s) ("mem0"), device id(s) ("0"),
137 and/or host device name(s) ("0000:35:00.0") to filter the listing.
138 For example:
139 # cxl list -M --memdev="0 mem3 5"
141 [
142 {
143 "memdev":"mem0",
144 "pmem_size":268435456,
145 "serial":0
146 },
147 {
148 "memdev":"mem3",
149 "pmem_size":268435456,
150 "ram_size":268435456,
151 "serial":2
152 },
153 {
154 "memdev":"mem5",
155 "pmem_size":268435456,
156 "ram_size":268435456,
157 "serial":4
158 }
159 ]
160 -s, --serial=
162 Specify CXL memory device serial number(s) to filter the listing
163 -M, --memdevs
165 Include CXL memory devices in the listing
166 -i, --idle
168 Include idle (not enabled / zero-sized) devices in the listing
169 -H, --health
171 Include health information in the memdev listing. Example listing:
172 # cxl list -m mem0 -H
174 [
175 {
176 "memdev":"mem0",
177 "pmem_size":268435456,
178 "ram_size":268435456,
179 "health":{
180 "maintenance_needed":true,
181 "performance_degraded":true,
182 "hw_replacement_needed":true,
183 "media_normal":false,
184 "media_not_ready":false,
185 "media_persistence_lost":false,
186 "media_data_lost":true,
187 "media_powerloss_persistence_loss":false,
188 "media_shutdown_persistence_loss":false,
189 "media_persistence_loss_imminent":false,
190 "media_powerloss_data_loss":false,
191 "media_shutdown_data_loss":false,
192 "media_data_loss_imminent":false,
193 "ext_life_used":"normal",
194 "ext_temperature":"critical",
195 "ext_corrected_volatile":"warning",
196 "ext_corrected_persistent":"normal",
197 "life_used_percent":15,
198 "temperature":25,
199 "dirty_shutdowns":10,
200 "volatile_errors":20,
201 "pmem_errors":30
202 }
203 }
204 ]
205 -I, --partition
207 Include partition information in the memdev listing. Example
208 listing:
209 # cxl list -m mem0 -I
211 [
212 {
213 "memdev":"mem0",
214 "ram_size":273535729664,
215 "partition_info":{
216 "total_size":273535729664,
217 "volatile_only_size":0,
218 "persistent_only_size":0,
219 "partition_alignment_size":268435456
220 "active_volatile_size":273535729664,
221 "active_persistent_size":0,
222 "next_volatile_size":0,
223 "next_persistent_size":0,
224 }
225 }
226 ]
227 -A, --alert-config
229 Include alert configuration in the memdev listing. Example listing:
230 # cxl list -m mem0 -A
232 [
233 {
234 "memdev":"mem0",
235 "pmem_size":0,
236 "ram_size":273535729664,
237 "alert_config":{
238 "life_used_prog_warn_threshold_valid":false,
239 "dev_over_temperature_prog_warn_threshold_valid":false,
240 "dev_under_temperature_prog_warn_threshold_valid":false,
241 "corrected_volatile_mem_err_prog_warn_threshold_valid":true,
242 "corrected_pmem_err_prog_warn_threshold_valid":false,
243 "life_used_prog_warn_threshold_writable":false,
244 "dev_over_temperature_prog_warn_threshold_writable":false,
245 "dev_under_temperature_prog_warn_threshold_writable":false,
246 "corrected_volatile_mem_err_prog_warn_threshold_writable":true,
247 "corrected_pmem_err_prog_warn_threshold_writable":false,
248 "life_used_crit_alert_threshold":0,
249 "life_used_prog_warn_threshold":0,
250 "dev_over_temperature_crit_alert_threshold":0,
251 "dev_under_temperature_crit_alert_threshold":0,
252 "dev_over_temperature_prog_warn_threshold":0,
253 "dev_under_temperature_prog_warn_threshold":0,
254 "corrected_volatile_mem_err_prog_warn_threshold":0,
255 "corrected_pmem_err_prog_warn_threshold":0
256 },
257 }
258 ]
259 -B, --buses
261 Include bus / CXL root object(s) in the listing. Typically, on ACPI
262 systems the bus object is a singleton associated with the ACPI0017
263 device, but there are test scenerios where there may be multiple
264 CXL memory hierarchies.
265 # cxl list -B
267 [
268 {
269 "bus":"root3",
270 "provider":"cxl_test"
271 },
272 {
273 "bus":"root0",
274 "provider":"ACPI.CXL"
275 }
276 ]
277 -b, --bus=
279 Specify CXL root device name(s), device id(s), and / or CXL bus
280 provider names to filter the listing. The supported provider names
281 are "ACPI.CXL" and "cxl_test".
282 -P, --ports
284 Include port objects (CXL / PCIe root ports + Upstream Switch
285 Ports) in the listing.
286 -p, --port=
288 Specify CXL Port device name(s) ("port2"), device id(s) ("2"), host
289 device name(s) ("pci0000:34"), and / or port type name(s) to filter
290 the listing. The supported port type names are "root" and "switch".
291 Note that a bus object is also a port, so the following two
292 syntaxes are equivalent:
293 # cxl list -B
295 # cxl list -P -p root -S
296 ...where the '-S/--single' is required since descendant ports are always
298 included in a port listing and '-S/--single' stops after listing the
299 bus. Additionally, endpoint objects are ports so the following commands
300 are equivalent, and no '-S/--single' is required as endpoint ports are
301 terminal:
302 # cxl list -E
304 # cxl list -P -p endpoint
305 By default, only 'switch' ports are listed, i.e.
307 # cxl list -P
309 # cxl list -P -p switch
310 ...are equivalent.
312 -S, --single
314 Specify whether the listing should emit all the objects that are
315 descendants of a port that matches the port filter, or only direct
316 descendants of the individual ports that match the filter. By
317 default all descendant objects are listed.
318 -E, --endpoints
320 Include endpoint objects (CXL Memory Device decoders) in the
321 listing.
322 # cxl list -E
324 [
325 {
326 "endpoint":"endpoint2",
327 "host":"mem0"
328 }
329 ]
330 -e, --endpoint
332 Specify CXL endpoint device name(s), or device id(s) to filter the
333 emitted endpoint(s).
334 -D, --decoders
336 Include decoder objects (CXL Memory decode capability instances in
337 buses, ports, and endpoints) in the listing.
338 -d, --decoder
340 Specify CXL decoder device name(s), device id(s), or decoder type
341 names to filter the emitted decoder(s). The format for a decoder
342 name is "decoder<port_id>.<instance_id>". The possible decoder type
343 names are "root", "switch", or "endpoint", similar to the port
344 filter syntax.
345 -T, --targets
347 Extend decoder listings with downstream port target information,
348 port and bus listings with the downstream port information, and /
349 or regions with mapping information.
350 # cxl list -BTu -b ACPI.CXL
352 {
353 "bus":"root0",
354 "provider":"ACPI.CXL",
355 "nr_dports":1,
356 "dports":[
357 {
358 "dport":"ACPI0016:00",
359 "alias":"pci0000:34",
360 "id":"0"
361 }
362 ]
363 }
364 -R, --regions
366 Include region objects in the listing.
367 -r, --region
369 Specify CXL region device name(s), or device id(s), to filter the
370 listing.
371 -v, --verbose
373 Increase verbosity of the output. This can be specified multiple
374 times to be even more verbose on the informational and
375 miscellaneous output, and can be used to override omitted flags for
376 showing specific information. Note that cxl list --verbose
377 --verbose is equivalent to cxl list -vv.
378 • -v Enable --memdevs, --regions, --buses, --ports, --decoders,
380 and --targets.
381 • -vv Everything -v provides, plus include disabled devices with
383 --idle.
384 • -vvv Everything -vv provides, plus enable --health and
386 --partition.
387 --debug
389 If the cxl tool was built with debug enabled, turn on debug
390 messages.
391 -u, --human
393 By default the command will output machine-friendly raw-integer
394 data. Instead, with this flag, numbers representing storage size
395 will be formatted as human readable strings with units, other
396 fields are converted to hexadecimal strings.
397
399 Copyright © 2016 - 2022, Intel Corporation. License GPLv2: GNU GPL
400 version 2 http://gnu.org/licenses/gpl.html. This is free software: you
401 are free to change and redistribute it. There is NO WARRANTY, to the
402 extent permitted by law.
403
405 linkcxl:ndctl-list[1]
406 01/13/2023 CXL-LIST(1)