9.20.7. NVDIMM 根设备 _DSMs

下面描述了 NVDIMM 根设备的设备特定方法（_DSM）。

9.20.7.1. 输入参数：

Arg0 - UUID（设置为 2f10e7a4-9e91-11e4-89d3-123b93f75cba）

Arg1 - Revision ID（设置为 1）

Arg2 - Function Index

表 9.17 NVDIMM 根设备函数索引

函数索引	描述
0	查询已实现的命令（见第 9.1.1 节）
1	查询地址范围清理（ARS）能力（见第 9.20.7.4 节）
2	启动地址范围清理（ARS）（见第 9.20.7.5 节）
3	查询地址范围清理（ARS）状态（见第 9.20.7.6 节）
4	清除不可校正错误（见第 9.20.7.7 节）
5	转换 SPA
6	保留
7	ARS 错误注入
8	清除 ARS 错误注入
9	ARS 错误注入状态查询
0xA	查询 ARS 错误注入能力
0xB - 0xFFFF	保留

Arg3 - 一个包，包含由 UUID、Revision ID 和 Function Index 指定的功能的参数。每个命令的包布局以及相应的输出在下表中说明。输入和输出包都是字节列表（Buffer）。

9.20.7.2. 地址范围清理（ARS）概述

ARS 允许平台将内存错误传达给系统软件。此能力允许系统软件阻止对内存中具有不可校正错误的地址进行访问。

ARS 功能是系统范围的，而不是特定于单个 NVDIMM，也就是说，它们管理系统中存在的所有 NVDIMM。

查询 ARS 能力 功能指示某个地址范围是否支持 ARS，并用于发现系统范围属性，例如 查询 ARS 状态 功能可返回的数据最大量，以及平台是否提供异步 ACPI 通知以表明已发现新的不可校正错误。

在任意给定时间，系统范围内只能有一个清理操作正在进行。OSPM 在发出 启动 ARS 功能之前，应先发出 查询 ARS 状态 功能并确保没有 ARS 正在进行。如果返回成功状态，则 查询 ARS 状态 功能的扩展状态会向 OSPM 指示以下情况之一：

ARS 已完成，并返回 ARS 结果。OSPM 应在发出另一个 启动 ARS 功能之前处理这些结果。当启动新的地址范围清理操作时，先前的 ARS 结果将丢失。
ARS 正在进行中，并且不返回 ARS 结果。当 ARS 正在进行时，启动 ARS 功能会失败。OSPM 应定期发出 查询 ARS 状态 功能，直到 ARS 不再进行中。
自平台启动以来尚未进行过 ARS，因此不返回 ARS 结果。可以发出新的 启动 ARS 功能。
ARS 过早停止，并返回部分结果。如果平台要返回的数据多于 Max Query ARS Status Output Buffer Size（见第 9.20.7.4 节）所能容纳的数量，OSPM 可以循环发出 启动 ARS 和 查询 ARS 状态 功能，并通过在每次迭代中修改 ARS Start SPA Address 和长度来检索所有 ARS 错误记录。

如果发出了 启动 ARS 功能，OSPM 会为要清理的范围提供 ARS Start SPA Address 和 ARS Length。如果先前的 ARS 过早停止，则这些字段应设置为上一次 查询 ARS 状态 输出缓冲区中的 Restart ARS Start SPA Address 和 Restart ARS Length 的值。对于任何 启动 ARS 功能，OSPM 可以选择将 Flags Bit[0] 置位，以向平台表明该 ARS 具有优先级，并可能导致其他处理延迟，例如在启动期间。成功的 启动 ARS 功能的输出会提供完成清理所需估计时间，作为向 OSPM 提示何时发出 查询 ARS 状态 功能。

如 查询 ARS 能力 功能输出所示，平台在检测到新的不可校正错误时，可能会发出异步事件通知 0x81（检测到未消耗的不可校正内存错误通知）。收到该通知后，OSPM 可以决定发出一个将 Flags Bit [1] 置位的 启动 ARS，以准备检索现有记录，并发出 查询 ARS 状态 功能来检索这些记录。OSPM 可以将整个持久内存范围作为 启动 ARS 的“ARS Start SPA Address”和“ARS Length”传递，即使持久内存范围不是连续的。或者，OSPM 也可以决定忽略事件通知 0x81。如果在 OSPM 处理 ARS 数据之前访问了该内存范围，则可能发生默认的平台错误处理序列，例如 Machine Check。

