FillDeviceMemory-Funktion

Artikel
02/02/2024

Die FillDeviceMemory-Funktion legt den Inhalt eines Puffers ohne Störungen durch Compileroptimierungen in Situationen fest, in denen Entwickler*innen zusätzlich sicherstellen müssen, dass beim Zugriff auf den Gerätespeicher keine Ausrichtungsfehler erzeugt 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

Param Destination [out]

Ein Verweis auf die Startadresse des Speicherblocks, der gefüllt werden soll

Param Length [in]

Die Bytegröße des Speicherblocks, der gefüllt werden soll. Dieser Wert muss kleiner als die Größe des Destination-Puffers sein.

Param Fill [in]

Der Bytewert, mit dem der Speicherblock gefüllt werden soll

Syntax

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

Hinweise

Diese API ist vorhanden, um das FillVolatileMemory-Verhalten bereitzustellen, bei dem der Inhalt eines Puffers ohne Störungen durch Compileroptimierungen festgelegt wird. Dieses Verhalten wird in Situationen bereitgestellt, in denen Entwickler*innen zusätzlich sicherstellen müssen, dass beim Zugriff auf den Gerätespeicher keine Ausrichtungsfehler erzeugt 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. Das unterscheidet sich vom FillMemory-Verhalten, das einer Vielzahl von Compileroptimierungen unterliegt.
Wenn der Aufruf abgeschlossen ist, wurde der Puffer mit dem gewünschten Wert überschrieben. Dieser Zugriff des Funktionsarbeitsspeichers auf den Destination-Puffer wird ausschließlich innerhalb der Funktion ausgeführt, wobei der Compiler den Arbeitsspeicherzugriff nicht aus dieser Funktion verschieben kann.
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 nicht ausgerichtete Zugriffe auf den Gerätespeicher nicht unterstützt, werden lediglich ausgerichtete Zugriffe ausgeführt.
Die API greift als Teil ihrer Ausführung möglicherweise mehr als einmal auf Speicherorte im Arbeitsspeicher zu.

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 keine Größe des Arbeitsspeichers, der durch Zugriffe erzeugt wurde – es sei denn, die CPU selbst erzwingt diese Anforderungen.

Hinweis

Diese Funktion funktioniert nicht nur auf der neuesten Windows-Version, sondern auf 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

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

Anforderungen

Unterstützte Mindestversion (Client): Windows 11 Insider-Vorabversion TBD

Header: winbase.h (Winbase.h eingeschlossen)

Kernelmodusbibliothek: volatileaccessk.lib

Benutzermodusbibliothek: volatileaccessu.lib

Share via