PBUILD_SCATTER_GATHER_LIST funzione di callback (wdm.h)

Articolo
02/27/2024

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)