平台可能支持让 OSPM 清除先前由 ARS 报告的错误的能力。OSPM 仅应在以下情况下对某个内存地址范围发出 清除不可校正错误 功能：该地址范围已从进一步使用中退役，或者在读取这些位置之前已向该范围写入有效的无错误数据。如果平台不支持 清除不可校正错误 功能，或者某个地址范围的 清除不可校正错误 功能失败，则 OSPM 应继续阻止对这些地址范围的访问。

ARS 相关功能对 Status 和 Extended Status 字段使用以下约定。

9.20.7.3. 地址范围清理（ARS）错误注入概述

预期的 OSPM ARS 错误注入流程为：

使用 ARS 错误注入注入一个错误。
可选地，如果主机支持 ARS 检测到未消耗的不可校正内存错误通知，则系统固件会为 OSPM 触发一个 ACPI NVDIMM 根设备通知 0x81。
使用 Flags 的 Bit[1] 置位的启动 ARS，以便 OSPM 向系统固件确认该通知，并使用查询 ARS 状态来查询 ARS 状态。
可选地，使用 ARS 错误注入状态查询查询已注入错误的范围。
使用 ARS 错误注入清除来清除 ARS 已注入错误的范围。在错误被清除之前，系统固件将在查询 ARS 状态输出缓冲区中报告该错误。

表 9.18 状态与扩展状态字段的通用解释

字节	字段名称	描述
1-0	状态	0 - 成功 1 - 不支持该功能 2 - 输入参数无效 3 - 硬件错误 4 - 建议重试；执行重试的次数由 OSPM 决定。5 - 错误 - 原因未知 6 - 特定于功能的错误代码 7 - FFFFh 保留用于错误
3-2	扩展状态	特定于功能

注

如果状态非零，则 _DSM（设备特定方法）中所有功能的输出缓冲区仅限于状态和扩展状态字段。

9.20.7.4. 功能索引 1 - 查询 ARS 能力

此功能为给定地址范围提供 ARS 能力。此功能输入和输出的格式如下所示。

9.20.7.4.1. 功能输入

表 9.19 查询 ARS 能力 - 输入缓冲区

字段	字节长度	字节偏移	描述
ARS Start SPA Address	8	0	ARS 的系统物理地址起始地址
ARS Length	8	8	ARS 的长度

9.20.7.4.2. 功能输出

表 9.20 查询 ARS 能力 - 输出缓冲区

字段	字节长度	字节偏移	描述
Status	2	0	在表 9.18 中定义。如果 Status 未设置为 0（成功），则此结构中的所有其他字段均为保留。
Extended Status	2	2	Bit[0] - 如果置为 1，表示支持对易失性内存进行清理。易失性内存是指在 UEFI 或 ACPI 地址范围类型中未标记为 Persistent Memory 的任何区域。Bit[1] - 如果置为 1，表示支持对 Persistent Memory 进行清理。Persistent Memory 是指具有以下内存范围类型之一的任何区域： - UEFI 内存类型 EfiPersisten tMemory - 设置了 EFI_MEMORY_N V 内存属性的任何 UEFI 内存类型 - ACPI 地址范围类型 AddressRange PersistentMemory Bits[15:2] - 保留
Max Query ARS Status Output Buffer Size	4	4	单位为字节。由查询 ARS 状态功能返回的缓冲区最大大小（包括 Status 和 Extended Status 字段）。这可用于计算所支持的 ARS 错误记录的最大数量。对于平台而言，该值应为常量，与输入 SPA 范围无关。只要指定了有效的输入 SPA 范围，返回的该值应始终相同。
Clear Uncorrectable Error Range Length Unit Size	4	8	单位为字节。 - 此字段描述不可纠正错误清除单位大小。该值应为 2 的幂。 - Clear Uncorrectable Errors LSM 功能的 Clear Uncorrectable Error Range Length 参数应为该单位大小的整数倍。 - 查询 ARS 状态 ARS 错误记录格式中的 “Length” 字段应为该单位大小的整数倍。 - ARS Error Inject DSM 功能的 ARS Error Inject SPA Range Length 参数应为该单位大小的整数倍。 - 对于平台而言，该值应为常量，与输入 SPA 范围无关。
Flags	2	12	Bit[0] - 未消费的不可纠正内存错误检测通知标志。如果置为 1，表示平台支持 nvdimm-root-device-notification-values 中所述的 ACPI NVDIMM Root Device 未消费错误通知（0x81）。如果置为 0，则平台不支持此通知机制。Bit[1] - ARS 停止通知标志。如果置为 1，表示平台支持 NVDIMM Root Device Notification Values 中所述的 ARS 停止通知（0x82）。如果置为 0，则平台不支持此通知。Bit[15-2] - 保留。
Reserved	2	14
Clear Uncorrectable Error Max Range Length	4	16	单位为字节。 - 允许平台报告一次可清除的不可纠正错误的最大字节数。 - 该值应为单位大小 Query ARS Capabilities Clear Uncorrectable Error Range Length Unit Size 的整数倍
Reserved1	4	20

