Linux 内核 CXL 平台约定（CXL Linux Conventions）指南：规范偏差记录与 PRM 地址翻译实现解析-二趣网

Linux 内核 CXL 平台约定（CXL Linux Conventions）指南：规范偏差记录与 PRM 地址翻译实现解析

【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux

导读

CXL（Compute Express Link）规范定义了设备与主机之间的内存互连行为，但实际出货的平台上往往存在"偏离或打破 CXL 规范预期"的固件/硬件实现。Linux 内核在Documentation/driver-api/cxl/文档体系中专门设立了一套CXL Linux Conventions（CXL 平台约定），借鉴 ACPI Code First 模板格式，系统性记录这些平台偏差的细节、产生原因与取舍，使多个平台实现可以遵循同一约定。本文以 conventions.rst 为骨架，深入讲解其收录的两类核心约定——低内存空洞（Low Memory Hole）下的 CFMWS 窗口裁剪与ACPI PRM CXL 地址翻译（Normalized Addressing），并结合 drivers/cxl 驱动的真实实现，说明 Linux 如何在这些平台上正确构建 CXL 内存区域。

一、CXL Linux Conventions 是什么

1.1 文档定位与目的

Documentation/driver-api/cxl/conventions.rst是一份索引性文档，它明确说明了这套约定的存在意义：

市面上存在一些出货平台，其行为偏离或打破了 CXL 规范的预期。本系列文档记录这些偏差的细节以及偏差的合理性论证（rationale），并借用 ACPI Code First 模板格式来捕获假设与取舍，使得多个平台实现可以遵循同一个约定。

这揭示了一个重要现实：规范是理想的，平台是现实的。当固件（BIOS/EFI）的行为无法完全符合 CXL 3.2 规范时，Linux 需要一套机制来记录"平台实际做了什么、Linux 如何适配"，而不是简单地把平台判为不合规并放弃支持。Conventions 文档正是这一机制的载体。

1.2 文档体系结构

conventions.rst 通过 Sphinx toctree 组织内容：

.. toctree:: :maxdepth: 1 :caption: Contents conventions/cxl-lmh.rst conventions/cxl-atl.rst conventions/template.rst

三个子文档分别承担不同的职责：

子文档	主题	对应平台场景
conventions/cxl-lmh.rst	CFMWS、平台内存空洞与端点 Decoder 的冲突	x86 平台在 4GB 以下存在 Low Memory Hole（PCIe MMIO 空洞）
conventions/cxl-atl.rst	ACPI PRM CXL 地址翻译	AMD Zen5 等使用 Normalized Address（规范化地址）的平台
conventions/template.rst	约定文档的书写模板	供后续平台记录新偏差时复用

三份文档都遵循相同的Code First 式结构：Document（对应 CXL 规范版本）→ License → Creator/Contributors → Summary of the Change → Benefits of the Change → References → Detailed Description of the Change（含建议写入规范的具体语言/表格）。

1.3 模板：如何记录一项新的平台约定

template.rst 给出了标准格式，各字段含义如下：

Document：指明本约定针对的 CXL 规范版本（如CXL Revision 3.2, Version 1.0）；
License：文档采用CC-BY-4.0许可证；
Creator/Contributors：约定提出者与维护者；
Summary of the Change：详细描述与规范的冲突点，以及硬件平台所做的假设与取舍；
Benefits of the Change：说明如果平台和 Linux 不采纳此约定会带来什么后果；
References：关联的规范章节与外部文档；
Detailed Description of the Change：给出能修正冲突的建议规范语言（proposed spec language）。

这一模板保证了不同厂商、不同平台的偏差记录在格式上统一，Linux 社区可以据此评审每一项约定的合理性与适用范围。

二、约定一：Low Memory Hole 下的 CFMWS 窗口裁剪（cxl-lmh）

2.1 背景：CFMWS、HPA 与 SPA 的基本概念

要理解第一个约定，需要先厘清几个地址空间概念：

