PBUILD_SCATTER_GATHER_LIST Rückruffunktion (wdm.h)
Die BuildScatterGatherList Routine bereitet das System auf einen DMA-Vorgang mit einem vom Treiber bereitgestellten Puffer zum Erstellen der Punkt/Gather-Liste vor.
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, die den Busmasteradapter oder DMA-Controller darstellt.
[in] DeviceObject
Zeiger auf das Geräteobjekt, das das Zielgerät für den DMA-Vorgang darstellt.
[in] Mdl
Zeigen Sie auf die MDL, die den durch den MdlAddress Member des aktuellen IRP angegebenen Puffers beschreibt.
[in] CurrentVa
Zeiger auf die aktuelle virtuelle Adresse in der MDL, damit der Puffer für einen DMA-Übertragungsvorgang zugeordnet wird.
[in] Length
Gibt die Länge des zuzuordnenden Puffers in Bytes an.
[in] ExecutionRoutine
Zeiger auf eine vom Treiber bereitgestellte AdapterListControl Routine, die bei IRQL = DISPATCH_LEVEL aufgerufen wird, wenn der DMA-Controller oder der Busmasteradapter des Systems verfügbar ist.
[in] Context
Zeiger auf den vom Treiber bestimmten Kontext, der beim Aufruf an ExecutionRou tine übergeben wird.
[in] WriteToDevice
Gibt die Richtung der DMA-Übertragung an: TRUE für eine Übertragung vom Puffer auf das Gerät und ANDERENfalls FALSE.
[in] ScatterGatherBuffer
Zeigen Sie auf den vom Aufrufer bereitgestellten Puffer, den die Routine mit einer SCATTER_GATHER_LIST Struktur ausfü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 Length ist zu groß, um in den Puffer zu passen. |
Bemerkungen
BuildScatterGatherList ist keine Systemroutine, die direkt anhand des Namens aufgerufen werden kann. Diese Routine kann nur durch Zeiger von der in einer DMA_OPERATIONS Struktur zurückgegebenen Adresse aufgerufen werden. Treiber rufen die Adresse dieser Routine ab, indem sie IoGetDmaAdapter- mit dem Version Member des DeviceDescription- Parameters auf DEVICE_DESCRIPTION_VERSION2 festgelegt wird. Wenn IoGetDmaAdapterNULL-zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.
BuildScatterGatherList führt den gleichen Vorgang wie GetScatterGatherListaus, mit der Ausnahme, dass der im ScatterGatherBuffer Parameter bereitgestellte Puffer verwendet wird, um die von ihr erstellten Punkt/Gather-Liste zu speichern. Im Gegensatz dazu weist GetScatterGatherList dynamisch einen Puffer zu, der die Punkt/Gather-Liste enthält. Wenn nicht genügend Arbeitsspeicher verfügbar ist, um den Puffer zuzuweisen, kann GetScatterGatherList- mit einem STATUS_INSUFFICIENT_RESOURCES Fehler fehlschlagen. Treiber, die dieses Szenario vermeiden müssen, können einen Puffer vorab anwenden, um die Punkt/Gather-Liste zu speichern, und stattdessen BuildScatterGatherList- verwenden.
Ein Treiber kann die CalculateScatterGatherList Routine verwenden, um die Größe des Puffers zu bestimmen, der der Punkt/Gather-Liste zugeordnet werden soll.
Der Treiber sollte den Zeiger auf die Punkt/Gather-Liste in ScatterGatherBuffer- beibehalten, wenn der Treiber PutScatterGatherListaufruft. Der Treiber muss PutScatterGatherList- aufrufen (wodurch die Liste gelebt wird), bevor er auf die Daten in der Liste zugreifen kann.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar in Windows XP und höheren Versionen von Windows. |
| Zielplattform- | Desktop |
| Header- | wdm.h (include Wdm.h) |
| IRQL- | DISPATCH_LEVEL |
| DDI-Complianceregeln | IrqlDispatch(wdm) |