CopyDeviceMemory-Funktion

Artikel
01/30/2024

Die CopyDeviceMemory-Funktion kopiert Speicher von einem Speicherort an einen anderen ohne Störungen von Compileroptimierungen in Situationen, in denen Entwickler*innen zusätzlich sicherstellen müssen, dass beim Zugriff auf Gerätespeicher keine Ausrichtungsfehler generiert werden.

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor der kommerziellen Freigabe grundlegend geändert werden können. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Parameter

Parameterziel [out]

Ein Zeiger auf die Startadresse am Ziel des kopierten Blocks.

Parameterquelle [in]

Ein Verweis auf die Startadresse des Speicherblocks, der kopiert werden soll

Parameterlänge [in]

Die Größe des zu kopierenden Speicherblocks in Byte.

Syntax

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

Hinweise

Diese API soll das Verhalten von CopyVolatileMemory (d. h. das Kopieren des Speichers von einem Speicherort an einen anderen ohne Störungen von Compileroptimierungen) in Situationen bereitstellen, in denen Entwickler*innen zusätzlich sicherstellen müssen, dass beim Zugriff auf den Gerätespeicher keine Ausrichtungsfehler generiert werden. Die API verfügt über die folgenden Eigenschaften:

Die API wird nicht als systeminterner Compiler erkannt, wodurch der Aufruf niemals durch Optimierungen des Compilers entfernt wird, die den Aufruf vollständig entfernen oder mit einer equivalent-Anweisungssequenz ersetzen würden. Dies ist ein Unterschied zu CopyMemory, das einer Vielzahl von Compileroptimierungen unterliegt.
Wenn der Aufruf zurückgegeben wird, wurden die Daten aus der Quelle in das Ziel kopiert. Der Speicherzugriff dieser Funktion auf die Quelle und das Ziel gilt nur innerhalb der Funktion (d. h., der Compiler kann Speicherzugriffe nicht aus dieser Funktion verschieben).
Die API führt möglicherweise nur dann nicht ausgerichtete Zugriffe auf den Arbeitsspeicher aus, wenn die CPU diese auf dem Gerätespeicher unterstützt. Wenn die CPU keine nicht ausgerichtete Zugriffe auf den Gerätespeicher unterstützt, werden lediglich ausgerichtete Zugriffe ausgeführt.
Die API kann im Rahmen des Kopiervorgangs mehrmals auf Speicherspeicherorte zugreifen.
Sie unterstützt keine Kopiervorgänge, wenn Quelle und Ziel sich gegenseitig überlappen. Wenn überlappende Puffer angegeben werden, tritt schnell der Fehlercode FAST_FAIL_INVALID_ARG auf.

Hinweis

Diese Funktion garantiert lediglich, dass die CPU-Anforderungen für den Zugriff auf den als Gerätespeicher zugeordneten Arbeitsspeicher eingehalten werden. Wenn ein bestimmtes Gerät über eigene spezifische Anforderungen für den Zugriff verfügt, sollte diese Funktion nicht verwendet werden. Stattdessen müssen Entwickler*innen eigene Accessorfunktionen implementieren. Beispielsweise garantiert diese Funktion nicht die Größe des Arbeitsspeichers, der durch Zugriffe erzeugt wurde – es sei denn, die CPU selbst erzwingt diese Anforderungen.

Hinweis

Diese Funktion funktioniert nicht nur unter der neuesten Windows-Version, sondern unter allen Versionen. Sie müssen das neueste SDK verwenden, um die Funktionsdeklaration aus dem winbase.h-Header abzurufen. Außerdem benötigen Sie die Bibliothek (volatileaccessu.lib) aus dem neuesten SDK. Die resultierende Binärdatei wird jedoch in älteren Versionen von Windows problemlos ausgeführt.

Beispiel

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);

Anforderungen

Unterstützte Mindestversion (Client): Windows 11 Insider Preview Build TBD

Header: winbase.h (Winbase.h eingeschlossen)

Kernelmodusbibliothek: volatileaccessk.lib

Benutzermodusbibliothek: volatileaccessu.lib

Share via