9.20.7.5. 功能索引 2 - 启动 ARS

启动 ARS 功能会针对给定内存范围触发一次地址范围清理。地址清理可针对易失性内存、Persistent Memory，或两者同时进行。对于给定输入 ARS Start SPA 和长度，就给定的 Type 参数而言，可能存在一个或多个范围，包括它们之间的间隙。

9.20.7.5.1. 功能输入

表 9.21 启动 ARS - 输入缓冲区

字段	字节长度	字节偏移	描述
ARS Start SPA Address	8	0	单位为字节
ARS Length	8	8	单位为字节
Type	2	16	Bit[0] - 如果置为 1，清理易失性内存 Bit[1] - 如果置为 1，清理 Persistent Memory Bits[15:2] 保留 - 注：如果所提供的范围同时包含易失性和持久性子范围，则只会清理此处指示的类型。
Flags	1	18	Bit[0] - 如果置为 1，指定平台在执行 ARS 期间可能导致处理其他操作时出现延迟（例如，用于系统引导期间）。如果置为 0，指定平台在执行 ARS 期间不得导致处理其他操作时出现延迟（例如，用于运行时）。Bit[1]：如果置为 1，固件应返回先前清理的数据（如果有），而不启动新的清理。如果置为 0，固件应启动新的 ARS。
Reserved	5	19

9.20.7.5.2. 功能输出

表 9.22 启动 ARS - 输出缓冲区

字段	字节长度	字节偏移	描述
Status	2	0	6 - ARS 已在进行中其他所有值在状态与扩展状态字段的通用解释中定义
Extended Status	2	2	保留
Estimated Time for Scrub	4	4	单位为秒对给定地址范围进行清理的预计时间。

9.20.7.6. 功能索引 3 - 查询 ARS 状态

查询 ARS 状态 命令允许软件获取 ARS 的状态。

如果平台支持 ARS 错误注入，则其负载中还应包括已注入的错误。

9.20.7.6.1. 功能输入

无

9.20.7.6.2. 功能输出

表 9.23 查询 ARS 状态 - 输出缓冲区

字段	字节长度	字节偏移	解释
Status	2	0	在状态与扩展状态字段的通用解释中定义
Extended Status	2	2	0 - ARS 完成 1 - ARS 进行中。任何返回的 ARS 数据都应全为零。 2 - 当前引导未执行 ARS。任何返回的 ARS 数据都应全为零。 3 - ARS 提前停止 - 当实现达到可报告错误的最大数量时，可能会发生这种情况。 4 ..0xFFFF- 保留。任何返回的 ARS 数据都应全为零。
ARS Data	可变	4	见 ARS Data。

返回的输出 SPA 范围表示针对指定类型执行的 ARS 清理的范围。

表 9.24 ARS Data