HPA（Host Physical Address，主机物理地址）：CXL 设备实际能够解码并响应的物理内存地址空间。
SPA（System Physical Address，系统物理地址）：系统可见、用户可以直接发起事务访问的地址空间，它排除了保留区域。
CFMWS（CXL Fixed Memory Window Structure）：由平台固件通过 ACPI CEDT 表发布的结构，描述与每个 CXL Host Bridge 关联的零个或多个 HPA 窗口。每个窗口是一段连续的 HPA 范围，可能以一个或多个目标（包括 CXL Host Bridge）进行交织（interleave）。
HDM Decoder（Host-managed Device Memory Decoder）：位于 CXL 设备/交换机/根端口中的解码器寄存器，负责将 HPA 转换为 DPA（Device Physical Address）或完成地址裁剪。
OSPM：Operating System-directed configuration and Power Management，即操作系统对 CXL 资源的配置职责。

CXL 3.2 规范 Table 9-22 规定：Window Size 字段表示该窗口描述的 HPA 连续字节总数，该值必须是"交织路数（NIW）× 256MB"的倍数。

2.2 问题：PCIe MMIO 空洞导致的窗口裁剪

x86 平台在 4GB 以下存在Low Memory Hole（低内存空洞），例如 PCIe MMIO 预留区域。平台固件（BIOS）会为这些空洞保留物理地址，导致以下后果：

CFMWS 描述的是 SPA 范围：在有 LMH 的平台上，SPA 范围是 HPA 的一个严格子集（strict subset）——SPA 范围把空洞裁掉（trim）了；
端点丢失容量：Endpoint 中映射到空洞那部分 HPA 范围没有对应的 SPA，这部分容量就"丢失"了；
CFMWS Range Size 不再满足 NIW×256MB 规则。

文档给出的 x86 示例平台配置（两个 CFMWS，LMH 从 2GB 开始）：

Window	CFMWS Base	CFMWS Size	HDM Decoder Base	HDM Decoder Size	Ways
0	0 GB	2 GB	0 GB	3 GB	12
1	4 GB	NIW×256MB 对齐	4 GB	NIW×256MB 对齐	12

关键差异在于：HDM Decoder Base/Size 表示 12 路（12 ways）region 的全部 12 个端点 Decoder 及所有中间 Switch Decoder 的配置，它们由 BIOS 按 NIW×256MB 规则配置，因此 HPA 范围大小是3GB；而 CFMWS Base/Size 用于配置 Root Decoder 的 HPA 范围，裁剪后只有2GB。

这就产生了两个导致 region 构建失败的问题：

region 大小不匹配：Root Decoder 与任何 HDM Decoder 之间的大小不匹配，Root Decoder 因裁剪而总是更小；
违反对齐规则：裁剪导致 Root Decoder 违反 NIW×256MB 规则。

2.3 Linux 的适配方案

该约定的核心变更是：允许 base 地址为 0GB 的 region 绕过这些检查，从而允许使用被裁剪的 Root Decoder 地址范围创建 region。

同时文档强调了边界条件（重要限制）：

此变更不允许任何其他任意 region 违反这些检查——它专门用于启用将 CXL 内存映射到 4GB 以下的 x86 平台。

对于覆盖 PCIe 空洞的 HPA 区域，虽然 HDM Decoder 覆盖了它，但平台永远不会把地址访问路由到 CXL 体系（因为 Root Decoder 只覆盖排除空洞的裁剪区域）。这一点超出 Linux 的强制能力范围——文档明确承认"这是 Linux 无法强制执行的"（outside the ability of Linux to enforce）。

2.4 收益与源码佐证

采纳该约定后，OSPM 能够构建 region，并把中间 Switch Decoder 与端点 Decoder 挂载到 region 上，使设备总容量中可寻址的部分对用户可用；否则将导致 memdev 容量丢失。

在 drivers/cxl/acpi.c 中可以看到 Linux 对 CFMWS 的校验逻辑：cxl_acpi_cfmws_verify()检查base_hpa与window_size是否 256MB 对齐，并对交织算术（MODULO/XOR）、交织路数、结构长度逐一验证。而 region 构造路径中 drivers/cxl/core/region.c 大量使用了SZ_256M及interleave_ways × 256MB的对齐约束（例如第 678、3353 行），并在hbiw * 256MB对齐计算处（第 3289 行注释）为这类非对齐平台做了特殊处理。CXL_CAPACITY_MULTIPLIER（定义为SZ_256M）在 drivers/cxl/cxlmem.h 中被定义为容量换算的基准倍数，印证了 256MB 对齐是 CXL 内存资源管理的核心粒度。

三、约定二：ACPI PRM CXL 地址翻译 / Normalized Addressing（cxl-atl）

3.1 背景：不同互连架构下的地址空间不一致

