Linux 内核 CXL 平台约定CXL Linux Conventions指南规范偏差记录与 PRM 地址翻译实现解析【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux导读CXLCompute Express Link规范定义了设备与主机之间的内存互连行为但实际出货的平台上往往存在偏离或打破 CXL 规范预期的固件/硬件实现。Linux 内核在Documentation/driver-api/cxl/文档体系中专门设立了一套CXL Linux ConventionsCXL 平台约定借鉴 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.rstCFMWS、平台内存空洞与端点 Decoder 的冲突x86 平台在 4GB 以下存在 Low Memory HolePCIe MMIO 空洞conventions/cxl-atl.rstACPI 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.0License文档采用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-lmh2.1 背景CFMWS、HPA 与 SPA 的基本概念要理解第一个约定需要先厘清几个地址空间概念HPAHost Physical Address主机物理地址CXL 设备实际能够解码并响应的物理内存地址空间。SPASystem Physical Address系统物理地址系统可见、用户可以直接发起事务访问的地址空间它排除了保留区域。CFMWSCXL Fixed Memory Window Structure由平台固件通过 ACPI CEDT 表发布的结构描述与每个 CXL Host Bridge 关联的零个或多个 HPA 窗口。每个窗口是一段连续的 HPA 范围可能以一个或多个目标包括 CXL Host Bridge进行交织interleave。HDM DecoderHost-managed Device Memory Decoder位于 CXL 设备/交换机/根端口中的解码器寄存器负责将 HPA 转换为 DPADevice Physical Address或完成地址裁剪。OSPMOperating 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 示例平台配置两个 CFMWSLMH 从 2GB 开始WindowCFMWS BaseCFMWS SizeHDM Decoder BaseHDM Decoder SizeWays00 GB2 GB0 GB3 GB1214 GBNIW×256MB 对齐4 GBNIW×256MB 对齐12关键差异在于HDM Decoder Base/Size 表示 12 路12 waysregion 的全部 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 Addressingcxl-atl3.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 平台在固件中提供PRMPlatform 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 DecoderCFMWS为 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→SPAcxl decoder5.0: address mapping found for 0000:e2:00.0 (hpa - spa): 0x00x2000000000 - 0x8500000000x8000000000 ways:4 granularity:256 cxl decoder8.0: address mapping found for 0000:e3:00.0 (hpa - spa): 0x00x2000000000 - 0x8500000000x8000000000 ways:4 granularity:256 cxl decoder11.0: address mapping found for 0000:e4:00.0 (hpa - spa): 0x00x2000000000 - 0x8500000000x8000000000 ways:4 granularity:256 cxl decoder13.0: address mapping found for 0000:e1:00.0 (hpa - spa): 0x00x2000000000 - 0x8500000000x8000000000 ways:4 granularity:256对应的 CXL Host BridgeHDMDecoder 与 Root DecoderCFMWS与上述计算出的端点映射一致/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:73.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 不同端点有自己独立的物理地址空间提交给设备的所有请求已经使用 DPACXL 端点 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-32PRM Parameter BufferCXL DPA→SPA 翻译Byte OffsetLength in BytesDescription00h8CXL Device Physical Address (DPA)CXL DPA例如来自 CXL Component Event Log08h4CXL Endpoint SBDFByte 3 PCIe SegmentByte 2 Bus NumberByte 1 Device Number Bits[7:3] Function Number Bits[2:0]Byte 0 RESERVED (MBZ)0Ch8Output Buffer指向输出缓冲区的虚拟地址指针缓冲区格式见 Table 9-33Table 9-33PRM Output BufferCXL DPA→SPA 翻译Byte OffsetLength in BytesDescription00h8System Physical Address (SPA)由 CXL DPA 转换得到的 SPA3.5 收益如果没有该变更操作系统可能无法确定端点及其 HDM Decoder 对应的内存区域与 Root Decoderregion 创建会失败互连架构不同的平台将无法配置和使用 CXL。3.6 源码实现印证这一约定在 Linux 内核中已有完整实现。drivers/cxl/core/atl.cCopyright (C) 2025 Advanced Micro Devices, Inc.正是 PRM 地址翻译的落地代码第 22-24 行定义了与文档 9.18.4.1 完全一致的 GUIDEE41B397-25D4-452C-AD54-48C6E3480B94struct 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_MAXcxl_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 内存而设不适用于其他任意 regioncxl-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.rstx86 AMD 地址翻译CXL 驱动实现drivers/cxl/acpi.cCFMWS 解析与校验、drivers/cxl/core/region.cregion 构建与交织对齐、drivers/cxl/core/port.c端口与 decoder 管理【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
