CopyDeviceMemory 函式

  • 發行項

CopyDeviceMemory 函式會在開發人員需要另外確定存取裝置記憶體時不會產生對齊錯誤的情況下，將記憶體從某個位置複製到另一個位置，而不會干擾編譯程序優化。

重要

某些資訊與發行前版本產品有關，在發行前版本產品可能經過大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

參數

Param 目的地 [out]

所複製區塊目的地之起始位址的指標。

Param 來源 [in]

要複製之內存區塊起始位址的指標。

Param Length [in]

要複製的記憶體區塊大小，以位元組為單位。

語法

volatile void*
  __cdecl
  CopyDeviceMemory (
    _Out_writes_bytes_all_(Length) volatile void* Destination,
    _In_reads_bytes_(Length) volatile const void* Source,
    SIZE_T Length
  );

備註

此 API 存在以提供 CopyVolatileMemory 行為（例如，在開發人員需要另外確定存取裝置記憶體時不會產生對齊錯誤的情況下，從某個位置複製到另一個位置，而不會干擾編譯程式優化）。 API 具有下列屬性：

  • API 無法辨識為編譯程式內部函數，因此編譯程式永遠不會優化呼叫（完全取代呼叫，或將呼叫取代為「對等」的指令序列）。 這與 CopyMemory 不同，這受限於各種編譯程序優化。
  • 呼叫傳回時，數據已從來源複製到目的地。 此函式記憶體存取 來源 和 目的地 只會在函式內執行（亦即編譯程式無法將記憶體存取移出此函式）。
  • 只有當 CPU 支援裝置記憶體上的未對齊記憶體取時，API 才能執行未對齊的記憶體存取。 如果 CPU 不支援未對齊的裝置記憶體存取，則只會執行對齊的存取。
  • API 可能會在其複製作業中多次存取記憶體位置。
  • 當來源和目的地彼此重疊時，不支援複製作業。 如果提供重疊的緩衝區，則快速失敗，並FAST_FAIL_INVALID_ARG錯誤碼。

注意

此函式只保證會遵守 CPU 存取對應為 裝置記憶體的記憶體 需求。 如果特定裝置有自己存取的特定需求，則不應使用此函式（而開發人員必須實作自己的存取子函式）。 例如，此函式不保證產生的記憶體存取大小（除非 CPU 本身強制執行這些需求）。

注意

此函式適用於所有版本的 Windows，而不只是最新版本。 您必須取用最新的 SDK，才能從 winbase.h 標頭取得函式宣告。 您也需要來自最新 SDK 的連結庫 （volatileaccessu.lib）。 不過，產生的二進位檔將會在舊版 Windows 上正常執行。

範例

UCHAR* CopyBuffer;

// In this scenario we are copying data from 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 mempcy, CopyMemory,
// and even CopyVolatileMemory may perform unaligned memory accesses
// because it is typically faster to do this.
// To ensure only naturally aligned accesses happen, use CopyDeviceMemory.

CopyDeviceMemory(CopyBuffer, DeviceMemoryBuffer, 100);

需求

最低支援的用戶端： Windows 11 Insider Preview 組建 TBD

標頭： winbase.h （包括 Winbase.h）

核心模式連結庫： volatileaccessk.lib

使用者模式連結庫： volatileaccessu.lib

另請參閱