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 di 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 master del bus o il controller DMA.
[in] DeviceObject
Puntatore all'oggetto dispositivo che rappresenta il dispositivo di destinazione per l'operazione DMA.
[in] Mdl
Puntatore al MDL che descrive il buffer specificato dal membro MdlAddress dell'IRP corrente.
[in] CurrentVa
Puntatore all'indirizzo virtuale corrente in MDL per il mapping del buffer per un'operazione di trasferimento DMA.
[in] Length
Specifica la lunghezza, in byte, del buffer da eseguire il mapping.
[in] ExecutionRoutine
Puntatore a una routine AdapterListControl fornita dal driver, denominata IRQL = DISPATCH_LEVEL quando è disponibile il controller DMA di sistema o la scheda master del bus.
[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 dispone di registri mappa insufficienti disponibili per il trasferimento. |
STATUS_BUFFER_TOO_SMALL | La lunghezza specificata è troppo grande da adattare all'interno del buffer. |
Commenti
BuildScatterGatherList non è una routine di sistema che può essere chiamata direttamente in base al 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 di dispersione/raccolta creato. Al contrario, GetScatterGatherList alloca dinamicamente un buffer per contenere l'elenco di 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 di dispersione/raccolta e usare BuildScatterGatherList .
Un driver può usare la routine CalculateScatterGatherList per determinare la dimensione del buffer da allocare per contenere l'elenco di dispersione/raccolta.
Il driver deve mantenere il puntatore all'elenco di 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.
Requisiti
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) |