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