PGET_SCATTER_GATHER_LIST funzione di callback (wdm.h)
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 |
|---|---|
|
Operazione completata. |
|
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. |
|
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) |