public-mirrors/linux
1
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-08-05 16:54:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
linux/Documentation/driver-api/cxl/index.rst

55 lines
1 KiB
ReStructuredText
Raw Permalink Normal View History

cxl/mem: Introduce a driver for CXL-2.0-Type-3 endpoints The CXL.mem protocol allows a device to act as a provider of "System RAM" and/or "Persistent Memory" that is fully coherent as if the memory was attached to the typical CPU memory controller. With the CXL-2.0 specification a PCI endpoint can implement a "Type-3" device interface and give the operating system control over "Host Managed Device Memory". See section 2.3 Type 3 CXL Device. The memory range exported by the device may optionally be described by the platform firmware memory map, or by infrastructure like LIBNVDIMM to provision persistent memory capacity from one, or more, CXL.mem devices. A pre-requisite for Linux-managed memory-capacity provisioning is this cxl_mem driver that can speak the mailbox protocol defined in section 8.2.8.4 Mailbox Registers. For now just land the initial driver boiler-plate and Documentation/ infrastructure. Signed-off-by: Ben Widawsky <ben.widawsky@intel.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Acked-by: David Rientjes <rientjes@google.com> (v1) Cc: Jonathan Corbet <corbet@lwn.net> Link: https://www.computeexpresslink.org/download-the-specification Link: https://lore.kernel.org/r/20210217040958.1354670-2-ben.widawsky@intel.com Signed-off-by: Dan Williams <dan.j.williams@intel.com>
2021-02-16 20:09:50 -08:00
.. SPDX-License-Identifier: GPL-2.0
====================
Compute Express Link
====================
cxl: update documentation structure in prep for new docs Restructure the cxl folder to make adding docs per-page cleaner. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-2-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:18 -04:00
CXL device configuration has a complex handoff between platform (Hardware,
BIOS, EFI), OS (early boot, core kernel, driver), and user policy decisions
that have impacts on each other. The docs here break up configurations steps.
.. toctree::
:maxdepth: 2
:caption: Overview
theory-of-operation
maturity-map
Documentation/driver-api/cxl: Introduce conventions.rst There exists shipping platforms that bend, break, or otherwise lean on ambiguities in the CXL specification. Without driver changes to accommodate these deviations, end users are left without CXL subsystem RAS features. Specifically, provisioning, error translation, and other flows require the CXL subsystem to understand the platforms CXL topology beyond undecorated memory address ranges. Those isolated compatibility problems risk growing into deeper upstream maintenance burden if different platform vendors arrive at diverging solutions. For example, there are multiple options for resolving low-memory-mmio intersecting large-interleave-ways CXL windows. Linux should only entertain one solution to that problem. Now, with the ACPI Specification Working Group, situations like this would be resolved with the "Code First ECN" process to codify Linux expectations in a specification. In the absence of such a process for the CXL specification, create a file in Linux documentation to detail the motivations, assumptions, tradeoffs, and proposals for amending specification language. The goal is to capture the issues such that platform vendors arrive at compatible solutions for these problems and serve as a repository for potential specification updates. The expectation is to update conventions.rst along with CXL subsystem code changes to accommodate the platform topology. [ dj: Rebased against v6.16-rc1 ] Signed-off-by: Dan Williams <dan.j.williams@intel.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Reviewed-by: Robert Richter <rrichter@amd.com> Link: https://patch.msgid.link/20250603185254.3730099-1-dan.j.williams@intel.com Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-06-03 11:52:54 -07:00
conventions
cxl: update documentation structure in prep for new docs Restructure the cxl folder to make adding docs per-page cleaner. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-2-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:18 -04:00
cxl: docs/devices - add cxl device and protocol reference Add a simple device primer sufficient to understand the theory of operation documentation. Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-4-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:20 -04:00
.. toctree::
:maxdepth: 2
:caption: Device Reference
devices/device-types
cxl: docs/platform/bios-and-efi documentation Add some docs on CXL configurations done in bios/efi that affect linux configuration - information vendors may care to consider. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-5-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:21 -04:00
.. toctree::
:maxdepth: 2
:caption: Platform Configuration
platform/bios-and-efi
cxl: docs/platform/acpi reference documentation Add basic ACPI table information needed to understand the CXL driver probe process. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-6-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:22 -04:00
platform/acpi
cxl: docs/platform/cdat reference documentation Add documentation for CDAT structures for CXL usages. Reviewed-by: Gregory Price <gourry@gourry.net> Reviewed-by: Alison Schofield <alison.schofield@intel.com> Link: https://patch.msgid.link/20250515000923.2590820-2-dave.jiang@intel.com Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-14 17:09:21 -07:00
platform/cdat
cxl: docs/platform/example-configs documentation Add example ACPI Table configurations for different sample platforms. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-7-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:23 -04:00
platform/example-configs
cxl: docs/platform/bios-and-efi documentation Add some docs on CXL configurations done in bios/efi that affect linux configuration - information vendors may care to consider. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-5-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:21 -04:00
cxl/mem: Introduce a driver for CXL-2.0-Type-3 endpoints The CXL.mem protocol allows a device to act as a provider of "System RAM" and/or "Persistent Memory" that is fully coherent as if the memory was attached to the typical CPU memory controller. With the CXL-2.0 specification a PCI endpoint can implement a "Type-3" device interface and give the operating system control over "Host Managed Device Memory". See section 2.3 Type 3 CXL Device. The memory range exported by the device may optionally be described by the platform firmware memory map, or by infrastructure like LIBNVDIMM to provision persistent memory capacity from one, or more, CXL.mem devices. A pre-requisite for Linux-managed memory-capacity provisioning is this cxl_mem driver that can speak the mailbox protocol defined in section 8.2.8.4 Mailbox Registers. For now just land the initial driver boiler-plate and Documentation/ infrastructure. Signed-off-by: Ben Widawsky <ben.widawsky@intel.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Acked-by: David Rientjes <rientjes@google.com> (v1) Cc: Jonathan Corbet <corbet@lwn.net> Link: https://www.computeexpresslink.org/download-the-specification Link: https://lore.kernel.org/r/20210217040958.1354670-2-ben.widawsky@intel.com Signed-off-by: Dan Williams <dan.j.williams@intel.com>
2021-02-16 20:09:50 -08:00
.. toctree::
cxl: docs/linux - overview Add type-3 device configuration overview that explains the probe process for a type-3 device from early-boot through memory-hotplug. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-8-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:24 -04:00
:maxdepth: 2
cxl: update documentation structure in prep for new docs Restructure the cxl folder to make adding docs per-page cleaner. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-2-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:18 -04:00
:caption: Linux Kernel Configuration
cxl/mem: Introduce a driver for CXL-2.0-Type-3 endpoints The CXL.mem protocol allows a device to act as a provider of "System RAM" and/or "Persistent Memory" that is fully coherent as if the memory was attached to the typical CPU memory controller. With the CXL-2.0 specification a PCI endpoint can implement a "Type-3" device interface and give the operating system control over "Host Managed Device Memory". See section 2.3 Type 3 CXL Device. The memory range exported by the device may optionally be described by the platform firmware memory map, or by infrastructure like LIBNVDIMM to provision persistent memory capacity from one, or more, CXL.mem devices. A pre-requisite for Linux-managed memory-capacity provisioning is this cxl_mem driver that can speak the mailbox protocol defined in section 8.2.8.4 Mailbox Registers. For now just land the initial driver boiler-plate and Documentation/ infrastructure. Signed-off-by: Ben Widawsky <ben.widawsky@intel.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Acked-by: David Rientjes <rientjes@google.com> (v1) Cc: Jonathan Corbet <corbet@lwn.net> Link: https://www.computeexpresslink.org/download-the-specification Link: https://lore.kernel.org/r/20210217040958.1354670-2-ben.widawsky@intel.com Signed-off-by: Dan Williams <dan.j.williams@intel.com>
2021-02-16 20:09:50 -08:00
cxl: docs/linux - overview Add type-3 device configuration overview that explains the probe process for a type-3 device from early-boot through memory-hotplug. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-8-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:24 -04:00
linux/overview
cxl: docs/linux - early boot configuration Document __init time configurations that affect CXL driver probe process and memory region configuration. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-9-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:25 -04:00
linux/early-boot
cxl: docs/linux - add cxl-driver theory of operation Add docs for the CXL driver that explains the base devices, decoder types, region types, mailbox interfaces, and decoder programming. Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-10-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:26 -04:00
linux/cxl-driver
cxl: docs/linux/dax-driver documentation Add documentation on how the CXL driver interacts with the DAX driver. Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-12-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:28 -04:00
linux/dax-driver
cxl: docs/linux/memory-hotplug Add documentation on how the CXL driver surfaces memory through the DAX driver and memory-hotplug. Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-13-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:29 -04:00
linux/memory-hotplug
cxl: update documentation structure in prep for new docs Restructure the cxl folder to make adding docs per-page cleaner. Signed-off-by: Gregory Price <gourry@gourry.net> Reviewed-by: Dave Jiang <dave.jiang@intel.com> Link: https://patch.msgid.link/20250512162134.3596150-2-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:18 -04:00
linux/access-coordinates
cxl/mem: Introduce a driver for CXL-2.0-Type-3 endpoints The CXL.mem protocol allows a device to act as a provider of "System RAM" and/or "Persistent Memory" that is fully coherent as if the memory was attached to the typical CPU memory controller. With the CXL-2.0 specification a PCI endpoint can implement a "Type-3" device interface and give the operating system control over "Host Managed Device Memory". See section 2.3 Type 3 CXL Device. The memory range exported by the device may optionally be described by the platform firmware memory map, or by infrastructure like LIBNVDIMM to provision persistent memory capacity from one, or more, CXL.mem devices. A pre-requisite for Linux-managed memory-capacity provisioning is this cxl_mem driver that can speak the mailbox protocol defined in section 8.2.8.4 Mailbox Registers. For now just land the initial driver boiler-plate and Documentation/ infrastructure. Signed-off-by: Ben Widawsky <ben.widawsky@intel.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Acked-by: David Rientjes <rientjes@google.com> (v1) Cc: Jonathan Corbet <corbet@lwn.net> Link: https://www.computeexpresslink.org/download-the-specification Link: https://lore.kernel.org/r/20210217040958.1354670-2-ben.widawsky@intel.com Signed-off-by: Dan Williams <dan.j.williams@intel.com>
2021-02-16 20:09:50 -08:00
cxl: docs/allocation/dax Small example of accessing CXL memory capacity via DAX device Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-14-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:30 -04:00
.. toctree::
:maxdepth: 2
:caption: Memory Allocation
allocation/dax
cxl: docs/allocation/page-allocator Document some interesting interactions that occur when exposing CXL memory capacity to page allocator. Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-15-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:31 -04:00
allocation/page-allocator
cxl: docs/allocation/reclaim Document a bit about how reclaim interacts with various CXL configurations. Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-16-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:32 -04:00
allocation/reclaim
cxl: docs/allocation/hugepages Add docs on how CXL capacity interacts with CMA and HugeTLB allocation interfaces. Signed-off-by: Gregory Price <gourry@gourry.net> Link: https://patch.msgid.link/20250512162134.3596150-17-gourry@gourry.net Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2025-05-12 12:21:33 -04:00
allocation/hugepages.rst
Documentation: CXL Maturity Map Provide a survey of the work-in-progress maturity (implementation status) of various aspects of the CXL subsystem. Clarify that in addition to ongoing upkeep relative to specification updates, there are some long running themes in the driver that respond to the discovery of new corner cases (bugs) and new use cases (feature extensions). The primary audience is distribution maintainers, but it also serves as a guide for kernel developers to understand what aspects of the CXL subsystem need more help. It is a landing page to document ongoing progress, and a guide to discern exposure to work-in-progress features. Reviewed-by: Adam Manzanares <a.manzanares@samsung.com> Signed-off-by: Dan Williams <dan.j.williams@intel.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Reviewed-by: Ira Weiny <ira.weiny@intel.com> Reviewed-by: Alison Schofield <alison.schofield@intel.com> Link: https://patch.msgid.link/172005486862.2048248.6668794717827294862.stgit@dwillia2-xfh.jf.intel.com Signed-off-by: Dave Jiang <dave.jiang@intel.com>
2024-07-03 18:01:35 -07:00
cxl/mem: Introduce a driver for CXL-2.0-Type-3 endpoints The CXL.mem protocol allows a device to act as a provider of "System RAM" and/or "Persistent Memory" that is fully coherent as if the memory was attached to the typical CPU memory controller. With the CXL-2.0 specification a PCI endpoint can implement a "Type-3" device interface and give the operating system control over "Host Managed Device Memory". See section 2.3 Type 3 CXL Device. The memory range exported by the device may optionally be described by the platform firmware memory map, or by infrastructure like LIBNVDIMM to provision persistent memory capacity from one, or more, CXL.mem devices. A pre-requisite for Linux-managed memory-capacity provisioning is this cxl_mem driver that can speak the mailbox protocol defined in section 8.2.8.4 Mailbox Registers. For now just land the initial driver boiler-plate and Documentation/ infrastructure. Signed-off-by: Ben Widawsky <ben.widawsky@intel.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Acked-by: David Rientjes <rientjes@google.com> (v1) Cc: Jonathan Corbet <corbet@lwn.net> Link: https://www.computeexpresslink.org/download-the-specification Link: https://lore.kernel.org/r/20210217040958.1354670-2-ben.widawsky@intel.com Signed-off-by: Dan Williams <dan.j.williams@intel.com>
2021-02-16 20:09:50 -08:00
.. only:: subproject and html
Reference in a new issue Copy permalink