PGET_SCATTER_GATHER_LIST funzione di callback (wdm.h)

Articolo
08/08/2023

La routine GetScatterGatherList prepara il sistema per un'operazione di dispersione/raccolta DMA per conto dell'oggetto dispositivo di destinazione, tramite il controller DMA di sistema o un adattatore master del bus.

Sintassi

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice
)
{...}

Parametri

[in] DmaAdapter

Puntatore alla struttura DMA_ADAPTER restituita da IoGetDmaAdapter che rappresenta l'adattatore bus-master o il controller DMA.

[in] DeviceObject

Puntatore all'oggetto dispositivo che rappresenta il dispositivo di destinazione per l'operazione DMA.

[in] Mdl

Puntatore al file MDL che descrive il buffer in MdlAddress nell'IRP corrente.

[in] CurrentVa

Puntatore all'indirizzo virtuale corrente in MDL per il buffer di cui eseguire il mapping per un'operazione di trasferimento DMA.

[in] Length

Specifica la lunghezza, in byte, di cui eseguire il mapping.

[in] ExecutionRoutine

Puntatore a una routine AdapterListControl fornita dal driver, che viene chiamata in DISPATCH_LEVEL quando è disponibile il controller DMA di sistema o l'adattatore bus-master.

[in] Context

Puntatore al contesto determinato dal driver passato alla routine AdapterListControl del driver quando viene chiamato.

[in] WriteToDevice

Indica la direzione del trasferimento DMA: TRUE per un trasferimento dal buffer al dispositivo e FALSE in caso contrario.

Valore restituito

Questa routine può restituire uno dei valori NTSTATUS seguenti.

Codice restituito	Descrizione
STATUS_SUCCESS	Operazione completata.
STATUS_INSUFFICIENT_RESOURCES	La routine non è in grado di allocare memoria sufficiente o il numero di registri mappa necessari per il trasferimento è maggiore del valore restituito da IoGetDmaAdapter.
STATUS_BUFFER_TOO_SMALL	Il buffer è troppo piccolo per il trasferimento richiesto.

Commenti

La routine GetScatterGatherList alloca dinamicamente un buffer per contenere l'elenco di dispersione/raccolta. Per i possibili valori NTSTATUS se l'allocazione del buffer ha esito negativo, vedere il valore restituito.

GetScatterGatherList non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine è chiamabile solo dal puntatore dall'indirizzo restituito in una struttura di DMA_OPERATIONS . I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter.

Non appena sono disponibili il canale DMA appropriato e tutti i registri delle mappe necessari, GetScatterGatherList crea un elenco di dispersione/raccolta, inizializza i registri della mappa e quindi chiama la routine AdapterListControl fornita dal driver per eseguire l'operazione di I/O.

GetScatterGatherList combina le azioni delle routine AllocateAdapterChannel e MapTransfer per i driver che eseguono DMA a dispersione/raccolta. GetScatterGatherList determina il numero di registri mappa necessari per il trasferimento, alloca i registri della mappa, esegue il mapping dei buffer per DMA e compila l'elenco a dispersione/raccolta. Chiama quindi la routine AdapterListControl fornita, passando un puntatore all'elenco di dispersione/raccolta in ScatterGather. Il driver deve mantenere questo puntatore da usare quando si chiama PutScatterGatherList. Si noti che GetScatterGatherList non dispone delle restrizioni di accodamento applicabili a AllocateAdapterChannel.

Nella routine AdapterListControl il driver deve eseguire l'I/O. Al ritorno dalla routine fornita dal driver, GetScatterGatherList mantiene i registri della mappa, ma libera la struttura dell'adattatore DMA. Il driver deve chiamare PutScatterGatherList (che scarica i buffer) prima di poter accedere ai dati nel buffer.

Questa routine può gestire gli ELENCHI MDL concatenati, a condizione che il numero totale di registri mappa richiesti da tutti gli ELENCHI mdl concatenati non superi il numero di registri mappa disponibili.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 2000 e versioni successive di Windows. Non supportato in Windows 98 o Windows Me.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
Regole di conformità DDI	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)