PINITIALIZE_DMA_TRANSFER_CONTEXT Rückruffunktion (wdm.h)

Artikel
02/29/2024

Die InitializeDmaTransferContext-Routine initialisiert einen undurchsichtigen DMA-Übertragungskontext, der zum Nachverfolgen ausstehender Zuordnungen von DMA-Ressourcen verwendet wird.

Syntax

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

NTSTATUS PinitializeDmaTransferContext(
  [in]  PDMA_ADAPTER DmaAdapter,
  [out] PVOID DmaTransferContext
)
{...}

Parameter

[in] DmaAdapter

Ein Zeiger auf eine DMA_ADAPTER-Struktur . Diese Struktur ist das Adapterobjekt, das den Bus-master DMA-Gerät oder System-DMA-Kanal des Treibers darstellt. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf der IoGetDmaAdapter-Routine abgerufen.

[out] DmaTransferContext

Ein Zeiger auf einen vom Aufrufer zugeordneten Puffer, in den InitializeDmaTransferContext die Anfangswerte für den DMA-Übertragungskontext schreibt. Dieser Kontext ist für den Aufrufer undurchsichtig. Der Aufrufer muss einen Puffer zuordnen, der groß genug ist, um den DMA-Übertragungskontext zu enthalten. Die Größe dieses Kontexts in Bytes wird durch die DMA_TRANSFER_CONTEXT_SIZE_V1 Konstante in der Wdm.h-Headerdatei angegeben.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETERS	Fehler bei dieser Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben wurden.

Hinweise

InitializeDmaTransferContext ist keine Systemroutine, die direkt nach Namen aufgerufen werden kann. Diese Routine kann nur durch den 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 der Version-Member des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

Ein initialisierter DMA-Übertragungskontext muss als Parameter für die Routinen AllocateAdapterChannelEx, GetScatterGatherListEx oder BuildScatterGatherListEx bereitgestellt werden. Jede dieser Routinen schreibt Informationen zur angeforderten DMA-Ressourcenzuordnung in den DMA-Übertragungskontext. Diese Informationen sind für den Aufrufer undurchsichtig. Um eine ausstehende Zuordnungsanforderung abzubrechen, muss der Aufrufer den DMA-Übertragungskontext für die Anforderung an die CancelAdapterChannel-Routine angeben.

Der DMA-Übertragungskontext, der für AllocateAdapterChannelEx, GetScatterGatherListEx oder BuildScatterGatherListEx bereitgestellt wird, muss für alle Adapterzuordnungsanforderungen eindeutig sein.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL