PCREATE_COMMON_BUFFER_FROM_MDL Rückruffunktion (wdm.h)

Artikel
08/08/2023

Die CreateCommonBufferFromMdl-Routine versucht, einen gemeinsamen Puffer aus einer MDL zu erstellen, indem sie die Gerätezugriffskompatibilität testet und den Speicher je nach Übersetzungstyp einem zusammenhängenden logischen Bereich zuordnen kann. Wie alle anderen gängigen Pufferzuordnungsfunktionen 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 für die Lebensdauer des allgemeinen Puffers immer 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 MmBuildMdlForNonPagedPool erstellt.
Die MDL wurde über MmProbeAndLockPages gesperrt und dem Systemraum über MmGetSystemAddressForMdlSafe zugeordnet.
Die physischen Seiten für die MDL wurden über MmAllocatePagesForMdlEx zugeordnet und dem Systemraum über MmGetSystemAddressForMdlSafe zugeordnet.
Die MDL muss eine seitenorientierte Region darstellen und ein Vielfaches von PAGE_SIZE sein.
- Wenn die erweiterte SubSection-Konfiguration verwendet wird, muss der Teil der verwendeten MDL seitenbündig 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, aber der Teil der verwendeten MDL muss in einer einzelnen MDL in der Kette enthalten sein.
Wenn DMA Remapping nicht verwendet wird, muss die MDL physisch zusammenhängenden Arbeitsspeicher 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

Gibt die Anzahl der erweiterten Konfigurationen im Array ExtendedConfigs an.

[out] LogicalAddress

Bei Erfolg gibt die logische Adresse des resultierenden gemeinsamen Puffers an.

Rückgabewert

CreateCommonBufferFromMdl gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte umfassen die folgenden status-Codes.

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 auf dem aktuellen System nicht unterstützt wird.
STATUS_INSUFFICIENT_RESOURCES	Das System verfügt nicht über genügend Arbeitsspeicher, um Metadaten zur Buchführung und Zuordnung zu erstellen.

Hinweise

CreateCommonBufferFromMdl ist keine Systemroutine, die direkt mit dem Namen aufgerufen werden kann. Diese Routine kann nur durch zeiger von der Adresse aufgerufen werden, die in einer DMA_OPERATIONS-Struktur zurückgegeben wird. Treiber erhalten die Adresse dieser Routine, indem sie IoGetDmaAdapter aufrufen, wobei das Versionselement des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

Ein allgemeiner Puffer, der von CreateCommonBufferFromMdl erstellt wurde, wird über FreeCommonBuffer entfernt. 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 Seiten verantwortlich.

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