CXL 设备与 CXL Bridge 使用相同的 HPA 空间，这在同一主机域内的所有组件之间是通用的：主机与设备之间的 CXL.mem 路径上，地址区域视图必须保持一致（参见 CXL 3.2 规范 Table 1-1、3.3.1、8.2.4.20、9.13.1、9.18.1.3）。

但并非所有平台都共享同一主机物理地址空间。当平台互连架构不同时，挂载到主机的组件（如 CXL 设备）可能处于不同的 HPA 空间，此时需要地址翻译在主机与组件之间转换 HPA。翻译机制是主机特有的、与实现相关的。

典型例子：x86 AMD 平台使用 Data Fabric 管理对物理内存的访问。设备拥有自己的内存空间，可以被配置为使用与 SPA 不同的 "Normalized Address"（规范化地址），因此需要地址翻译。这类 AMD 平台在固件中提供PRM（Platform Runtime Mechanism，平台运行时机制）handler来执行多种地址翻译，包括针对 CXL 端点的翻译。AMD Zen5 系统实现了 ACPI PRM CXL Address Translation 固件调用，并通过特定 GUID 唯一标识支持 Normalized addressing 的平台（详见 AMD Family 1Ah ACPI v6.5 Porting Guide Publication #58088 的 "Address Translation - CXL DPA to System Physical Address"）。

3.2 Normalized Addressing 模式下 HDM Decoder 的特殊行为

在 Normalized Address 模式下，HDM Decoder 地址范围必须以不同方式配置和处理：

端点 HDM Decoder 配置中使用的硬件地址不是 SPA，需要从端点的地址范围翻译到 CXL Host Bridge 的地址范围；
这对定位端点关联的 CXL Host Bridge 及 CFMWS 描述的 HPA 窗口至关重要；
交织解码由 Data Fabric 完成，端点本身不执行 HPA→DPA 的解码，端点交织被关闭（1-way）；
在进行性能分析（profiling）、追踪（tracing）或错误处理时，也可能需要地址翻译来查看端点的硬件地址。

3.3 文档中的完整示例：4 路交织的 Normalized Addressing

文档给出了一个详细的示例：Root Decoder（CFMWS）为 1-way、512GB 的 SPA 范围，Host Bridge Decoder 为 4-way 交织、targets 为 endpoint5/8/11/13、granularity 256，而四个端点各自的 decoder 均为 1-way、DPA 起始 0x0、大小 128GB、granularity 256。

这一拓扑在 sysfs 中的呈现（端点侧）：

/sys/bus/cxl/devices/endpoint5/decoder5.0/interleave_granularity:256 /sys/bus/cxl/devices/endpoint5/decoder5.0/interleave_ways:1 /sys/bus/cxl/devices/endpoint5/decoder5.0/size:0x2000000000 /sys/bus/cxl/devices/endpoint5/decoder5.0/start:0x0 /sys/bus/cxl/devices/endpoint8/decoder8.0/interleave_granularity:256 /sys/bus/cxl/devices/endpoint8/decoder8.0/interleave_ways:1 /sys/bus/cxl/devices/endpoint8/decoder8.0/size:0x2000000000 /sys/bus/cxl/devices/endpoint8/decoder8.0/start:0x0 /sys/bus/cxl/devices/endpoint11/decoder11.0/interleave_granularity:256 /sys/bus/cxl/devices/endpoint11/decoder11.0/interleave_ways:1 /sys/bus/cxl/devices/endpoint11/decoder11.0/size:0x2000000000 /sys/bus/cxl/devices/endpoint11/decoder11.0/start:0x0 /sys/bus/cxl/devices/endpoint13/decoder13.0/interleave_granularity:256 /sys/bus/cxl/devices/endpoint13/decoder13.0/interleave_ways:1 /sys/bus/cxl/devices/endpoint13/decoder13.0/size:0x2000000000 /sys/bus/cxl/devices/endpoint13/decoder13.0/start:0x0

注意：端点交织配置使用直接映射（1-way），这与"交织解码由 Data Fabric 完成"的约定一致。

通过 PRM 调用，内核可以确定如下映射（HPA→SPA）：

