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 not be actively decoding any HPA ranges.
  86
  87
  88 What            /sys/bus/cxl/devices/memX/security/erase
  89 Date:           June, 2023
  90 KernelVersion:  v6.5
  91 Contact:        linux-cxl@vger.kernel.org
  92 Description:
  93                 (WO) Write a boolean 'true' string value to this attribute to
  94                 secure erase user data by changing the media encryption keys for
  95                 all user data areas of the device.
  96
  97
  98 What:           /sys/bus/cxl/devices/memX/firmware/
  99 Date:           April, 2023
 100 KernelVersion:  v6.5
 101 Contact:        linux-cxl@vger.kernel.org
 102 Description:
 103                 (RW) Firmware uploader mechanism. The different files under
 104                 this directory can be used to upload and activate new
 105                 firmware for CXL devices. The interfaces under this are
 106                 documented in sysfs-class-firmware.
 107
 108
 109 What:           /sys/bus/cxl/devices/*/devtype
 110 Date:           June, 2021
 111 KernelVersion:  v5.14
 112 Contact:        linux-cxl@vger.kernel.org
 113 Description:
 114                 (RO) CXL device objects export the devtype attribute which
 115                 mirrors the same value communicated in the DEVTYPE environment
 116                 variable for uevents for devices on the "cxl" bus.
 117
 118
 119 What:           /sys/bus/cxl/devices/*/modalias
 120 Date:           December, 2021
 121 KernelVersion:  v5.18
 122 Contact:        linux-cxl@vger.kernel.org
 123 Description:
 124                 (RO) CXL device objects export the modalias attribute which
 125                 mirrors the same value communicated in the MODALIAS environment
 126                 variable for uevents for devices on the "cxl" bus.
 127
 128
 129 What:           /sys/bus/cxl/devices/portX/uport
 130 Date:           June, 2021
 131 KernelVersion:  v5.14
 132 Contact:        linux-cxl@vger.kernel.org
 133 Description:
 134                 (RO) CXL port objects are enumerated from either a platform
 135                 firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream
 136                 port with CXL component registers. The 'uport' symlink connects
 137                 the CXL portX object to the device that published the CXL port
 138                 capability.
 139
 140
 141 What:           /sys/bus/cxl/devices/{port,endpoint}X/parent_dport
 142 Date:           January, 2023
 143 KernelVersion:  v6.3
 144 Contact:        linux-cxl@vger.kernel.org
 145 Description:
 146                 (RO) CXL port objects are instantiated for each upstream port in
 147                 a CXL/PCIe switch, and for each endpoint to map the
 148                 corresponding memory device into the CXL port hierarchy. When a
 149                 descendant CXL port (switch or endpoint) is enumerated it is
 150                 useful to know which 'dport' object in the parent CXL port
 151                 routes to this descendant. The 'parent_dport' symlink points to
 152                 the device representing the downstream port of a CXL switch that
 153                 routes to {port,endpoint}X.
 154
 155
 156 What:           /sys/bus/cxl/devices/portX/dportY
 157 Date:           June, 2021
 158 KernelVersion:  v5.14
 159 Contact:        linux-cxl@vger.kernel.org
 160 Description:
 161                 (RO) CXL port objects are enumerated from either a platform
 162                 firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream
 163                 port with CXL component registers. The 'dportY' symlink
 164                 identifies one or more downstream ports that the upstream port
 165                 may target in its decode of CXL memory resources.  The 'Y'
 166                 integer reflects the hardware port unique-id used in the
 167                 hardware decoder target list.
 168
 169
 170 What:           /sys/bus/cxl/devices/decoderX.Y
 171 Date:           June, 2021
 172 KernelVersion:  v5.14
 173 Contact:        linux-cxl@vger.kernel.org
 174 Description:
 175                 (RO) CXL decoder objects are enumerated from either a platform
 176                 firmware description, or a CXL HDM decoder register set in a
 177                 PCIe device (see CXL 2.0 section 8.2.5.12 CXL HDM Decoder
 178                 Capability Structure). The 'X' in decoderX.Y represents the
 179                 cxl_port container of this decoder, and 'Y' represents the
 180                 instance id of a given decoder resource.
 181
 182
 183 What:           /sys/bus/cxl/devices/decoderX.Y/{start,size}
 184 Date:           June, 2021
 185 KernelVersion:  v5.14
 186 Contact:        linux-cxl@vger.kernel.org
 187 Description:
 188                 (RO) The 'start' and 'size' attributes together convey the
 189                 physical address base and number of bytes mapped in the
 190                 decoder's decode window. For decoders of devtype
 191                 "cxl_decoder_root" the address range is fixed. For decoders of
 192                 devtype "cxl_decoder_switch" the address is bounded by the
 193                 decode range of the cxl_port ancestor of the decoder's cxl_port,
 194                 and dynamically updates based on the active memory regions in
 195                 that address space.
 196
 197
 198 What:           /sys/bus/cxl/devices/decoderX.Y/locked
 199 Date:           June, 2021
 200 KernelVersion:  v5.14
 201 Contact:        linux-cxl@vger.kernel.org
 202 Description:
 203                 (RO) CXL HDM decoders have the capability to lock the
 204                 configuration until the next device reset. For decoders of
 205                 devtype "cxl_decoder_root" there is no standard facility to
 206                 unlock them.  For decoders of devtype "cxl_decoder_switch" a
 207                 secondary bus reset, of the PCIe bridge that provides the bus
 208                 for this decoders uport, unlocks / resets the decoder.
 209
 210
 211 What:           /sys/bus/cxl/devices/decoderX.Y/target_list
 212 Date:           June, 2021
 213 KernelVersion:  v5.14
 214 Contact:        linux-cxl@vger.kernel.org
 215 Description:
 216                 (RO) Display a comma separated list of the current decoder
 217                 target configuration. The list is ordered by the current
 218                 configured interleave order of the decoder's dport instances.
 219                 Each entry in the list is a dport id.
 220
 221
 222 What:           /sys/bus/cxl/devices/decoderX.Y/cap_{pmem,ram,type2,type3}
 223 Date:           June, 2021
 224 KernelVersion:  v5.14
 225 Contact:        linux-cxl@vger.kernel.org
 226 Description:
 227                 (RO) When a CXL decoder is of devtype "cxl_decoder_root", it
 228                 represents a fixed memory window identified by platform
 229                 firmware. A fixed window may only support a subset of memory
 230                 types. The 'cap_*' attributes indicate whether persistent
 231                 memory, volatile memory, accelerator memory, and / or expander
 232                 memory may be mapped behind this decoder's memory window.
 233
 234
 235 What:           /sys/bus/cxl/devices/decoderX.Y/target_type
 236 Date:           June, 2021
 237 KernelVersion:  v5.14
 238 Contact:        linux-cxl@vger.kernel.org
 239 Description:
 240                 (RO) When a CXL decoder is of devtype "cxl_decoder_switch", it
 241                 can optionally decode either accelerator memory (type-2) or
 242                 expander memory (type-3). The 'target_type' attribute indicates
 243                 the current setting which may dynamically change based on what
 244                 memory regions are activated in this decode hierarchy.
 245
 246
 247 What:           /sys/bus/cxl/devices/endpointX/CDAT
 248 Date:           July, 2022
 249 KernelVersion:  v6.0
 250 Contact:        linux-cxl@vger.kernel.org
 251 Description:
 252                 (RO) If this sysfs entry is not present no DOE mailbox was
 253                 found to support CDAT data.  If it is present and the length of
 254                 the data is 0 reading the CDAT data failed.  Otherwise the CDAT
 255                 data is reported.
 256
 257
 258 What:           /sys/bus/cxl/devices/decoderX.Y/mode
 259 Date:           May, 2022
 260 KernelVersion:  v6.0
 261 Contact:        linux-cxl@vger.kernel.org
 262 Description:
 263                 (RW) When a CXL decoder is of devtype "cxl_decoder_endpoint" it
 264                 translates from a host physical address range, to a device local
 265                 address range. Device-local address ranges are further split
 266                 into a 'ram' (volatile memory) range and 'pmem' (persistent
 267                 memory) range. The 'mode' attribute emits one of 'ram', 'pmem',
 268                 'mixed', or 'none'. The 'mixed' indication is for error cases
 269                 when a decoder straddles the volatile/persistent partition
 270                 boundary, and 'none' indicates the decoder is not actively
 271                 decoding, or no DPA allocation policy has been set.
 272
 273                 'mode' can be written, when the decoder is in the 'disabled'
 274                 state, with either 'ram' or 'pmem' to set the boundaries for the
 275                 next allocation.
 276
 277
 278 What:           /sys/bus/cxl/devices/decoderX.Y/dpa_resource
 279 Date:           May, 2022
 280 KernelVersion:  v6.0
 281 Contact:        linux-cxl@vger.kernel.org
 282 Description:
 283                 (RO) When a CXL decoder is of devtype "cxl_decoder_endpoint",
 284                 and its 'dpa_size' attribute is non-zero, this attribute
 285                 indicates the device physical address (DPA) base address of the
 286                 allocation.
 287
 288
 289 What:           /sys/bus/cxl/devices/decoderX.Y/dpa_size
 290 Date:           May, 2022
 291 KernelVersion:  v6.0
 292 Contact:        linux-cxl@vger.kernel.org
 293 Description:
 294                 (RW) When a CXL decoder is of devtype "cxl_decoder_endpoint" it
 295                 translates from a host physical address range, to a device local
 296                 address range. The range, base address plus length in bytes, of
 297                 DPA allocated to this decoder is conveyed in these 2 attributes.
 298                 Allocations can be mutated as long as the decoder is in the
 299                 disabled state. A write to 'dpa_size' releases the previous DPA
 300                 allocation and then attempts to allocate from the free capacity
 301                 in the device partition referred to by 'decoderX.Y/mode'.
 302                 Allocate and free requests can only be performed on the highest
 303                 instance number disabled decoder with non-zero size. I.e.
 304                 allocations are enforced to occur in increasing 'decoderX.Y/id'
 305                 order and frees are enforced to occur in decreasing
 306                 'decoderX.Y/id' order.
 307
 308
 309 What:           /sys/bus/cxl/devices/decoderX.Y/interleave_ways
 310 Date:           May, 2022
 311 KernelVersion:  v6.0
 312 Contact:        linux-cxl@vger.kernel.org
 313 Description:
 314                 (RO) The number of targets across which this decoder's host
 315                 physical address (HPA) memory range is interleaved. The device
 316                 maps every Nth block of HPA (of size ==
 317                 'interleave_granularity') to consecutive DPA addresses. The
 318                 decoder's position in the interleave is determined by the
 319                 device's (endpoint or switch) switch ancestry. For root
 320                 decoders their interleave is specified by platform firmware and
 321                 they only specify a downstream target order for host bridges.
 322
 323
 324 What:           /sys/bus/cxl/devices/decoderX.Y/interleave_granularity
 325 Date:           May, 2022
 326 KernelVersion:  v6.0
 327 Contact:        linux-cxl@vger.kernel.org
 328 Description:
 329                 (RO) The number of consecutive bytes of host physical address
 330                 space this decoder claims at address N before the decode rotates
 331                 to the next target in the interleave at address N +
 332                 interleave_granularity (assuming N is aligned to
 333                 interleave_granularity).
 334
 335
 336 What:           /sys/bus/cxl/devices/decoderX.Y/create_{pmem,ram}_region
 337 Date:           May, 2022, January, 2023
 338 KernelVersion:  v6.0 (pmem), v6.3 (ram)
 339 Contact:        linux-cxl@vger.kernel.org
 340 Description:
 341                 (RW) Write a string in the form 'regionZ' to start the process
 342                 of defining a new persistent, or volatile memory region
 343                 (interleave-set) within the decode range bounded by root decoder
 344                 'decoderX.Y'. The value written must match the current value
 345                 returned from reading this attribute. An atomic compare exchange
 346                 operation is done on write to assign the requested id to a
 347                 region and allocate the region-id for the next creation attempt.
 348                 EBUSY is returned if the region name written does not match the
 349                 current cached value.
 350
 351
 352 What:           /sys/bus/cxl/devices/decoderX.Y/delete_region
 353 Date:           May, 2022
 354 KernelVersion:  v6.0
 355 Contact:        linux-cxl@vger.kernel.org
 356 Description:
 357                 (WO) Write a string in the form 'regionZ' to delete that region,
 358                 provided it is currently idle / not bound to a driver.
 359
 360
 361 What:           /sys/bus/cxl/devices/regionZ/uuid
 362 Date:           May, 2022
 363 KernelVersion:  v6.0
 364 Contact:        linux-cxl@vger.kernel.org
 365 Description:
 366                 (RW) Write a unique identifier for the region. This field must
 367                 be set for persistent regions and it must not conflict with the
 368                 UUID of another region. For volatile ram regions this
 369                 attribute is a read-only empty string.
 370
 371
 372 What:           /sys/bus/cxl/devices/regionZ/interleave_granularity
 373 Date:           May, 2022
 374 KernelVersion:  v6.0
 375 Contact:        linux-cxl@vger.kernel.org
 376 Description:
 377                 (RW) Set the number of consecutive bytes each device in the
 378                 interleave set will claim. The possible interleave granularity
 379                 values are determined by the CXL spec and the participating
 380                 devices.
 381
 382
 383 What:           /sys/bus/cxl/devices/regionZ/interleave_ways
 384 Date:           May, 2022
 385 KernelVersion:  v6.0
 386 Contact:        linux-cxl@vger.kernel.org
 387 Description:
 388                 (RW) Configures the number of devices participating in the
 389                 region is set by writing this value. Each device will provide
 390                 1/interleave_ways of storage for the region.
 391
 392
 393 What:           /sys/bus/cxl/devices/regionZ/size
 394 Date:           May, 2022
 395 KernelVersion:  v6.0
 396 Contact:        linux-cxl@vger.kernel.org
 397 Description:
 398                 (RW) System physical address space to be consumed by the region.
 399                 When written trigger the driver to allocate space out of the
 400                 parent root decoder's address space. When read the size of the
 401                 address space is reported and should match the span of the
 402                 region's resource attribute. Size shall be set after the
 403                 interleave configuration parameters. Once set it cannot be
 404                 changed, only freed by writing 0. The kernel makes no guarantees
 405                 that data is maintained over an address space freeing event, and
 406                 there is no guarantee that a free followed by an allocate
 407                 results in the same address being allocated.
 408
 409
 410 What:           /sys/bus/cxl/devices/regionZ/mode
 411 Date:           January, 2023
 412 KernelVersion:  v6.3
 413 Contact:        linux-cxl@vger.kernel.org
 414 Description:
 415                 (RO) The mode of a region is established at region creation time
 416                 and dictates the mode of the endpoint decoder that comprise the
 417                 region. For more details on the possible modes see
 418                 /sys/bus/cxl/devices/decoderX.Y/mode
 419
 420
 421 What:           /sys/bus/cxl/devices/regionZ/resource
 422 Date:           May, 2022
 423 KernelVersion:  v6.0
 424 Contact:        linux-cxl@vger.kernel.org
 425 Description:
 426                 (RO) A region is a contiguous partition of a CXL root decoder
 427                 address space. Region capacity is allocated by writing to the
 428                 size attribute, the resulting physical address space determined
 429                 by the driver is reflected here. It is therefore not useful to
 430                 read this before writing a value to the size attribute.
 431
 432
 433 What:           /sys/bus/cxl/devices/regionZ/target[0..N]
 434 Date:           May, 2022
 435 KernelVersion:  v6.0
 436 Contact:        linux-cxl@vger.kernel.org
 437 Description:
 438                 (RW) Write an endpoint decoder object name to 'targetX' where X
 439                 is the intended position of the endpoint device in the region
 440                 interleave and N is the 'interleave_ways' setting for the
 441                 region. ENXIO is returned if the write results in an impossible
 442                 to map decode scenario, like the endpoint is unreachable at that
 443                 position relative to the root decoder interleave. EBUSY is
 444                 returned if the position in the region is already occupied, or
 445                 if the region is not in a state to accept interleave
 446                 configuration changes. EINVAL is returned if the object name is
 447                 not an endpoint decoder. Once all positions have been
 448                 successfully written a final validation for decode conflicts is
 449                 performed before activating the region.
 450
 451
 452 What:           /sys/bus/cxl/devices/regionZ/commit
 453 Date:           May, 2022
 454 KernelVersion:  v6.0
 455 Contact:        linux-cxl@vger.kernel.org
 456 Description:
 457                 (RW) Write a boolean 'true' string value to this attribute to
 458                 trigger the region to transition from the software programmed
 459                 state to the actively decoding in hardware state. The commit
 460                 operation in addition to validating that the region is in proper
 461                 configured state, validates that the decoders are being
 462                 committed in spec mandated order (last committed decoder id +
 463                 1), and checks that the hardware accepts the commit request.
 464                 Reading this value indicates whether the region is committed or
 465                 not.
 466
 467
 468 What:           /sys/bus/cxl/devices/memX/trigger_poison_list
 469 Date:           April, 2023
 470 KernelVersion:  v6.4
 471 Contact:        linux-cxl@vger.kernel.org
 472 Description:
 473                 (WO) When a boolean 'true' is written to this attribute the
 474                 memdev driver retrieves the poison list from the device. The
 475                 list consists of addresses that are poisoned, or would result
 476                 in poison if accessed, and the source of the poison. This
 477                 attribute is only visible for devices supporting the
 478                 capability. The retrieved errors are logged as kernel
 479                 events when cxl_poison event tracing is enabled.