PGET_SCATTER_GATHER_LIST_EX funzione di callback (wdm.h)

Articolo
02/07/2025

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

Cautela

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 a dispersione/raccolta per il trasferimento DMA userà l'area di questa memoria specificata dai parametri offset e Lunghezza. Per altre informazioni sulle catene MDL, vedere Using MDLs.

[in] Offset

Offset iniziale per il trasferimento DMA a dispersione/raccolta. Questo parametro è un offset di byte dall'inizio del buffer nella prima MDL della catena MDL. Se gli mdls nella catena MDL specificano un totale di N byte di spazio buffer, i valori validi di offset sono compresi nell'intervallo compreso tra 0 e 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 Lunghezza sono compresi nell'intervallo da 1 a N-Offset.

[in] Flags

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

Bandiera	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 nullvalido e non. 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. Il gestore di 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 GetScatterGatherListEx restituisce. 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 utilizzato. Impostare su NULL.

[in, optional] CompletionContext

Non utilizzato. Impostare su NULL.

[out, optional] ScatterGatherList

Puntatore a una variabile in cui la routine scrive un puntatore all'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 di DMA_SYNCHRONOUS_CALLBACK è impostato e il parametro ExecutionRoutine è NULL, ScatterGatherList deve essere un puntatore 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 di DMA_SYNCHRONOUS_CALLBACK è impostato e ScatterGatherList e ExecutionRoutine sono entrambi NULLoppure se il flag DMA_SYNCHRONOUS_CALLBACK non è impostato e la 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.

Osservazioni

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 adattatori 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 dalla AllocateAdapterChannelEx e Routine MapTransferEx in una sola chiamata. GetScatterGatherListEx esegue le operazioni seguenti:

Alloca le risorse necessarie per il trasferimento DMA.
Compila un elenco a dispersione/raccolta in base ai valori dei parametri Mdl, Offsete Lunghezza.
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 che la routine AdapterListControl. Se getScatterGatherListEx viene chiamato in modo sincrono (ovvero se è impostato il flag DMA_SYNCHRONOUS_CALLBACK), è possibile omettere la routine AdapterListControl. In questo caso, il chiamante usa le risorse allocate per avviare il trasferimento DMA dopo che GetScatterGatherListEx restituisce. 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 questo risultato, il chiamante può, se necessario, annullare la richiesta di allocazione in sospeso chiamando la routine CancelAdapterChannel.

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

Se le risorse richieste non sono immediatamente disponibili, GetScatterGatherListEx non attende le risorse, non crea un elenco a dispersione/raccolta e non chiama la routine AdapterListControl. Al contrario, getScatterGatherListEx ha esito negativo e restituisce STATUS_INSUFFICIENT_RESOURCES.
Il driver non è necessario per fornire una routine AdapterListControl se è impostato il flag 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 restituita GetScatterGatherListEx.
Se il driver non fornisce una routine AdapterListControl, il driver può usare le risorse allocate e l'elenco di dispersione/raccolta dopo Restituisce GetScatterGatherListEx. In questo caso, il driver deve fornire un puntatore ScatterGatherList valido non NULL. Inoltre, dopo che il driver avvia il trasferimento DMA, il driver deve chiamare la routine FreeAdapterObject per liberare le risorse che GetScatterGatherListEx allocati 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.

Fabbisogno

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