PBUILD_SCATTER_GATHER_LIST_EX funzione di callback (wdm.h)

Articolo
02/27/2024

La routine BuildScatterGatherListEx 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

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [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]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

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 .

[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

Dimensione, 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 BuildScatterGatherListEx 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, ExecutionRoutine è facoltativo e può essere NULL. Se ExecutionRoutine è NULL, il chiamante può usare le risorse allocate da BuildScatterGatherListEx. 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] ScatterGatherBuffer

Puntatore a un buffer allocato dal chiamante in cui la routine scrive l'elenco di dispersione/raccolta per il trasferimento DMA. Questo elenco inizia con una struttura SCATTER_GATHER_LIST , seguita da una matrice SCATTER_GATHER_ELEMENT .

[in] ScatterGatherLength

Dimensione, in byte, del buffer passato nel parametro ScatterGatherBuffer . La dimensione del buffer allocata deve essere sufficientemente grande da contenere l'elenco di dispersione/raccolta, oltre ai dati interni archiviati dal sistema operativo in questo buffer. Per calcolare le dimensioni del buffer necessarie, chiamare la routine GetDmaTransferInfo o CalculateScatterGatherList .

[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 di dispersione/raccolta per il trasferimento DMA. Questo elenco inizia con una struttura SCATTER_GATHER_LIST , che contiene un puntatore a una matrice di SCATTER_GATHER_ELEMENT . Questo puntatore di output corrisponde sempre al valore del parametro ScatterGatherBuffer .

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 BuildScatterGatherListEx 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

BuildScatterGatherListEx 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_BUFFER_TOO_SMALL	Il buffer fornito dal chiamante in ScatterGatherBuffer è troppo piccolo per contenere l'elenco di dispersione/raccolta.
STATUS_INSUFFICIENT_RESOURCES	La routine non è riuscita ad allocare le risorse necessarie per il trasferimento DMA.

Commenti

BuildScatterGatherListEx* 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 BuildScatterGatherListEx solo per gli adattatori bus-master. Non utilizzare questa routine per un adattatore DMA di sistema.

BuildScatterGatherListEx è simile alla routine GetScatterGatherListEx , ad eccezione del fatto che richiede al chiamante di allocare il buffer per l'elenco a dispersione/raccolta.

Ad esempio, un driver potrebbe preallocare uno o più buffer a dispersione/raccolta durante l'inizializzazione del dispositivo. Successivamente, una chiamata BuildScatterGatherListEx che usa tale buffer può avere esito positivo in condizioni di disponibilità di memoria insufficiente che potrebbero causare l'esito negativo di una chiamata GetScatterGatherListEx .

Per impostazione predefinita, BuildScatterGatherListEx 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 DMA_SYNCHRONOUS_CALLBACK , la routine BuildScatterGatherListEx si comporta come segue:

Se le risorse richieste non sono immediatamente disponibili, BuildScatterGatherListEx non attende le risorse, non compila un elenco a dispersione/raccolta e non chiama la routine AdapterListControl . Al contrario, BuildScatterGatherListEx ha 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 BuildScatterGatherListEx restituisca.
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 BuildScatterGatherListEx . In questo caso, il driver deve fornire un puntatore ScatterGatherList valido e non NULL. Inoltre, al termine del trasferimento DMA avviato dal driver, il driver deve chiamare la routine FreeAdapterObject per liberare le risorse allocate da BuildScatterGatherListEx per l'oggetto adapter.

BuildScatterGatherListEx è una versione estesa della routine BuildScatterGatherList . L'elenco seguente riepiloga le funzionalità disponibili solo nella versione estesa:

Funzionalità	Descrizione
Offset iniziale	Il driver chiamante può specificare un offset iniziale per un trasferimento DMA a dispersione/raccolta anziché avviare il trasferimento al primo indirizzo del buffer all'inizio della catena MDL.
Annullamento della richiesta di allocazione	Il driver può chiamare CancelAdapterChannel per annullare una richiesta di allocazione in sospeso quando l'adapter DMA è in coda per attendere le risorse DMA.
Callback sincrono	Il driver può impostare il flag di DMA_SYNCHRONOUS_CALLBACK per richiedere che la routine AdapterListControl fornita dal driver venga chiamata nel thread chiamante, prima che BuildScatterGatherListEx restituisca.

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