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