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