cxl decoder5.0: address mapping found for 0000:e2:00.0 (hpa -> spa): 0x0+0x2000000000 -> 0x850000000+0x8000000000 ways:4 granularity:256 cxl decoder8.0: address mapping found for 0000:e3:00.0 (hpa -> spa): 0x0+0x2000000000 -> 0x850000000+0x8000000000 ways:4 granularity:256 cxl decoder11.0: address mapping found for 0000:e4:00.0 (hpa -> spa): 0x0+0x2000000000 -> 0x850000000+0x8000000000 ways:4 granularity:256 cxl decoder13.0: address mapping found for 0000:e1:00.0 (hpa -> spa): 0x0+0x2000000000 -> 0x850000000+0x8000000000 ways:4 granularity:256

对应的 CXL Host Bridge（HDM）Decoder 与 Root Decoder（CFMWS）与上述计算出的端点映射一致：

/sys/bus/cxl/devices/port1/decoder1.0/interleave_granularity:256 /sys/bus/cxl/devices/port1/decoder1.0/interleave_ways:4 /sys/bus/cxl/devices/port1/decoder1.0/size:0x8000000000 /sys/bus/cxl/devices/port1/decoder1.0/start:0x850000000 /sys/bus/cxl/devices/port1/decoder1.0/target_list:0,1,2,3 /sys/bus/cxl/devices/port1/decoder1.0/target_type:expander /sys/bus/cxl/devices/root0/decoder0.0/interleave_granularity:256 /sys/bus/cxl/devices/root0/decoder0.0/interleave_ways:1 /sys/bus/cxl/devices/root0/decoder0.0/size:0x8000000000 /sys/bus/cxl/devices/root0/decoder0.0/start:0x850000000 /sys/bus/cxl/devices/root0/decoder0.0/target_list:7

3.4 需要的规范变更（Code First 提案）

该约定向 CXL 3.2 规范提出了以下变更建议：

允许 CXL 设备处于与主机不同的 HPA 空间；
允许平台在主机与设备之间的 CXL.mem 路径上跨内存域使用实现特定的地址翻译；
定义一个 PRM handler 方法，用于将设备地址转换为 SPA；
规定平台必须向操作系统提供该 PRM handler 方法，用于检测 Normalized addressing、确定端点 SPA 范围与交织配置；
在规范参考文档表中加入Platform Runtime Mechanism Specification, Version 1.1 – November 2020。

同时给出建议写入规范的段落：

8.2.4.20 CXL HDM Decoder Capability Structure追加说明：设备可能使用与主机域其他组件不共同的 HPA 空间，平台负责跨 HPA 空间的地址翻译；OS 必须确定交织配置并按需对 HDM Decoder 的 HPA 范围执行地址翻译；平台通过提供 PRM handler 表明支持独立 HPA 空间及翻译需求。
新增 9.18.4 节 PRM Handler for CXL DPA to System Physical Address Translation：说明在 Normalized Address 模式下，HPA 空间是组件特定的、与 SPA 不同；端点有自己独立的物理地址空间；提交给设备的所有请求已经使用 DPA；CXL 端点 Decoder 交织被禁用（1-way），设备不执行 HPA 解码来确定 DPA。OS 通过识别 PRM handler 来确认平台支持 Normalized addressing。

9.18.4.1 PRM Handler Invocation规定了 handler 的标识与调用方式：

使用直接调用机制（direct invocation mechanism，细节见 PRM 规范）；
PRM handler 由以下 GUID 标识：

EE41B397-25D4-452C-AD54-48C6E3480B94

调用方分配并准备一个 Parameter Buffer，将 PRM handler GUID 与 Parameter Buffer 指针传给 handler。

Table 9-32：PRM Parameter Buffer（CXL DPA→SPA 翻译）

Byte Offset	Length in Bytes	Description
00h	8	CXL Device Physical Address (DPA)：CXL DPA（例如来自 CXL Component Event Log）
08h	4	CXL Endpoint SBDF：Byte 3 = PCIe Segment；Byte 2 = Bus Number；Byte 1 = Device Number Bits[7:3] + Function Number Bits[2:0]；Byte 0 = RESERVED (MBZ)
0Ch	8	Output Buffer：指向输出缓冲区的虚拟地址指针（缓冲区格式见 Table 9-33）

Table 9-33：PRM Output Buffer（CXL DPA→SPA 翻译）

Byte Offset	Length in Bytes	Description
00h	8	System Physical Address (SPA)：由 CXL DPA 转换得到的 SPA

3.5 收益