字段	字节长度	字节偏移	解释
Output (Size)	4	0	输出缓冲区大小，单位为字节，包括此字段。
Start SPA	8	4	单位为字节
Length	8	12	单位为字节 ARS 执行的范围是从 Start SPA 到 Start SPA + Length
Restart ARS Start SPA Address	8	20	如果 Status 为 Success 且 Extended Status 报告为 ARS 提前停止，则用于重新启动 ARS 的起始 SPA。此处指定的值在调用 Start ARS 以继续一个在完成所请求的 ARS Length 之前提前停止的 ARS 时，将不作修改地用作 ARS Start SPA Address。注：继续一个已提前停止的 ARS 不是必需的。
Restart ARS Length	8	28	如果 Status 为 Success 且 Extended Status 报告为 ARS 提前停止，则用于重新启动 ARS 的 SPA 长度。此处指定的值在调用 Start ARS 以继续一个在完成所请求的 ARS Length 之前提前停止的 ARS 时，将不作修改地用作 ARS Length。
Type	2	36	Bit[0] - 如果置为 1，则为易失性内存范围 Bit[1] - 如果置为 1，则为 Persistent Memory 范围。如果 bit[0] 和 bit[1] 均置位，则该范围同时包含 Persistent Memory 和易失性内存。Bits[15:2] - 保留
Flags	2	38	Bit[0] - 如果置为 1，表示发生了溢出情况。这意味着错误日志中报告的错误数量超过了 Query ARS Capabilities 中 Max Query ARS Status Data Size 的最大总缓冲区大小所能容纳的数量。当此位被置为 1 时，返回的 Extended Status 应为 ARS 提前停止。Bits[15:1] 保留
Number of Error Records	4	40	报告的 ARS Error Record 结构数量
ARS Error Records	可变	44	ARS 错误记录的格式见下表。

表 9.25 ARS 错误记录格式

字段	字节长度	字节偏移	描述
NFIT Handle	4	0	NFIT Handle 表示 Error Location 的 Start SPA（偏移 8）处的特定 NVDIMM
Reserved	4	4	保留
Start SPA of Error Location	8	8	错误的系统物理地址起始地址。
Length	8	16	Length 表示从 Error Location 的 Start SPA 开始连续处于错误状态的字节数。由于交错，Start SPA of Error Location 和 Length 所覆盖的范围可能包括交错集中的其他 NVDIMM 上存在的地址。在溢出的情况下，Start SPA of Error Location 和 Length 指示的地址范围将覆盖受该错误影响的 NVDIMM 交错集。由于平台限制，Start SPA of Error Location 和 Length 所覆盖的范围可能超出请求的清理范围。

9.20.7.7. 功能索引 4 - 清除不可纠正错误

Clear Uncorrectable Error 功能允许系统软件基于系统物理地址（SPA）从 NVDIMM 中清除不可纠正错误。Query ARS Status 功能报告的不可纠正错误可利用此机制进行清除。

对于指定 SPA 范围所覆盖、且包含不可纠正错误的每个不可纠正错误范围长度，平台软件应清除该错误，并且可以修改这些地址处的数据。对于指定 SPA 范围所覆盖、但不包含不可纠正错误的每个不可纠正错误范围长度，平台软件不应执行任何操作。

Clear Uncorrectable Error SPA Range Base 应按 Clear Uncorrectable Error Range Length Unit Size 对齐，且 Clear Uncorrectable Error Range Length 必须为 Clear Uncorrectable Error Range Length Unit Size 的整数倍。如果未遵循这些规则，Clear Uncorrectable Error 请求应导致 Invalid Parameter 错误状态。

尝试使用超出某区域末端的范围长度来清除错误，应导致 Invalid Parameter 错误状态。

尝试使用大于不可纠正错误范围的范围长度来清除错误，不应被视为失败。

尝试从当前并不存在不可更正错误的地址清除错误，不应被视为失败。

注

使用此命令清除的位置中包含的数据是不确定的。使用此命令时必须小心，因为一旦错误被清除，如果软件不知道原始内容已经丢失，则随后对这些已清除位置的读取将导致静默数据损坏。只有在软件能够保证这些位置已从后续使用中退役，或者在读取这些位置之前会写入有效数据的情况下，软件才应使用此命令。

OSPM 可以对通过 ARS 错误注入功能注入的 ARS 错误范围调用 清除不可更正错误。如果平台支持此操作，则最终应将其视为调用了 ARS 错误注入清除 功能。如果平台不支持此操作，则应以输入参数无效错误失败。

9.20.7.7.1. 功能输入

表 9.26 清除不可更正错误 - 输入缓冲区

