CXL-LIST(1)

🎀 cxl-list — cxl Manual 🎀

Hiii bestie, welcome to CXL-LIST(1), aka the cxl Manual page that’s literally about listing platform CXL objects, and their attributes, in json. Slay.

---

✨ NAME ✨

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

---

🦋 SYNOPSIS 🦋

cxl list [<options>]

Okay so cxl list walks the CXL capable device hierarchy in the system and lists all device instances along with some of their major attributes. Iconic behavior, honestly.

You can pass options to limit the output to specific objects. When a single object type is specified the return json object is an array of just those objects, and when multiple object types are specified the returned object may be an array of arrays with the inner array named for the given object type. The top-level arrays are elided when the objects can nest under a higher object-type in the hierarchy. The potential top-level array names and their nesting properties are:

• "anon memdevs" — (disabled memory devices) do not nest
• "buses" — do not nest
• "ports" — nest under buses
• "endpoints" — nest under ports or buses (if ports are not emitted)
• "memdevs" — nest under endpoints or ports (if endpoints are not emitted) or buses (if endpoints and ports are not emitted)
• "root decoders" — nest under buses
• "port decoders" — nest under ports, or buses (if ports are not emitted)
• "endpoint decoders" — nest under endpoints, or ports (if endpoints are not emitted) or buses (if endpoints and ports are not emitted)

Filters can be specified as either a single identifier, a space separated quoted string, or a comma separated list. When multiple filter identifiers are specified within a filter string, like -m mem0,mem1,mem2, they are combined as an OR filter. When multiple filter string types are specified, like -m mem0,mem1,mem2 -p port10, they are combined as an AND filter. So, -m mem0,mem1,mem2 -p port10 would only list objects that are beneath port10 AND map mem0, mem1, OR mem2. Filter math, but make it fashion.

Given that many topology queries seek to answer questions relative to a given memdev, buses, ports, endpoints, and decoders can be filtered by one or more memdevs. For example:

# cxl list -P -p switch,endpoint -m mem0
[
  {
    "port":"port1",
    "host":"ACPI0016:00",
    "endpoints:port1":[
      {
        "endpoint":"endpoint2",
        "host":"mem0"
      }
    ]
  }
]

Additionally, when provisioning new interleave configurations it is useful to know which memdevs can be referenced by a given decoder like a root decoder, or mapped by a given port if the decoders are not configured.

# cxl list -Mu -d decoder0.0
{
  "memdev":"mem0",
  "pmem_size":"256.00 MiB (268.44 MB)",
  "serial":"0",
  "host":"0000:35:00.0"
}

Note that for the -m/--memdev=, -p/--port=, and -e/--endpoint= filters a host device name can be substituted for the CXL object identifier. iykyk, host names are valid too.

• For -m/--memdev= this is an endpoint PCI device name of the form "DDDD:bb:dd.f" (D: Domain b: Bus d: Device f: Function) (see /sys/bus/pci/devices)
• For -p/--port= this is an upstream switch port PCI device name of the form "DDDD:bb:dd.f", or a PCI bus name of the form "pciDDDD:bb"
• For -e/--endpoint= the host device is CXL memory device object name of the form "memX"

The --human option in addition to reformatting some fields to more human friendly strings also unwraps the array to reduce the number of lines of output. Less line spam, more vibe.

---

🌸 EXAMPLE 🌸

# cxl list --memdevs
[
  {
    "memdev":"mem0",
    "pmem_size":268435456,
    "serial":0,
    "host":"0000:35:00.0"
  }
]

# cxl list -BMu
[
  {
    "anon memdevs":[
      {
        "memdev":"mem0",
        "pmem_size":"256.00 MiB (268.44 MB)",
        "serial":"0"
      }
    ]
  },
  {
    "buses":[
      {
        "bus":"root0",
        "provider":"ACPI.CXL"
      }
    ]
  }
]

---

💅 OPTIONS 💅

• -m, --memdev= — Specify CXL memory device name(s) ("mem0"), device id(s) ("0"), and/or host device name(s) ("0000:35:00.0") to filter the listing. For example:

# cxl list -M --memdev="0 mem3 5"
[
  {
    "memdev":"mem0",
    "pmem_size":268435456,
    "serial":0
  },
  {
    "memdev":"mem3",
    "pmem_size":268435456,
    "ram_size":268435456,
    "serial":2
  },
  {
    "memdev":"mem5",
    "pmem_size":268435456,
    "ram_size":268435456,
    "serial":4
  }
]

• -s, --serial= — Specify CXL memory device serial number(s) to filter the listing
• -M, --memdevs — Include CXL memory devices in the listing
• -i, --idle — Include idle (not enabled / zero-sized) devices in the listing
• -H, --health — Include health information in the memdev listing. Example listing:

