PCREATE_COMMON_BUFFER_FROM_MDL Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die CreateCommonBufferFromMdl-Routine versucht, einen allgemeinen Puffer aus einer MDL zu erstellen, indem sie die Kompatibilität des Gerätezugriffs testen und den Speicher je nach Übersetzungstyp potenziell einem zusammenhängenden logischen Bereich zuordnen. Wie alle anderen gängigen Pufferzuweisungsfunktionen bietet diese Funktion keine Vorwärtsstatusgarantie.

Syntax

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Parameter

[in] DmaAdapter

Stellt einen Zeiger auf den DMA-Adapter bereit, der den Vorgang ausführt.

[in] Mdl

Stellt die MDL bereit, die einem allgemeinen Puffer zugeordnet wird.

Damit eine MDL einen allgemeinen Puffer sichern kann, müssen die folgenden Bedingungen erfüllt sein:

Die MDL muss Über Seiten verfügen, die immer für die Lebensdauer des allgemeinen Puffers vorhanden sind und dem Systemadressraum zugeordnet sind. Dies kann durch die folgenden Ansätze erreicht werden:
Die MDL wird aus einem Puffer im nicht ausgelagerten Pool über MmBuildMdlForNonPagedPoolerstellt.
Die MDL wurde über MmProbeAndLockPages gesperrt und über MmGetSystemAddressForMdlSafedem Systembereich zugeordnet.
Die physischen Seiten für die MDL wurden über MmAllocatePagesForMdlEx zugewiesen und über MmGetSystemAddressForMdlSafesystem space zugeordnet.
Die MDL muss einen seitenbündigen Bereich darstellen und ein Vielfaches von PAGE_SIZE sein.
- Wenn die erweiterte SubSection-Konfiguration verwendet wird, muss der verwendete MDL-Teil seitenausgeglichen sein und ein Vielfaches von PAGE_SIZE sein.
Die MDL darf keine verkettete MDL sein.
- Wenn die erweiterte SubSection-Konfiguration verwendet wird, kann eine verkettete MDL bereitgestellt werden, der verwendete MDL-Teil muss jedoch in einer einzelnen MDL in der Kette enthalten sein.
Wenn DMA Remapping nicht verwendet wird, muss die MDL physisch zusammenhängenden Speicher darstellen und für das Gerät zugänglich sein.

[in] ExtendedConfigs

Stellt ein optionales Array von DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION Strukturen bereit, um die Erstellung des gemeinsamen MDL-Puffers weiter zu konfigurieren.

Wenn mehrere Konfigurationen desselben DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE im Array bereitgestellt werden, schlägt die Erstellung fehl.

[in] ExtendedConfigsCount

Stellt die Anzahl erweiterter Konfigurationen im ExtendedConfigs Array bereit.

[out] LogicalAddress

Bei Erfolg wird die logische Adresse des resultierenden allgemeinen Puffers bereitgestellt.

Rückgabewert

CreateCommonBufferFromMdlSTATUS_SUCCESS zurückgeben, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind die folgenden Statuscodes.

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Der Aufrufer hat eine inkompatible MDL- oder erweiterte Konfiguration bereitgestellt.
STATUS_NOT_SUPPORTED	Der Aufrufer hat eine erweiterte Konfiguration bereitgestellt, die im aktuellen System nicht unterstützt wird.
STATUS_INSUFFICIENT_RESOURCES	Das System verfügt nicht über genügend Arbeitsspeicher, um Buchführungs- und Zuordnungsmetadaten zu erstellen.

Bemerkungen

CreateCommonBufferFromMdl ist keine Systemroutine, die direkt anhand des Namens aufgerufen werden kann. Diese Routine kann nur durch Zeiger von der in einer DMA_OPERATIONS Struktur zurückgegebenen Adresse aufgerufen werden. Treiber rufen die Adresse dieser Routine ab, indem sie IoGetDmaAdapter- mit dem Version Mitglied des DeviceDescription- Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt wird. Wenn IoGetDmaAdapterNULL-zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

Ein allgemeiner Puffer, der von CreateCommonBufferFromMdl erstellt wird, wird über FreeCommonBufferentfernt. Der Aufrufer muss die virtuelle Systemadresse als virtuelle Adresse angeben, um sicherzustellen, dass der allgemeine Puffer ordnungsgemäß aus den allgemeinen Pufferbuchhaltungsstrukturen des Adapters entfernt wird. Der Treiber ist weiterhin für das Entsperren und Freigeben der MDL und der zugehörigen Sicherungsseiten verantwortlich.

Verwenden Sie AllocateCommonBufferWithBounds, um einen gemeinsamen Puffer zu erstellen, in dem die HAL für die Aufrechterhaltung des Sicherungsspeichers verantwortlich ist.