字段	字节长度	字节偏移	描述
清除不可更正错误 SPA 范围基址	8	0	以字节为单位，要从其开始清除不可更正错误的起始位置。该地址应按 Query ARS Capabilities 功能中报告的清除不可更正错误范围长度单位大小对齐（参见功能索引 1 - Query ARS Capabilities）。
清除不可更正错误范围长度	8	8	以字节为单位，要从中清除不可更正错误的区域长度。该长度应为 Query ARS Capabilities 功能中报告的清除不可更正错误范围长度单位大小的整数倍（参见功能索引 1 - Query ARS Capabilities）。

9.20.7.7.2. 功能输出

表 9.27 清除不可更正错误 - 输出缓冲区

字段	字节长度	字节偏移	描述
状态	2	0	定义见状态和扩展状态字段通用解释。
扩展状态	2	2	保留
Reserved	4	4	保留
Cleared Uncorrectable Error Range Length	8	8	平台实际清除错误的范围，从请求的 Clear Uncorrectable Error SPA Range Base 开始。该长度应为 Query ARS Capabilities 功能中报告的 Clear Uncorrectable Error Range Length Unit Size 的整数倍（参见功能索引 1 - Query ARS Capabilities）。注：该范围长度可能小于输入范围长度所请求的长度。

9.20.7.8. 功能索引 5 - 转换 SPA

此命令指示平台将所请求的系统物理地址（SPA）转换为一个或多个 NVDIMM 设备，这些设备由 NFIT Device Handle 和该设备上的 Device Physical Address（DPA）组成。

要转换的 SPA 地址必须位于 NFIT System Physical Address Range 表所描述的某个 SPA 范围内。
对于非镜像交错集，SPA 地址将转换为单个 NVDIMM 和单个 DPA。
对于 HW 镜像交错集，Flags Bit[0] - Mirrored SPA Location 位被置位，并且 SPA 所转换到的所有 NVDIMM 设备都包含在返回的 NVDIMM 设备列表中。

9.20.7.8.1. 功能输入

下表概述了此命令所需的输入负载。

表 9.28 转换 SPA - 输入负载格式

字段	字节长度	字节偏移	描述
SPA	8	0	要转换的系统物理地址。这是一个按字节对齐的地址，所有位都被视为有效。不进行掩码或移位。

9.20.7.8.2. 功能输出

下列表格概述了此命令所需的输出负载。

表 9.29 转换 SPA - 输出负载格式

字段	字节长度	字节偏移	描述
Status	2	0	定义见 Status 和 Extended Status 字段通用解释。如果 SPA 不位于 NFIT System Physical Address Range 表所描述的某个 SPA 范围内，则返回状态 2，即 Invalid Input Parameter。如果 Status 未设置为 0（即 Success），则此结构中的所有其他字段均为保留。
Extended Status	2	2	Extended Status 字段（厂商定义）
Flags	1	4	Bit[0] - Mirrored SPA Location - 如果设置为 1，表示该 SPA 位置映射到一个或多个彼此镜像并共同构成单个 SPA 范围的 NVDIMM。当前参与 HW Mirror 的所有 NVDIMM 都应被报告，并且 Number of NVDIMMs 应报告 Mirrored SPA 范围中的所有设备。
Reserved	3	5	必须为 0
Translated Length	8	8	返回的 SPA 转换所适用的字节数。由输入 SPA + 输出 Translated Length -1 所定义的 SPA 范围将产生地址转换，其中包含恒定的 Translated NVDIMM Device List，该列表包含一组恒定的 NFIT Device Handles。
Number of NVDIMMs	4	16	在 Translated NVDIMM Devices 列表中返回的 NVDIMM 设备数量。对于给定的 SPA 位置，这通常为 1，但对于 Mirrored SPA Locations，可能有多个 NVDIMM 提供相同的 SPA。
Translated NVDIMM Device List	Varies	20	一个或多个 Translated NVDIMM Devices 的列表

9.20.7.8.3. 已转换的 NVDIMM 设备

表 9.30 转换 SPA - 已转换的 NVDIMM 设备列表输出负载格式

字段	字节长度	字节偏移	描述
NFIT Device Handle	4	0	SPA 映射到的物理 NVDIMM 的句柄。可利用此句柄检索进一步描述该物理设备的其他 NFIT 表数据。
Reserved	4	4	返回为零
DPA	8	8	SPA 转换得到的 Device Physical Address。

9.20.7.9. 功能索引 7 - ARS 错误注入