# cxl list -m mem0 -H
[
  {
    "memdev":"mem0",
    "pmem_size":268435456,
    "ram_size":268435456,
    "health":{
      "maintenance_needed":true,
      "performance_degraded":true,
      "hw_replacement_needed":true,
      "media_normal":false,
      "media_not_ready":false,
      "media_persistence_lost":false,
      "media_data_lost":true,
      "media_powerloss_persistence_loss":false,
      "media_shutdown_persistence_loss":false,
      "media_persistence_loss_imminent":false,
      "media_powerloss_data_loss":false,
      "media_shutdown_data_loss":false,
      "media_data_loss_imminent":false,
      "ext_life_used":"normal",
      "ext_temperature":"critical",
      "ext_corrected_volatile":"warning",
      "ext_corrected_persistent":"normal",
      "life_used_percent":15,
      "temperature":25,
      "dirty_shutdowns":10,
      "volatile_errors":20,
      "pmem_errors":30
    }
  }
]

• -I, --partition — Include partition information in the memdev listing. Example listing:

# cxl list -m mem0 -I
[
  {
    "memdev":"mem0",
    "ram_size":273535729664,
    "partition_info":{
      "total_size":273535729664,
      "volatile_only_size":0,
      "persistent_only_size":0,
      "partition_alignment_size":268435456
      "active_volatile_size":273535729664,
      "active_persistent_size":0,
      "next_volatile_size":0,
      "next_persistent_size":0,
    }
  }
]

• -A, --alert-config — Include alert configuration in the memdev listing. Example listing:

# cxl list -m mem0 -A
[
  {
    "memdev":"mem0",
    "pmem_size":0,
    "ram_size":273535729664,
    "alert_config":{
      "life_used_prog_warn_threshold_valid":false,
      "dev_over_temperature_prog_warn_threshold_valid":false,
      "dev_under_temperature_prog_warn_threshold_valid":false,
      "corrected_volatile_mem_err_prog_warn_threshold_valid":true,
      "corrected_pmem_err_prog_warn_threshold_valid":false,
      "life_used_prog_warn_threshold_writable":false,
      "dev_over_temperature_prog_warn_threshold_writable":false,
      "dev_under_temperature_prog_warn_threshold_writable":false,
      "corrected_volatile_mem_err_prog_warn_threshold_writable":true,
      "corrected_pmem_err_prog_warn_threshold_writable":false,
      "life_used_crit_alert_threshold":0,
      "life_used_prog_warn_threshold":0,
      "dev_over_temperature_crit_alert_threshold":0,
      "dev_under_temperature_crit_alert_threshold":0,
      "dev_over_temperature_prog_warn_threshold":0,
      "dev_under_temperature_prog_warn_threshold":0,
      "corrected_volatile_mem_err_prog_warn_threshold":0,
      "corrected_pmem_err_prog_warn_threshold":0
    },
  }
]

• -B, --buses — Include bus / CXL root object(s) in the listing. Typically, on ACPI systems the bus object is a singleton associated with the ACPI0017 device, but there are test scenarios where there may be multiple CXL memory hierarchies.

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

• -b, --bus= — Specify CXL root device name(s), device id(s), and / or CXL bus provider names to filter the listing. The supported provider names are "ACPI.CXL" and "cxl_test".
• -P, --ports — Include port objects (CXL / PCIe root ports + Upstream Switch Ports) in the listing.
• -p, --port= — Specify CXL Port device name(s) ("port2"), device id(s) ("2"), host device name(s) ("pci0000:34"), and / or port type name(s) to filter the listing. The supported port type names are "root" 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 -S

...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, i.e.

# cxl list -P
# cxl list -P -p switch

...are equivalent.

• -S, --single — Specify whether the listing should emit all the objects that are descendants of a port that matches the port filter, or only direct descendants of the individual ports that match the filter. By default all descendant objects are listed.
• -E, --endpoints — Include endpoint objects (CXL Memory Device decoders) in the listing.

# cxl list -E
[
  {
    "endpoint":"endpoint2",
    "host":"mem0"
  }
]

• -e, --endpoint — Specify CXL endpoint device name(s), or device id(s) to filter the emitted endpoint(s).
• -D, --decoders — Include decoder objects (CXL Memory decode capability instances in buses, ports, and endpoints) in the listing.
• -d, --decoder — filter the decoders that actually get emitted, bestie 💅. You can pass decoder device name(s), device id(s), or decoder type names. A decoder name looks like "decoder<port_id>.<instance_id>", and the type names you can use are "root", "switch", or "endpoint" — same energy as the port filter syntax, iykyk.
• -T, --targets — this one's the glow-up flag ✨: it extends decoder listings with downstream port target info, port and bus listings with the downstream port info, and/or regions with mapping info.

