Documentation/ABI/testing/sysfs-bus-cxl

   1 What:           /sys/bus/cxl/flush
   2 Date:           Januarry, 2022
   3 KernelVersion:  v5.18
   4 Contact:        linux-cxl@vger.kernel.org
   5 Description:
   6                 (WO) If userspace manually unbinds a port the kernel schedules
   7                 all descendant memdevs for unbind. Writing '1' to this attribute
   8                 flushes that work.
   9
  10
  11 What:           /sys/bus/cxl/devices/memX/firmware_version
  12 Date:           December, 2020
  13 KernelVersion:  v5.12
  14 Contact:        linux-cxl@vger.kernel.org
  15 Description:
  16                 (RO) "FW Revision" string as reported by the Identify
  17                 Memory Device Output Payload in the CXL-2.0
  18                 specification.
  19
  20
  21 What:           /sys/bus/cxl/devices/memX/ram/size
  22 Date:           December, 2020
  23 KernelVersion:  v5.12
  24 Contact:        linux-cxl@vger.kernel.org
  25 Description:
  26                 (RO) "Volatile Only Capacity" as bytes. Represents the
  27                 identically named field in the Identify Memory Device Output
  28                 Payload in the CXL-2.0 specification.
  29
  30
  31 What:           /sys/bus/cxl/devices/memX/pmem/size
  32 Date:           December, 2020
  33 KernelVersion:  v5.12
  34 Contact:        linux-cxl@vger.kernel.org
  35 Description:
  36                 (RO) "Persistent Only Capacity" as bytes. Represents the
  37                 identically named field in the Identify Memory Device Output
  38                 Payload in the CXL-2.0 specification.
  39
  40
  41 What:           /sys/bus/cxl/devices/memX/serial
  42 Date:           January, 2022
  43 KernelVersion:  v5.18
  44 Contact:        linux-cxl@vger.kernel.org
  45 Description:
  46                 (RO) 64-bit serial number per the PCIe Device Serial Number
  47                 capability. Mandatory for CXL devices, see CXL 2.0 8.1.12.2
  48                 Memory Device PCIe Capabilities and Extended Capabilities.
  49
  50
  51 What:           /sys/bus/cxl/devices/memX/numa_node
  52 Date:           January, 2022
  53 KernelVersion:  v5.18
  54 Contact:        linux-cxl@vger.kernel.org
  55 Description:
  56                 (RO) If NUMA is enabled and the platform has affinitized the
  57                 host PCI device for this memory device, emit the CPU node
  58                 affinity for this device.
  59
  60
  61 What:           /sys/bus/cxl/devices/memX/security/state
  62 Date:           June, 2023
  63 KernelVersion:  v6.5
  64 Contact:        linux-cxl@vger.kernel.org
  65 Description:
  66                 (RO) Reading this file will display the CXL security state for
  67                 that device. Such states can be: 'disabled', 'sanitize', when
  68                 a sanitization is currently underway; or those available only
  69                 for persistent memory: 'locked', 'unlocked' or 'frozen'. This
  70                 sysfs entry is select/poll capable from userspace to notify
  71                 upon completion of a sanitize operation.
  72
  73
  74 What:           /sys/bus/cxl/devices/memX/security/sanitize
  75 Date:           June, 2023
  76 KernelVersion:  v6.5
  77 Contact:        linux-cxl@vger.kernel.org
  78 Description:
  79                 (WO) Write a boolean 'true' string value to this attribute to
  80                 sanitize the device to securely re-purpose or decommission it.
  81                 This is done by ensuring that all user data and meta-data,
  82                 whether it resides in persistent capacity, volatile capacity,
  83                 or the LSA, is made permanently unavailable by whatever means
  84                 is appropriate for the media type. This functionality requires
  85                 the device to be disabled, that is, not actively decoding any
  86                 HPA ranges. This permits avoiding explicit global CPU cache
  87                 management, relying instead for it to be done when a region
  88                 transitions between software programmed and hardware committed
  89                 states. If this file is not present, then there is no hardware
  90                 support for the operation.
  91
  92
  93 What            /sys/bus/cxl/devices/memX/security/erase
  94 Date:           June, 2023
  95 KernelVersion:  v6.5
  96 Contact:        linux-cxl@vger.kernel.org
  97 Description:
  98                 (WO) Write a boolean 'true' string value to this attribute to
  99                 secure erase user data by changing the media encryption keys for
 100                 all user data areas of the device. This functionality requires
 101                 the device to be disabled, that is, not actively decoding any
 102                 HPA ranges. This permits avoiding explicit global CPU cache
 103                 management, relying instead for it to be done when a region
 104                 transitions between software programmed and hardware committed
 105                 states. If this file is not present, then there is no hardware
 106                 support for the operation.
 107
 108
 109 What:           /sys/bus/cxl/devices/memX/firmware/
 110 Date:           April, 2023
 111 KernelVersion:  v6.5
 112 Contact:        linux-cxl@vger.kernel.org
 113 Description:
 114                 (RW) Firmware uploader mechanism. The different files under
 115                 this directory can be used to upload and activate new
 116                 firmware for CXL devices. The interfaces under this are
 117                 documented in sysfs-class-firmware.
 118
 119
 120 What:           /sys/bus/cxl/devices/*/devtype
 121 Date:           June, 2021
 122 KernelVersion:  v5.14
 123 Contact:        linux-cxl@vger.kernel.org
 124 Description:
 125                 (RO) CXL device objects export the devtype attribute which
 126                 mirrors the same value communicated in the DEVTYPE environment
 127                 variable for uevents for devices on the "cxl" bus.
 128
 129
 130 What:           /sys/bus/cxl/devices/*/modalias
 131 Date:           December, 2021
 132 KernelVersion:  v5.18
 133 Contact:        linux-cxl@vger.kernel.org
 134 Description:
 135                 (RO) CXL device objects export the modalias attribute which
 136                 mirrors the same value communicated in the MODALIAS environment
 137                 variable for uevents for devices on the "cxl" bus.
 138
 139
 140 What:           /sys/bus/cxl/devices/portX/uport
 141 Date:           June, 2021
 142 KernelVersion:  v5.14
 143 Contact:        linux-cxl@vger.kernel.org
 144 Description:
 145                 (RO) CXL port objects are enumerated from either a platform
 146                 firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream
 147                 port with CXL component registers. The 'uport' symlink connects
 148                 the CXL portX object to the device that published the CXL port
 149                 capability.
 150
 151
 152 What:           /sys/bus/cxl/devices/{port,endpoint}X/parent_dport
 153 Date:           January, 2023
 154 KernelVersion:  v6.3
 155 Contact:        linux-cxl@vger.kernel.org
 156 Description:
 157                 (RO) CXL port objects are instantiated for each upstream port in
 158                 a CXL/PCIe switch, and for each endpoint to map the
 159                 corresponding memory device into the CXL port hierarchy. When a
 160                 descendant CXL port (switch or endpoint) is enumerated it is
 161                 useful to know which 'dport' object in the parent CXL port
 162                 routes to this descendant. The 'parent_dport' symlink points to
 163                 the device representing the downstream port of a CXL switch that
 164                 routes to {port,endpoint}X.
 165
 166
 167 What:           /sys/bus/cxl/devices/portX/dportY
 168 Date:           June, 2021
 169 KernelVersion:  v5.14
 170 Contact:        linux-cxl@vger.kernel.org
 171 Description:
 172                 (RO) CXL port objects are enumerated from either a platform
 173                 firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream
 174                 port with CXL component registers. The 'dportY' symlink
 175                 identifies one or more downstream ports that the upstream port
 176                 may target in its decode of CXL memory resources.  The 'Y'
 177                 integer reflects the hardware port unique-id used in the
 178                 hardware decoder target list.
 179
 180
 181 What:           /sys/bus/cxl/devices/portX/decoders_committed
 182 Date:           October, 2023
 183 KernelVersion:  v6.7
 184 Contact:        linux-cxl@vger.kernel.org
 185 Description:
 186                 (RO) A memory device is considered active when any of its
 187                 decoders are in the "committed" state (See CXL 3.0 8.2.4.19.7
 188                 CXL HDM Decoder n Control Register). Hotplug and destructive
 189                 operations like "sanitize" are blocked while device is actively
 190                 decoding a Host Physical Address range. Note that this number
 191                 may be elevated without any regionX objects active or even
 192                 enumerated, as this may be due to decoders established by
 193                 platform firwmare or a previous kernel (kexec).
 194
 195
 196 What:           /sys/bus/cxl/devices/decoderX.Y
 197 Date:           June, 2021
 198 KernelVersion:  v5.14
 199 Contact:        linux-cxl@vger.kernel.org
 200 Description:
 201                 (RO) CXL decoder objects are enumerated from either a platform
 202                 firmware description, or a CXL HDM decoder register set in a
 203                 PCIe device (see CXL 2.0 section 8.2.5.12 CXL HDM Decoder
 204                 Capability Structure). The 'X' in decoderX.Y represents the
 205                 cxl_port container of this decoder, and 'Y' represents the
 206                 instance id of a given decoder resource.
 207
 208
 209 What:           /sys/bus/cxl/devices/decoderX.Y/{start,size}
 210 Date:           June, 2021
 211 KernelVersion:  v5.14
 212 Contact:        linux-cxl@vger.kernel.org
 213 Description:
 214                 (RO) The 'start' and 'size' attributes together convey the
 215                 physical address base and number of bytes mapped in the
 216                 decoder's decode window. For decoders of devtype
 217                 "cxl_decoder_root" the address range is fixed. For decoders of
 218                 devtype "cxl_decoder_switch" the address is bounded by the
 219                 decode range of the cxl_port ancestor of the decoder's cxl_port,
 220                 and dynamically updates based on the active memory regions in
 221                 that address space.
 222
 223
 224 What:           /sys/bus/cxl/devices/decoderX.Y/locked
 225 Date:           June, 2021
 226 KernelVersion:  v5.14
 227 Contact:        linux-cxl@vger.kernel.org
 228 Description:
 229                 (RO) CXL HDM decoders have the capability to lock the
 230                 configuration until the next device reset. For decoders of
 231                 devtype "cxl_decoder_root" there is no standard facility to
 232                 unlock them.  For decoders of devtype "cxl_decoder_switch" a
 233                 secondary bus reset, of the PCIe bridge that provides the bus
 234                 for this decoders uport, unlocks / resets the decoder.
 235
 236
 237 What:           /sys/bus/cxl/devices/decoderX.Y/target_list
 238 Date:           June, 2021
 239 KernelVersion:  v5.14
 240 Contact:        linux-cxl@vger.kernel.org
 241 Description:
 242                 (RO) Display a comma separated list of the current decoder
 243                 target configuration. The list is ordered by the current
 244                 configured interleave order of the decoder's dport instances.
 245                 Each entry in the list is a dport id.
 246
 247
 248 What:           /sys/bus/cxl/devices/decoderX.Y/cap_{pmem,ram,type2,type3}
 249 Date:           June, 2021
 250 KernelVersion:  v5.14
 251 Contact:        linux-cxl@vger.kernel.org
 252 Description:
 253                 (RO) When a CXL decoder is of devtype "cxl_decoder_root", it
 254                 represents a fixed memory window identified by platform
 255                 firmware. A fixed window may only support a subset of memory
 256                 types. The 'cap_*' attributes indicate whether persistent
 257                 memory, volatile memory, accelerator memory, and / or expander
 258                 memory may be mapped behind this decoder's memory window.
 259
 260
 261 What:           /sys/bus/cxl/devices/decoderX.Y/target_type
 262 Date:           June, 2021
 263 KernelVersion:  v5.14
 264 Contact:        linux-cxl@vger.kernel.org
 265 Description:
 266                 (RO) When a CXL decoder is of devtype "cxl_decoder_switch", it
 267                 can optionally decode either accelerator memory (type-2) or
 268                 expander memory (type-3). The 'target_type' attribute indicates
 269                 the current setting which may dynamically change based on what
 270                 memory regions are activated in this decode hierarchy.
 271
 272
 273 What:           /sys/bus/cxl/devices/endpointX/CDAT
 274 Date:           July, 2022
 275 KernelVersion:  v6.0
 276 Contact:        linux-cxl@vger.kernel.org
 277 Description:
 278                 (RO) If this sysfs entry is not present no DOE mailbox was
 279                 found to support CDAT data.  If it is present and the length of
 280                 the data is 0 reading the CDAT data failed.  Otherwise the CDAT
 281                 data is reported.
 282
 283
 284 What:           /sys/bus/cxl/devices/decoderX.Y/mode
 285 Date:           May, 2022
 286 KernelVersion:  v6.0
 287 Contact:        linux-cxl@vger.kernel.org
 288 Description:
 289                 (RW) When a CXL decoder is of devtype "cxl_decoder_endpoint" it
 290                 translates from a host physical address range, to a device local
 291                 address range. Device-local address ranges are further split
 292                 into a 'ram' (volatile memory) range and 'pmem' (persistent
 293                 memory) range. The 'mode' attribute emits one of 'ram', 'pmem',
 294                 'mixed', or 'none'. The 'mixed' indication is for error cases
 295                 when a decoder straddles the volatile/persistent partition
 296                 boundary, and 'none' indicates the decoder is not actively
 297                 decoding, or no DPA allocation policy has been set.
 298
 299                 'mode' can be written, when the decoder is in the 'disabled'
 300                 state, with either 'ram' or 'pmem' to set the boundaries for the
 301                 next allocation.
 302
 303
 304 What:           /sys/bus/cxl/devices/decoderX.Y/dpa_resource
 305 Date:           May, 2022
 306 KernelVersion:  v6.0
 307 Contact:        linux-cxl@vger.kernel.org
 308 Description:
 309                 (RO) When a CXL decoder is of devtype "cxl_decoder_endpoint",
 310                 and its 'dpa_size' attribute is non-zero, this attribute
 311                 indicates the device physical address (DPA) base address of the
 312                 allocation.
 313
 314
 315 What:           /sys/bus/cxl/devices/decoderX.Y/dpa_size
 316 Date:           May, 2022
 317 KernelVersion:  v6.0
 318 Contact:        linux-cxl@vger.kernel.org
 319 Description:
 320                 (RW) When a CXL decoder is of devtype "cxl_decoder_endpoint" it
 321                 translates from a host physical address range, to a device local
 322                 address range. The range, base address plus length in bytes, of
 323                 DPA allocated to this decoder is conveyed in these 2 attributes.
 324                 Allocations can be mutated as long as the decoder is in the
 325                 disabled state. A write to 'dpa_size' releases the previous DPA
 326                 allocation and then attempts to allocate from the free capacity
 327                 in the device partition referred to by 'decoderX.Y/mode'.
 328                 Allocate and free requests can only be performed on the highest
 329                 instance number disabled decoder with non-zero size. I.e.
 330                 allocations are enforced to occur in increasing 'decoderX.Y/id'
 331                 order and frees are enforced to occur in decreasing
 332                 'decoderX.Y/id' order.
 333
 334
 335 What:           /sys/bus/cxl/devices/decoderX.Y/interleave_ways
 336 Date:           May, 2022
 337 KernelVersion:  v6.0
 338 Contact:        linux-cxl@vger.kernel.org
 339 Description:
 340                 (RO) The number of targets across which this decoder's host
 341                 physical address (HPA) memory range is interleaved. The device
 342                 maps every Nth block of HPA (of size ==
 343                 'interleave_granularity') to consecutive DPA addresses. The
 344                 decoder's position in the interleave is determined by the
 345                 device's (endpoint or switch) switch ancestry. For root
 346                 decoders their interleave is specified by platform firmware and
 347                 they only specify a downstream target order for host bridges.
 348
 349
 350 What:           /sys/bus/cxl/devices/decoderX.Y/interleave_granularity
 351 Date:           May, 2022
 352 KernelVersion:  v6.0
 353 Contact:        linux-cxl@vger.kernel.org
 354 Description:
 355                 (RO) The number of consecutive bytes of host physical address
 356                 space this decoder claims at address N before the decode rotates
 357                 to the next target in the interleave at address N +
 358                 interleave_granularity (assuming N is aligned to
 359                 interleave_granularity).
 360
 361
 362 What:           /sys/bus/cxl/devices/decoderX.Y/create_{pmem,ram}_region
 363 Date:           May, 2022, January, 2023
 364 KernelVersion:  v6.0 (pmem), v6.3 (ram)
 365 Contact:        linux-cxl@vger.kernel.org
 366 Description:
 367                 (RW) Write a string in the form 'regionZ' to start the process
 368                 of defining a new persistent, or volatile memory region
 369                 (interleave-set) within the decode range bounded by root decoder
 370                 'decoderX.Y'. The value written must match the current value
 371                 returned from reading this attribute. An atomic compare exchange
 372                 operation is done on write to assign the requested id to a
 373                 region and allocate the region-id for the next creation attempt.
 374                 EBUSY is returned if the region name written does not match the
 375                 current cached value.
 376
 377
 378 What:           /sys/bus/cxl/devices/decoderX.Y/delete_region
 379 Date:           May, 2022
 380 KernelVersion:  v6.0
 381 Contact:        linux-cxl@vger.kernel.org
 382 Description:
 383                 (WO) Write a string in the form 'regionZ' to delete that region,
 384                 provided it is currently idle / not bound to a driver.
 385
 386
 387 What:           /sys/bus/cxl/devices/decoderX.Y/qos_class
 388 Date:           May, 2023
 389 KernelVersion:  v6.5
 390 Contact:        linux-cxl@vger.kernel.org
 391 Description:
 392                 (RO) For CXL host platforms that support "QoS Telemmetry" this
 393                 root-decoder-only attribute conveys a platform specific cookie
 394                 that identifies a QoS performance class for the CXL Window.
 395                 This class-id can be compared against a similar "qos_class"
 396                 published for each memory-type that an endpoint supports. While
 397                 it is not required that endpoints map their local memory-class
 398                 to a matching platform class, mismatches are not recommended and
 399                 there are platform specific side-effects that may result.
 400
 401
 402 What:           /sys/bus/cxl/devices/regionZ/uuid
 403 Date:           May, 2022
 404 KernelVersion:  v6.0
 405 Contact:        linux-cxl@vger.kernel.org
 406 Description:
 407                 (RW) Write a unique identifier for the region. This field must
 408                 be set for persistent regions and it must not conflict with the
 409                 UUID of another region. For volatile ram regions this
 410                 attribute is a read-only empty string.
 411
 412
 413 What:           /sys/bus/cxl/devices/regionZ/interleave_granularity
 414 Date:           May, 2022
 415 KernelVersion:  v6.0
 416 Contact:        linux-cxl@vger.kernel.org
 417 Description:
 418                 (RW) Set the number of consecutive bytes each device in the
 419                 interleave set will claim. The possible interleave granularity
 420                 values are determined by the CXL spec and the participating
 421                 devices.
 422
 423
 424 What:           /sys/bus/cxl/devices/regionZ/interleave_ways
 425 Date:           May, 2022
 426 KernelVersion:  v6.0
 427 Contact:        linux-cxl@vger.kernel.org
 428 Description:
 429                 (RW) Configures the number of devices participating in the
 430                 region is set by writing this value. Each device will provide
 431                 1/interleave_ways of storage for the region.
 432
 433
 434 What:           /sys/bus/cxl/devices/regionZ/size
 435 Date:           May, 2022
 436 KernelVersion:  v6.0
 437 Contact:        linux-cxl@vger.kernel.org
 438 Description:
 439                 (RW) System physical address space to be consumed by the region.
 440                 When written trigger the driver to allocate space out of the
 441                 parent root decoder's address space. When read the size of the
 442                 address space is reported and should match the span of the
 443                 region's resource attribute. Size shall be set after the
 444                 interleave configuration parameters. Once set it cannot be
 445                 changed, only freed by writing 0. The kernel makes no guarantees
 446                 that data is maintained over an address space freeing event, and
 447                 there is no guarantee that a free followed by an allocate
 448                 results in the same address being allocated.
 449
 450
 451 What:           /sys/bus/cxl/devices/regionZ/mode
 452 Date:           January, 2023
 453 KernelVersion:  v6.3
 454 Contact:        linux-cxl@vger.kernel.org
 455 Description:
 456                 (RO) The mode of a region is established at region creation time
 457                 and dictates the mode of the endpoint decoder that comprise the
 458                 region. For more details on the possible modes see
 459                 /sys/bus/cxl/devices/decoderX.Y/mode
 460
 461
 462 What:           /sys/bus/cxl/devices/regionZ/resource
 463 Date:           May, 2022
 464 KernelVersion:  v6.0
 465 Contact:        linux-cxl@vger.kernel.org
 466 Description:
 467                 (RO) A region is a contiguous partition of a CXL root decoder
 468                 address space. Region capacity is allocated by writing to the
 469                 size attribute, the resulting physical address space determined
 470                 by the driver is reflected here. It is therefore not useful to
 471                 read this before writing a value to the size attribute.
 472
 473
 474 What:           /sys/bus/cxl/devices/regionZ/target[0..N]
 475 Date:           May, 2022
 476 KernelVersion:  v6.0
 477 Contact:        linux-cxl@vger.kernel.org
 478 Description:
 479                 (RW) Write an endpoint decoder object name to 'targetX' where X
 480                 is the intended position of the endpoint device in the region
 481                 interleave and N is the 'interleave_ways' setting for the
 482                 region. ENXIO is returned if the write results in an impossible
 483                 to map decode scenario, like the endpoint is unreachable at that
 484                 position relative to the root decoder interleave. EBUSY is
 485                 returned if the position in the region is already occupied, or
 486                 if the region is not in a state to accept interleave
 487                 configuration changes. EINVAL is returned if the object name is
 488                 not an endpoint decoder. Once all positions have been
 489                 successfully written a final validation for decode conflicts is
 490                 performed before activating the region.
 491
 492
 493 What:           /sys/bus/cxl/devices/regionZ/commit
 494 Date:           May, 2022
 495 KernelVersion:  v6.0
 496 Contact:        linux-cxl@vger.kernel.org
 497 Description:
 498                 (RW) Write a boolean 'true' string value to this attribute to
 499                 trigger the region to transition from the software programmed
 500                 state to the actively decoding in hardware state. The commit
 501                 operation in addition to validating that the region is in proper
 502                 configured state, validates that the decoders are being
 503                 committed in spec mandated order (last committed decoder id +
 504                 1), and checks that the hardware accepts the commit request.
 505                 Reading this value indicates whether the region is committed or
 506                 not.
 507
 508
 509 What:           /sys/bus/cxl/devices/memX/trigger_poison_list
 510 Date:           April, 2023
 511 KernelVersion:  v6.4
 512 Contact:        linux-cxl@vger.kernel.org
 513 Description:
 514                 (WO) When a boolean 'true' is written to this attribute the
 515                 memdev driver retrieves the poison list from the device. The
 516                 list consists of addresses that are poisoned, or would result
 517                 in poison if accessed, and the source of the poison. This
 518                 attribute is only visible for devices supporting the
 519                 capability. The retrieved errors are logged as kernel
 520                 events when cxl_poison event tracing is enabled.