PBUILD_SCATTER_GATHER_LIST Rückruffunktion (wdm.h)
Die BuildScatterGatherList-Routine bereitet das System auf einen DMA-Vorgang vor, wobei ein vom Treiber bereitgestellter Puffer verwendet wird, um die Scatter/Gather-Liste zu erstellen.
Syntax
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
)
{...}
Parameter
[in] DmaAdapter
Zeiger auf die DMA_ADAPTER Struktur, die von IoGetDmaAdapter zurückgegeben wird und den Bus-master-Adapter oder DMA-Controller darstellt.
[in] DeviceObject
Zeiger auf das Geräteobjekt, das das Zielgerät für den DMA-Vorgang darstellt.
[in] Mdl
Zeiger auf die MDL, die den Puffer beschreibt, der vom MdlAddress-Member des aktuellen IRP angegeben wird.
[in] CurrentVa
Zeiger auf die aktuelle virtuelle Adresse in der MDL für den Puffer, der für einen DMA-Übertragungsvorgang zugeordnet werden soll.
[in] Length
Gibt die Länge des zuzuordnenden Puffers in Bytes an.
[in] ExecutionRoutine
Zeiger auf eine vom Treiber bereitgestellte AdapterListControl-Routine, die unter IRQL = DISPATCH_LEVEL aufgerufen wird, wenn der System-DMA-Controller oder der Bus-master-Adapter verfügbar ist.
[in] Context
Zeiger auf den vom Treiber bestimmten Kontext, der an ExecutionRoutine übergeben wird, wenn er aufgerufen wird.
[in] WriteToDevice
Gibt die Richtung der DMA-Übertragung an: TRUE für eine Übertragung vom Puffer zum Gerät, andernfalls FALSE .
[in] ScatterGatherBuffer
Zeiger auf den vom Aufrufer bereitgestellten Puffer, den die Routine mit einer SCATTER_GATHER_LIST Struktur füllt.
[in] ScatterGatherLength
Gibt die Größe des Puffers in Bytes an, der im ScatterGatherBuffer-Parameter übergeben wird.
Rückgabewert
BuildScatterGatherList gibt einen der folgenden Werte zurück:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_SUCCESS | Der Vorgang wurde erfolgreich abgeschlossen. |
| STATUS_INSUFFICIENT_RESOURCES | Das System verfügt über unzureichende Kartenregister für die Übertragung. |
| STATUS_BUFFER_TOO_SMALL | Die angegebene Länge ist zu groß, um in den Puffer zu passen. |
Hinweise
BuildScatterGatherList ist keine Systemroutine, die direkt mit dem Namen aufgerufen werden kann. Diese Routine kann nur durch zeiger von der Adresse aufgerufen werden, die in einer DMA_OPERATIONS-Struktur zurückgegeben wird. Treiber erhalten die Adresse dieser Routine, indem Sie IoGetDmaAdapter aufrufen, wobei das Versionselement des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION2 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.
BuildScatterGatherList führt den gleichen Vorgang wie GetScatterGatherList aus, mit dem Unterschied, dass es den Puffer verwendet, der im ScatterGatherBuffer-Parameter angegeben ist, um die von ihr erstellte Scatter/Gather-Liste aufzunehmen. Im Gegensatz dazu weist GetScatterGatherList dynamisch einen Puffer zu, der die Scatter/Gather-Liste enthält. Wenn nicht genügend Arbeitsspeicher zum Zuweisen des Puffers verfügbar ist, kann GetScatterGatherList mit einem STATUS_INSUFFICIENT_RESOURCES Fehler fehlschlagen. Treiber, die dieses Szenario vermeiden müssen, können einen Puffer vorab zuweisen, um die Scatter/Gather-Liste zu speichern, und stattdessen BuildScatterGatherList verwenden.
Ein Treiber kann die CalculateScatterGatherList-Routine verwenden, um die Größe des Puffers zu bestimmen, der zugeordnet werden soll, um die Scatter/Gather-Liste zu speichern.
Der Treiber sollte den Zeiger auf die Scatter/Gather-Liste in ScatterGatherBuffer beibehalten, damit der Treiber PutScatterGatherList aufruft. Der Treiber muss PutScatterGatherList aufrufen (wodurch die Liste geleert wird), bevor er auf die Daten in der Liste zugreifen kann.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar in Windows XP und höheren Versionen von Windows. |
| Zielplattform | Desktop |
| Kopfzeile | wdm.h (einschließen von Wdm.h) |
| IRQL | DISPATCH_LEVEL |
| DDI-Complianceregeln | IrqlDispatch(wdm) |