PINITIALIZE_DMA_TRANSFER_CONTEXT funzione di callback (wdm.h)

Articolo
02/29/2024

La routine InitializeDmaTransferContext inizializza un contesto di trasferimento DMA opaco usato per tenere traccia delle allocazioni in sospeso delle risorse DMA.

Sintassi

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

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

Parametri

[in] DmaAdapter

Puntatore a una struttura DMA_ADAPTER . Questa struttura è l'oggetto adapter che rappresenta il dispositivo DMA master del driver o il canale DMA del sistema. Il chiamante ha ottenuto questo puntatore da una chiamata precedente alla routine IoGetDmaAdapter .

[out] DmaTransferContext

Puntatore a un buffer allocato dal chiamante in cui InitializeDmaTransferContext scrive i valori iniziali per il contesto di trasferimento DMA. Questo contesto è opaco al chiamante. Il chiamante deve allocare un buffer sufficiente per contenere il contesto di trasferimento DMA. Le dimensioni, in byte, di questo contesto vengono specificate dalla costante DMA_TRANSFER_CONTEXT_SIZE_V1 nel file di intestazione Wdm.h.

Valore restituito

InitializeDmaTransferContext restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti degli errori possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_INVALID_PARAMETERS	Questa routine non è riuscita a causa di valori di parametro non validi passati dal chiamante.

Commenti

InitializeDmaTransferContext non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine può essere chiamata solo dal puntatore dall'indirizzo restituito in una struttura DMA_OPERATIONS. I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro Version del parametro DeviceDescription impostato su DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.

Un contesto di trasferimento DMA inizializzato deve essere fornito come parametro alla routine AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx. Ognuna di queste routine scrive informazioni sull'allocazione delle risorse DMA richiesta nel contesto di trasferimento DMA. Queste informazioni sono opache per il chiamante. Per annullare una richiesta di allocazione in sospeso, il chiamante deve fornire il contesto di trasferimento DMA per la richiesta alla routine CancelAdapterChannel .

Il contesto di trasferimento DMA fornito a AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx deve essere univoco in tutte le richieste di allocazione della scheda.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL