PBUILD_SCATTER_GATHER_LIST funzione di callback (wdm.h)
La routine BuildScatterGatherList prepara il sistema per un'operazione DMA, usando un buffer fornito dal driver per compilare l'elenco a dispersione/raccolta.
Sintassi
PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;
NTSTATUS PbuildScatterGatherList(
[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,
[in] PVOID ScatterGatherBuffer,
[in] ULONG ScatterGatherLength
)
{...}
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 specificato dal MdlAddress membro dell'IRP corrente.
[in] CurrentVa
Puntatore all'indirizzo virtuale corrente nel file MDL per il mapping del buffer per un'operazione di trasferimento DMA.
[in] Length
Specifica la lunghezza, in byte, del buffer di cui eseguire il mapping.
[in] ExecutionRoutine
Puntatore a una routine AdapterListControl fornita dal driver, chiamata in IRQL = DISPATCH_LEVEL quando è disponibile il controller DMA di sistema o l'adattatore bus-master.
[in] Context
Puntatore al contesto determinato dal driver passato a ExecutionRoutine quando viene chiamato.
[in] WriteToDevice
Indica la direzione del trasferimento DMA: TRUE per un trasferimento dal buffer al dispositivo e false in caso contrario.
[in] ScatterGatherBuffer
Puntatore al buffer fornito dal chiamante che la routine riempie con una struttura SCATTER_GATHER_LIST.
[in] ScatterGatherLength
Specifica le dimensioni, in byte, del buffer passato nel parametro ScatterGatherBuffer.
Valore restituito
BuildScatterGatherList restituisce uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
| STATUS_SUCCESS | L'operazione viene completata correttamente. |
| STATUS_INSUFFICIENT_RESOURCES | Il sistema non dispone di registri mappa sufficienti disponibili per il trasferimento. |
| STATUS_BUFFER_TOO_SMALL | La lunghezza specificata è troppo grande per rientrare nel buffer. |
Osservazioni
BuildScatterGatherList 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_VERSION2. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.
BuildScatterGatherList esegue la stessa operazione di GetScatterGatherList, ad eccezione del fatto che usa il buffer fornito nel parametro ScatterGatherBuffer per contenere l'elenco a dispersione/raccolta creato. Al contrario, GetScatterGatherList alloca dinamicamente un buffer per contenere l'elenco a dispersione/raccolta. Se la memoria insufficiente è disponibile per allocare il buffer, GetScatterGatherList può non riuscire con un errore di STATUS_INSUFFICIENT_RESOURCES. I driver che devono evitare questo scenario possono preallocare un buffer per contenere l'elenco a dispersione/raccolta e usare BuildScatterGatherList.
Un driver può usare la routine CalculateScatterGatherList per determinare le dimensioni del buffer da allocare per contenere l'elenco a dispersione/raccolta.
Il driver deve mantenere il puntatore all'elenco a dispersione/raccolta in ScatterGatherBuffer da usare quando il driver chiama PutScatterGatherList. Il driver deve chiamare PutScatterGatherList (che scarica l'elenco) prima di poter accedere ai dati nell'elenco.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Disponibile in Windows XP e versioni successive di Windows. |
| piattaforma di destinazione | Desktop |
| intestazione | wdm.h (include Wdm.h) |
| IRQL | DISPATCH_LEVEL |
| regole di conformità DDI | irqlDispatch(wdm) |