ARS Error Inject 允许对定义输入负载中的内存范围注入错误。输入是一个包含单个缓冲区的包，其中该缓冲区的格式如 ARS Error Inject - Input Format 所示。

9.20.7.9.1. 输入（Arg3）

表 9.31 ARS 错误注入 - 输入格式

字段	字节长度	字节偏移	描述
ARS Error Inject SPA Range Base	8	0	要从其开始注入错误的起始位置。
ARS Error Inject SPA Range Length	8	8	以字节为单位，要向其注入错误的区域长度。如果 Length 使该范围跨越 NVDIMM SPA 范围，则系统固件实现可以在 ARS Query Status _DSM 功能的输出缓冲区中报告多条 ARS 错误记录。
ARS Error Inject Options	1	16	Bit 0：未消耗的不可更正内存错误检测通知。设置为 1 时，固件应通知 OSPM。设置为 0 时，不会发生通知。Bit 1：强制溢出。设置为 1 时，当 Query ARS Status 遇到此范围时触发溢出条件。值 0 将被忽略。详见下文。Bit 2：持久错误。设置为 1 时，使此错误在重启后持续存在。这些是在指定内存位置注入的不可更正错误。设置为 0 时，确保该错误在重启时被清除。Bits 7-3：保留。

OSPM 可以通过在输入结构的 ARS Error Inject Options 中设置 Force Overflow 位（bit 1）来触发 Query ARS Status 溢出条件。

如果 Force Overflow 位设置为 0，则平台在必要时仍可触发溢出条件（例如，从 Query ARS Status 返回的错误记录数量超过 Query ARS Status Data Size）。

强制产生溢出条件的典型顺序如下：

OSPM 调用 ARS Error Inject 为特定范围注入错误，并在输入结构中设置以下字段：
a. 将 ARS Error Inject Options bit 0 设置为 0，以便该范围不会发生未消耗的不可更正内存错误检测通知。
b. 将 ARS Error Inject Options bit 1 设置为 1，表示系统固件在遇到该范围时应强制产生溢出条件。
OSPM 使用 ARS Error Inject 注入第二个错误，将 ARS Error Inject Options bit 0 设置为 1，并将 bit 1 清除为 0。
系统固件通过未消耗的不可更正内存错误检测通知将新错误通知 OSPM。
OSPM 响应该通知调用 Query ARS Status。

当系统固件遇到第一个注入范围时，它会看到 ARS Error Inject Options bit 1 已设置，并在输出 ARS Data 中将 Flags bit 0 设置为 1，以指示溢出条件。系统固件还会相应地设置 Restart ARS Start SPA Address 和 Restart ARS Length。
OSPM 调用 Start ARS，并在输入结构中设置以下字段：
a. 将 Flags bit 1 设置为 1，表示它不想启动新的 scrub。
b. 将 ARS Start SPA Address 设置为 Query ARS Status 输出中的 Restart ARS Start SPA Address。
c. 将 ARS Length 设置为 Query ARS Status 输出中的 Restart ARS Length。
OSPM 调用 Query ARS Status。
系统固件返回第二个注入范围。

当设置 Persistent Error 位时，错误范围和 ARS Error Inject Options 位应在重启后持续保留。

9.20.7.9.2. 输出

此函数的返回值是一个缓冲区，其格式如下表所示。

表 9.32 ARS 错误注入 - 输出格式

字段	字节长度	字节偏移	描述
Status	2	0	Bytes[1-0] 0 - 成功 1 - 不支持。平台不支持 ARS Error Inject 方法。2 - 输入参数无效。平台报告传递给 ARS Error Inject 方法的 SPA 范围参数无效，或者不支持通知。
Extended Status	2	2	保留

9.20.7.10. 功能索引 8 - ARS 错误注入清除

ARS Error Clear 允许清除定义输入负载中的持久内存范围内已注入的错误状态。

9.20.7.10.1. 输入（Arg3）

输入是一个包含单个缓冲区的包，其中该缓冲区的格式如下表所示。

表 9.33 ARS 错误注入清除 - 输入格式

字段	字节长度	字节偏移	描述
ARS Error Inject Clear SPA Range Base	8	0
ARS Error Inject Clear SPA Range Length	8	8	以字节为单位

9.20.7.10.2. 输出