# cxl list -BTu -b ACPI.CXL
{
  "bus":"root0",
  "provider":"ACPI.CXL",
  "nr_dports":1,
  "dports":[
    {
      "dport":"ACPI0016:00",
      "alias":"pci0000:34",
      "id":"0"
    }
  ]
}

• -R, --regions — pulls region objects into the listing, no cap 🫶

# cxl list -R
{
  "region":"region0",
  "resource":277025390592,
  "size":549755813888,
  "extended_linear_cache_size":274877906944,
  "type":"ram",
  "interleave_ways":2,
  "interleave_granularity":256,
  "decode_state":"commit",
  "qos_class_mismatch":true
}

• -X, --dax — appends DAX information onto region listings, slay 🌸

# cxl list -RXu
{
  "region":"region4",
  "resource":"0xf010000000",
  "size":"512.00 MiB (536.87 MB)",
  "interleave_ways":2,
  "interleave_granularity":4096,
  "decode_state":"commit",
  "daxregion":{
    "id":4,
    "size":"512.00 MiB (536.87 MB)",
    "align":2097152,
    "devices":[
      {
        "chardev":"dax4.0",
        "size":"512.00 MiB (536.87 MB)",
        "target_node":0,
        "align":2097152,
        "mode":"system-ram",
        "online_memblocks":0,
        "total_memblocks":4
      }
    ]
  }
}

• -r, --region — specify CXL region device name(s) or device id(s) to filter the listing. literally just the filter, nothing extra 💜
• -L, --media-errors — includes media-error info 🩹. The poison list gets retrieved from the device(s) and media_error records are added to the listing. Use this on memdevs and regions where the devices support the poison list capability. Heads up on the fields: "offset:" is relative to the region resource when you're listing by region, and it's the absolute device DPA when you're listing by memdev. "source:" is one of External, Internal, Injected, Vendor Specific, or Unknown, exactly as defined in CXL Specification v3.1 Table 8-140.

The media-errors option is only available with -Dlibtracefs=enabled. fr fr, no tracefs build, no media errors 😭

# cxl list -m mem9 --media-errors -u
{
  "memdev":"mem9",
  "pmem_size":"1024.00 MiB (1073.74 MB)",
  "pmem_qos_class":42,
  "ram_size":"1024.00 MiB (1073.74 MB)",
  "ram_qos_class":42,
  "serial":"0x5",
  "numa_node":1,
  "host":"cxl_mem.5",
  "media_errors":[
    {
      "offset":"0x40000000",
      "length":64,
      "source":"Injected"
    }
  ]
}

# cxl list -r region5 --media-errors -u
{
  "region":"region5",
  "resource":"0xf110000000",
  "size":"2.00 GiB (2.15 GB)",
  "type":"pmem",
  "interleave_ways":2,
  "interleave_granularity":4096,
  "decode_state":"commit",
  "media_errors":[
    {
      "offset":"0x1000",
      "length":64,
      "source":"Injected"
    },
    {
      "offset":"0x2000",
      "length":64,
      "source":"Injected"
    }
  ]
}

• -v, --verbose — turns the verbosity of the output up 🎚️. You can stack it multiple times to get even more verbose on the informational and miscellaneous output, and it can override omitted flags so specific info actually shows up. Obsessed with this detail: cxl list --verbose --verbose is equivalent to cxl list -vv.
  • -v — enables --memdevs, --regions, --buses, --ports, --decoders, and --targets.
  • -vv — everything -v gives you, plus include disabled devices with --idle.
  • -vvv — everything -vv gives you, plus enable --health, --partition, and --media-errors.
• --debug — if the cxl tool was built with debug enabled, this turns on debug messages. if it wasn't built that way, well... 🙈
• -u, --human — by default the command spits out machine-friendly raw-integer data. With this flag tho? Numbers representing storage size get formatted as human readable strings with units, and other fields get converted to hexadecimal strings. cute and readable 🌈

---

🎀 COPYRIGHT 🎀

Copyright © 2016 - 2022, Intel Corporation. License GPLv2: GNU GPL version 2 http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. (yes bestie, that last bit is in all caps for a reason 💀)

🦋 SEE ALSO 🦋

ndctl-list(1)

---

okay that's the whole page, you made it 🎉 this vibe check was brought to you by cxl, dated 2026-06-30, from the CXL-LIST(1) manual — go forth and list responsibly, mwah 💅✨