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