如果没有该变更，操作系统可能无法确定端点及其 HDM Decoder 对应的内存区域与 Root Decoder，region 创建会失败，互连架构不同的平台将无法配置和使用 CXL。

3.6 源码实现印证

第 22-24 行定义了与文档 9.18.4.1 完全一致的 GUID：EE41B397-25D4-452C-AD54-48C6E3480B94；
struct prm_cxl_dpa_spa_data（第 26-33 行）精确对应 Table 9-32 的 Parameter Buffer 布局：dpa、devfn、bus、segment与spa输出指针，且为__packed结构；
prm_cxl_dpa_spa()（第 35-58 行）填充参数并通过acpi_call_prm_handler(prm_cxl_dpa_spa_guid, &data)调用固件，翻译失败时返回ULLONG_MAX；
cxl_prm_setup_root()（第 60 行起）实现端点 HPA 范围到 SPA 范围的翻译，并特别处理：当端点与 DPA 为 1:1 映射（未开启 Normalized Addressing）时跳过翻译只做范围检查（第 77-78 行）；在 Normalized Addressing 模式下端点按 passthrough 编程、要求交织路数为 1（第 83-87 行）；翻译得到的地址包含交织偏移，因此将范围按 256MB 对齐（第 112-117 行）——这与前一节讨论的 256MB 对齐粒度一脉相承。

另外 drivers/cxl/Kconfig 中也出现了 PRM 相关配置项，说明该功能随内核配置可选编译。

四、两份约定的关联与总结

4.1 共同点：256MB 对齐粒度

两份约定看似主题不同（一个是"窗口被裁剪变小"，一个是"地址需要翻译"），但都围绕 CXL 地址解码的核心约束展开：

裁剪场景：Root Decoder 因 LMH 裁剪而小于 HDM Decoder、且不满足 NIW×256MB 规则，Linux 允许 base 为 0 的 region 绕过检查；
翻译场景：端点地址是 Normalized Address，必须经 PRM 翻译回 SPA 才能与 CFMWS/HDM Decoder 匹配，翻译后的范围同样要按 256MB 对齐。

内核代码中 drivers/cxl/acpi.c 的 CFMWS 对齐校验、drivers/cxl/core/port.c 的 decoder 大小对齐检查，以及 drivers/cxl/cxlmem.h 的CXL_CAPACITY_MULTIPLIER定义，共同构成了这一对齐粒度的完整证据链。

4.2 适用范围与限制（务必注意）

两处约定都有明确的边界，不可滥用：

cxl-lmh 的绕过仅适用于 base 为 0GB 的 region，专为 x86 平台在 4GB 以下映射 CXL 内存而设，不适用于其他任意 region；
cxl-atl 的翻译路径仅适用于支持 Normalized Addressing 的平台（通过 PRM handler 的 GUID 存在性来检测），且端点必须处于 1-way 直通配置。

4.3 对读者的实用价值

如果你是平台固件开发者或 Linux 内核驱动开发者，可以从本系列约定中获得三点直接收益：

排查 region 构建失败：遇到"Root Decoder 与 HDM Decoder 大小不匹配"或"地址未 256MB 对齐"的报错时，可对照 conventions/cxl-lmh.rst 判断是否属于 LMH 裁剪场景；
诊断端点地址异常：在 AMD Zen5 等平台上观察 sysfs 中端点 decoder 的start/size/interleave_ways与 Host Bridge decoder 不一致时，可通过 drivers/cxl/core/atl.c 的cxl decoderX.Y: address mapping found ...调试日志确认 PRM 翻译是否生效；
新增平台约定：如果遇到新的平台偏差，可参照 conventions/template.rst 的模板，按 Document → Summary → Benefits → References → Detailed Description 的结构向 Linux 社区提交约定文档，并同步给出内核侧实现与 sysfs 示例。

五、延伸阅读

以下文档与源码可帮助你在当前仓库中进一步深入：

文档体系入口：Documentation/driver-api/cxl/index.rst（含理论模型 theory-of-operation、成熟度矩阵 maturity-map、平台配置与 Linux 配置指南）
CXL 地址翻译相关内核文档：Documentation/admin-guide/RAS/address-translation.rst（x86 AMD 地址翻译）
CXL 驱动实现：drivers/cxl/acpi.c（CFMWS 解析与校验）、drivers/cxl/core/region.c（region 构建与交织对齐）、drivers/cxl/core/port.c（端口与 decoder 管理）

【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析