PBUILD_SCATTER_GATHER_LIST_EX funzione di callback (wdm.h)

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

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

Dimensione, 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:

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 null valido 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, 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 di SCATTER_GATHER_ELEMENT.

[in] ScatterGatherLength

Dimensione, in byte, del buffer passato nel parametro ScatterGatherBuffer. Le dimensioni del buffer allocate devono essere sufficienti per contenere l'elenco a dispersione/raccolta, oltre ai dati interni archiviati nel buffer dal sistema operativo. Per calcolare le dimensioni del buffer necessarie, chiamare la routine GetDmaTransferInfo o CalculateScatterGatherList.

[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 nell'elenco a 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 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 BuildScatterGatherListEx se il flag di DMA_SYNCHRONOUS_CALLBACK è impostato e ScatterGatherList e ExecutionRoutine sono entrambi nulloppure se il flag di 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.

Osservazioni

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 diDMA_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 le schede bus-master. Non utilizzare questa routine per un adattatore DMA di sistema.

BuildScatterGatherListEx è simile alla routine GetScatterGatherListEx , con la differenza 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 un errore di GetScatterGatherListEx chiamata.

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

• Se le risorse richieste non sono immediatamente disponibili, BuildScatterGatherListEx non attende le risorse, non crea 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 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 che BuildScatterGatherListEx restituisce. In questo caso, il driver deve fornire un puntatoreNULLScatterGatherList valido. Inoltre, al termine del trasferimento DMA avviato dal driver, il driver deve chiamare la routine FreeAdapterObject per liberare le risorse che BuildScatterGatherListEx allocate per l'oggetto adapter.

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

Fabbisogno

Vedere anche

AdapterListControl

AllocateAdapterChannelEx

CalculateScatterGatherList

DMA_OPERATIONS

DmaCompletionRoutine

FreeAdapterObject

GetScatterGatherList

GetScatterGatherListEx

MapTransferEx