PGET_SCATTER_GATHER_LIST_EX funzione di callback (wdm.h)

Articolo
02/29/2024

La routine GetScatterGatherListEx alloca le risorse necessarie per un trasferimento DMA, compila un elenco di dispersione/raccolta e chiama la routine AdapterListControl fornita dal driver per avviare il trasferimento DMA.

Attenzione

Non chiamare questa routine per un dispositivo DMA di sistema.

Sintassi

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

Parametri

[in] DmaAdapter

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

[in] DeviceObject

Puntatore a una struttura DEVICE_OBJECT . Questa struttura è l'oggetto dispositivo fisico (PDO) che rappresenta il dispositivo di destinazione per l'operazione DMA richiesta.

[in] DmaTransferContext

Puntatore a un contesto di trasferimento DMA inizializzato. Questo contesto è stato inizializzato da una chiamata precedente alla routine InitializeDmaTransferContext . Questo contesto deve essere univoco in tutte le richieste di allocazione degli adattatori. Per annullare una richiesta di allocazione in sospeso, il chiamante deve fornire il contesto di trasferimento DMA per la richiesta alla routine CancelAdapterChannel .

[in] Mdl

Puntatore a una catena MDL che descrive il layout di pagina fisico per una raccolta di buffer bloccati in memoria virtuale. L'elenco di dispersione/raccolta per il trasferimento DMA userà l'area di questa memoria specificata dai parametri Offset e Length . Per altre informazioni sulle catene MDL, vedere Using MDLs.For more information about MDL chain, see Using MDLs.

[in] Offset

Offset iniziale per il trasferimento DMA a dispersione/raccolta. Questo parametro è un offset di byte dall'inizio del buffer nel primo MDL nella catena MDL. Se gli ELENCHI DI certificati nella catena MDL specificano un totale di N byte di spazio buffer, i valori validi di Offset sono compresi nell'intervallo da 0 a N-1.

[in] Length

Lunghezza, in byte, del trasferimento DMA. Se la catena MDL specifica un totale di N byte di spazio buffer, i valori validi di Length sono compresi nell'intervallo da 1 a N-Offset.

[in] Flags

Flag di allocazione del canale dell'adattatore. È supportato il flag seguente:

Contrassegno	Significato
DMA_SYNCHRONOUS_CALLBACK	La routine GetScatterGatherListEx viene chiamata in modo sincrono. Se questo flag è impostato e le risorse DMA necessarie non sono immediatamente disponibili, la chiamata ha esito negativo e restituisce STATUS_INSUFFICIENT_RESOURCES.

Se il flag DMA_SYNCHRONOUS_CALLBACK è impostato, il parametro ExecutionRoutine è facoltativo e può essere NULL. Se questo flag non è impostato, ExecutionRoutine deve essere un puntatore non NULL valido. Per altre informazioni su questo flag, vedere la sezione Osservazioni.

[in, optional] ExecutionRoutine

Puntatore alla routine AdapterListControl fornita dal driver che avvia il trasferimento DMA per il driver. La gestione I/O chiama la routine AdapterListControl dopo l'allocazione delle risorse necessarie per l'oggetto adapter. Al termine della routine AdapterListControl , il gestore di I/O libera automaticamente l'oggetto adapter e le risorse allocate per questo oggetto.

Se il flag DMA_SYNCHRONOUS_CALLBACK è impostato, il parametro ExecutionRoutine è facoltativo e può essere NULL. Se questo parametro è NULL, il chiamante può usare le risorse allocate da GetScatterGatherListEx per eseguire il trasferimento DMA dopo la restituzione di GetScatterGatherListEx . Per altre informazioni, vedere la sezione Osservazioni.

[in, optional] Context

Contesto di controllo dell'adattatore determinato dal driver. Questo contesto viene passato alla routine AdapterListControl come parametro Context .

[in] WriteToDevice

Direzione del trasferimento DMA. Impostare questo parametro su TRUE per un'operazione di scrittura, che trasferisce i dati dalla memoria al dispositivo. Impostare questo parametro su FALSE per un'operazione di lettura, che trasferisce i dati dal dispositivo alla memoria.

[in, optional] DmaCompletionRoutine

Non usato. Impostare su NULL.

[in, optional] CompletionContext

Non usato. Impostare su NULL.

[out, optional] ScatterGatherList

Puntatore a una variabile in cui la routine scrive un puntatore nell'elenco a dispersione/raccolta allocato. Questo parametro punta a una struttura SCATTER_GATHER_LIST . La routine alloca questa struttura e la matrice SCATTER_GATHER_ELEMENT a cui punta.

