FillDeviceMemory 函数

FillDeviceMemory 函数会在开发人员需要额外确保访问设备内存时不会发生对齐错误的情况下，设置缓冲区的内容，且不受编译器优化干扰。

重要

一些信息与预发布产品相关，在商业发行之前可能会发生实质性修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

参数

Param Destination [out]

指向要填充的内存块起始地址的指针。

Param Length [in]

要填充的内存块的大小（以字节为单位）。 此值必须小于目标缓冲区的大小。

Param Fill [in]

要用于填充内存块的字节值。

语法

volatile void*
  FillDeviceMemory (
    _Out_writes_bytes_all_(Length) volatile void* Destination,
    SIZE_T Length,
    INT Fill
  );

备注

在开发人员需要进一步确保访问设备内存时不会产生对齐错误的情况下，此 API 用于提供 FillVolatileMemory 行为（即设置缓冲区的内容，且不受编译器优化的干扰）。 每个 API 具有以下属性：

• API 不会被识别为编译器内部函数，因此编译器永远不会优化调用（完全去除或用“等效”指令序列替换调用）。 这不同于 FillMemory，后者受多项编译器优化的影响。
• 调用完成后，缓冲区已被所需值覆盖。 此函数内存对目标的访问只在函数中执行（编译器无法在此函数外访问内存）。
• 仅当 CPU 支持设备内存上的未对齐内存访问时，API 才能执行未对齐内存访问。 如果 CPU 不支持未对齐的设备内存访问，则只会执行对齐的访问。
• API 在操作期间可以多次访问内存位置。

注意

此函数仅保证遵循 CPU 访问映射为设备内存的内存这一要求。 如果特定设备对访问有自己的特定要求，则不应使用此功能（相反，开发人员必须实现自己的访问器函数）。 例如，此函数无法保证生成的内存访问大小（除非 CPU 本身强制执行这些要求）。

注意

此函数适用于所有版本的 Windows，而不仅仅是最新版本。 需要使用最新的 SDK 从 winbase.h 标头获取函数声明。 还需要最新 SDK 中的库 (volatileaccessu.lib)。 但是，生成的二进制文件将能够很好地在较旧版本的 Windows 上运行。

示例

// In this scenario we are setting data on memory mapped
// as "device memory" (i.e. memory not backed by RAM). On
// some platforms like ARM64, device memory cannot tolerate
// memory accesses that are not naturally aligned (i.e. a 4-byte
// load must be 4-byte aligned). Functions like memset, FillMemory,
// and even FillVolatileMemory may perform unaligned memory accesses
// because it is typically faster to do this.
// To ensure only naturally aligned accesses happen, use FillDeviceMemory.

FillDeviceMemory(DeviceMemoryBuffer, 100, 0xAA);

要求

支持的最低客户端：Windows 11 Insider 预览版（待定）

标头：winbase.h（包括 Winbase.h）

Kernel-mode 库：volatileaccessk.lib

User-mode 库：volatileaccessu.lib

另请参阅

• FillVolatileMemory
• FillMemory