Il parametro ScatterGatherList è facoltativo e può essere NULL se il parametro ExecutionRoutine è diverso da NULL.

Se il flag DMA_SYNCHRONOUS_CALLBACK è impostato e il parametro ExecutionRoutine è NULL, ScatterGatherList deve essere un puntatore non NULL valido. Se ExecutionRoutine non è NULL, ScatterGatherList è facoltativo e può essere NULL se il driver chiamante non richiede l'elenco di dispersione/raccolta. La chiamata GetScatterGatherListEx ha esito negativo se il flag DMA_SYNCHRONOUS_CALLBACK è impostato e ScatterGatherList e ExecutionRoutine sono entrambi NULL oppure se il flag DMA_SYNCHRONOUS_CALLBACK non è impostato e ExecutionRoutine è NULL.

Valore restituito

GetScatterGatherListEx restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono i codici di stato seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETERS	La routine non è riuscita a causa di valori di parametro non validi passati dal chiamante.
STATUS_INSUFFICIENT_RESOURCES	La routine non è riuscita ad allocare le risorse necessarie per il trasferimento DMA.

Commenti

GetScatterGatherListEx 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.

Usare GetScatterGatherListEx solo per gli adapter bus-master. Non utilizzare questa routine per un adattatore DMA di sistema.

Il driver di un dispositivo master del bus può usare GetScatterGatherListEx per combinare le operazioni eseguite dalle routine AllocateAdapterChannelEx e MapTransferEx in una sola chiamata. GetScatterGatherListEx esegue le operazioni seguenti:

Alloca le risorse necessarie per il trasferimento DMA.
Crea un elenco a dispersione/raccolta in base ai valori dei parametri Mdl, Offset e Length .
Chiama la routine AdapterListControl fornita dal driver e fornisce l'elenco di dispersione/raccolta a questa routine come parametro.

Le risorse allocate vengono rilasciate automaticamente dopo la restituzione della routine AdapterListControl . Se GetScatterGatherListEx viene chiamato in modo sincrono, ovvero se è impostato il flag di DMA_SYNCHRONOUS_CALLBACK , è possibile omettere la routine AdapterListControl . In questo caso, il chiamante usa le risorse allocate per avviare il trasferimento DMA dopo la restituzione di GetScatterGatherListEx . Il chiamante deve rilasciare in modo esplicito queste risorse.

Per impostazione predefinita, GetScatterGatherListEx restituisce in modo asincrono, senza attendere il completamento dell'allocazione delle risorse richiesta. Dopo questa restituzione, il chiamante può, se necessario, annullare la richiesta di allocazione in sospeso chiamando la routine CancelAdapterChannel .

Se il driver chiamante imposta il flag di DMA_SYNCHRONOUS_CALLBACK , la routine GetScatterGatherListEx si comporta come segue:

Se le risorse richieste non sono immediatamente disponibili, GetScatterGatherListEx non attende le risorse, non compila un elenco a dispersione/raccolta e non chiama la routine AdapterListControl . GetScatterGatherListEx ha invece esito negativo e restituisce STATUS_INSUFFICIENT_RESOURCES.
Il driver non è necessario per fornire una routine AdapterListControl se è impostato il flag di DMA_SYNCHRONOUS_CALLBACK .
Se il driver fornisce una routine AdapterListControl , il flag DMA_SYNCHRONOUS_CALLBACK indica che questa routine deve essere chiamata nel contesto del thread chiamante, prima che Venga restituito GetScatterGatherListEx .
Se il driver non fornisce una routine AdapterListControl , il driver può usare le risorse allocate e l'elenco di dispersione/raccolta dopo la restituzione di GetScatterGatherListEx . In questo caso, il driver deve fornire un puntatore ScatterGatherList valido e non NULL. Inoltre, dopo che il driver avvia il trasferimento DMA, il driver deve chiamare la routine FreeAdapterObject per liberare le risorse allocate da GetScatterGatherListEx per l'oggetto adapter.

GetScatterGatherListEx è una versione estesa della routine GetScatterGatherList . Le funzionalità seguenti sono disponibili solo nella versione estesa:

GetScatterGatherListEx è simile alla routine BuildScatterGatherListEx , ad eccezione del fatto che GetScatterGatherListEx alloca automaticamente il buffer per l'elenco a dispersione/raccolta.

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