PBUILD_SCATTER_GATHER_LIST_EX Rückruffunktion (wdm.h)
Die BuildScatterGatherListEx Routine weist die Ressourcen zu, die für eine DMA-Übertragung erforderlich sind, erstellt eine Punkt-/Gather-Liste und ruft die vom Treiber bereitgestellte AdapterListControl Routine auf, um die DMA-Übertragung zu initiieren.
Vorsicht
Rufen Sie diese Routine nicht für ein System-DMA-Gerät auf.
Syntax
PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;
NTSTATUS PbuildScatterGatherListEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PVOID DmaTransferContext,
[in] PMDL Mdl,
[in] ULONGLONG Offset,
[in] ULONG Length,
[in] ULONG Flags,
[in, optional] PDRIVER_LIST_CONTROL ExecutionRoutine,
[in, optional] PVOID Context,
[in] BOOLEAN WriteToDevice,
[in] PVOID ScatterGatherBuffer,
[in] ULONG ScatterGatherLength,
[in, optional] PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
[in, optional] PVOID CompletionContext,
[out, optional] PVOID ScatterGatherList
)
{...}
Parameter
[in] DmaAdapter
Ein Zeiger auf eine DMA_ADAPTER Struktur. Diese Struktur ist das Adapterobjekt, das das Busmaster-DMA-Gerät oder den DMA-Kanal des Treibers darstellt. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf an die IoGetDmaAdapter Routine abgerufen.
[in] DeviceObject
Ein Zeiger auf eine DEVICE_OBJECT Struktur. Diese Struktur ist das physische Geräteobjekt (PDO), das das Zielgerät für den angeforderten DMA-Vorgang darstellt.
[in] DmaTransferContext
Ein Zeiger auf einen initialisierten DMA-Übertragungskontext. Dieser Kontext wurde durch einen vorherigen Aufruf der InitializeDmaTransferContext Routine initialisiert. Dieser Kontext muss für alle Adapterzuweisungsanforderungen eindeutig sein. Um eine ausstehende Zuordnungsanforderung abzubrechen, muss der Aufrufer den DMA-Übertragungskontext für die Anforderung an die CancelAdapterChannel Routine bereitstellen.
[in] Mdl
Ein Zeiger auf eine MDL-Kette, die das physische Seitenlayout für eine Sammlung gesperrter Puffer im virtuellen Speicher beschreibt. Die Punkt/Gather-Liste für die DMA-Übertragung verwendet den Bereich dieses Speichers, der durch die parameter Offset und Length angegeben wird. Weitere Informationen zu MDL-Ketten finden Sie unter Verwenden von MDLs.
[in] Offset
Der Startoffset für die XY/Gather-DMA-Übertragung. Dieser Parameter ist ein Byte-Offset vom Anfang des Puffers in der ersten MDL in der MDL-Kette. Wenn die MDLs in der MDL-Kette eine Gesamtmenge von N Bytes Pufferspeicher angeben, befinden sich gültige Werte von Offset- im Bereich 0 bis N-1.
[in] Length
Die Größe der DMA-Übertragung in Bytes. Wenn die MDL-Kette insgesamt N Bytes Pufferraum angibt, befinden sich gültige Werte Length im Bereich 1 bis N –Offset.
[in] Flags
Die Zuordnungskennzeichnungen des Adapterkanals. Das folgende Flag wird unterstützt:
| Flagge | Bedeutung |
|---|---|
| DMA_SYNCHRONOUS_CALLBACK | Die BuildScatterGatherListEx Routine wird synchron aufgerufen. Wenn dieses Flag festgelegt ist und die erforderlichen DMA-Ressourcen nicht sofort verfügbar sind, schlägt der Aufruf fehl und gibt STATUS_INSUFFICIENT_RESOURCES zurück. |
Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist, ist der ExecutionRoutine Parameter optional und kann NULL-sein. Wenn dieses Flag nicht festgelegt ist, muss ExecutionRoutine- ein gültiger, nichtNULL- Zeiger sein. Weitere Informationen zu dieser Kennzeichnung finden Sie im Abschnitt "Hinweise".
[in, optional] ExecutionRoutine
Ein Zeiger auf die vom Treiber bereitgestellte AdapterListControl Routine, die die DMA-Übertragung für den Treiber initiiert. Der E/A-Manager ruft die AdapterListControl Routine auf, nachdem die erforderlichen Ressourcen für das Adapterobjekt zugeordnet wurden. Nachdem die AdapterListControl Routine zurückgegeben wurde, gibt der E/A-Manager automatisch das Adapterobjekt und die Ressourcen frei, die für dieses Objekt zugeordnet wurden.
Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist, ist ExecutionRoutine optional und kann NULL-sein. Wenn ExecutionRoutine-NULL-ist, kann der Aufrufer die von BuildScatterGatherListExzugeordneten Ressourcen verwenden. Weitere Informationen finden Sie im Abschnitt "Hinweise".
[in, optional] Context
Der vom Treiber bestimmte Kontext des Adaptersteuerelements. Dieser Kontext wird als Context Parameter an die AdapterListControl Routine übergeben.
[in] WriteToDevice
Die Richtung der DMA-Übertragung. Legen Sie diesen Parameter auf TRUE- für einen Schreibvorgang fest, der Daten vom Speicher an das Gerät überträgt. Legen Sie diesen Parameter auf FALSE- für einen Lesevorgang fest, der Daten vom Gerät in den Arbeitsspeicher überträgt.
[in] ScatterGatherBuffer
Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, in den die Routine die Punkt/Gather-Liste für die DMA-Übertragung schreibt. Diese Liste beginnt mit einer SCATTER_GATHER_LIST Struktur, auf die ein SCATTER_GATHER_ELEMENT Array folgt.
[in] ScatterGatherLength
Die Größe des Puffers in Bytes, der im ScatterGatherBuffer Parameter übergeben wird. Die zugeordnete Puffergröße muss groß genug sein, um die Punkt/Erfassungsliste sowie interne Daten zu enthalten, die vom Betriebssystem in diesem Puffer gespeichert werden. Rufen Sie zum Berechnen der erforderlichen Puffergröße die GetDmaTransferInfo oder CalculateScatterGatherList Routine auf.
[in, optional] DmaCompletionRoutine
Wird nicht verwendet. Wird auf NULL-festgelegt.
[in, optional] CompletionContext
Wird nicht verwendet. Wird auf NULL-festgelegt.
[out, optional] ScatterGatherList
Ein Zeiger auf eine Variable, in die die Routine einen Zeiger in die Punkt/Gather-Liste für die DMA-Übertragung schreibt. Diese Liste beginnt mit einer SCATTER_GATHER_LIST Struktur, die einen Zeiger auf ein SCATTER_GATHER_ELEMENT Array enthält. Dieser Ausgabezeiger entspricht immer dem ScatterGatherBuffer Parameterwert.
Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist und der ExecutionRoutine Parameter NULList, muss ScatterGatherList- ein gültiger, nichtNULL- Zeiger sein. Wenn ExecutionRoutine nichtNULL-ist, ist ScatterGatherList- optional und kann NULL- werden, wenn der aufrufende Treiber die Punkt/Gather-Liste nicht erfordert. Der BuildScatterGatherListEx-aufruf schlägt fehl, wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist und ScatterGatherList- und ExecutionRoutine- beide NULL-sind, oder wenn das DMA_SYNCHRONOUS_CALLBACK Flag nicht festgelegt ist und ExecutionRoutineNULList.
Rückgabewert
BuildScatterGatherListEx gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind die folgenden Statuscodes.
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INVALID_PARAMETERS | Fehler der Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben werden. |
| STATUS_BUFFER_TOO_SMALL | Der vom Aufrufer bereitgestellte Puffer in ScatterGatherBuffer- ist zu klein, um die Punkt/Gather-Liste zu enthalten. |
| STATUS_INSUFFICIENT_RESOURCES | Die Routine konnte ressourcen, die für die DMA-Übertragung erforderlich sind, nicht zuordnen. |
Bemerkungen
BuildScatterGatherListEx* 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 Mitglied des DeviceDescription- Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt wird. Wenn IoGetDmaAdapterNULL-zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.
Verwenden Sie BuildScatterGatherListEx- nur für Busmasteradapter. Verwenden Sie diese Routine nicht für einen System-DMA-Adapter.
BuildScatterGatherListEx ähnelt der GetScatterGatherListEx Routine, mit der Ausnahme, dass der Aufrufer den Puffer für die Punkt/Gather-Liste zuweist.
Beispielsweise kann ein Treiber während der Geräteinitialisierung einen oder mehrere Punkt-/Gatherpuffer vorverlangen. Später kann ein BuildScatterGatherListEx Aufruf, der einen solchen Puffer verwendet, in Bedingungen mit geringer Speicherverfügbarkeit erfolgreich sein, die dazu führen kann, dass ein GetScatterGatherListEx-Aufruf fehlschlägt.
Standardmäßig wird BuildScatterGatherListEx asynchron zurückgegeben, ohne auf den Abschluss der angeforderten Ressourcenzuordnung zu warten. Nach dieser Rückgabe kann der Aufrufer ggf. die ausstehende Zuordnungsanforderung abbrechen, indem die CancelAdapterChannel Routine aufgerufen wird.
Wenn der aufrufende Treiber das DMA_SYNCHRONOUS_CALLBACK Flag festlegt, verhält sich die BuildScatterGatherListEx- Routine wie folgt:
Wenn die angeforderten Ressourcen nicht sofort verfügbar sind, wartet BuildScatterGatherListEx- nicht auf Ressourcen, erstellt keine Punkt-/Gather-Liste und ruft nicht die AdapterListControl Routine auf. Stattdessen schlägt BuildScatterGatherListEx- fehl und gibt STATUS_INSUFFICIENT_RESOURCES zurück.
Der Treiber ist nicht erforderlich, um eine AdapterListControl- Routine zu liefern, wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist.
Wenn der Treiber eine AdapterListControl Routine bereitstellt, gibt das DMA_SYNCHRONOUS_CALLBACK Flag an, dass diese Routine im Kontext des aufrufenden Threads aufgerufen werden soll, bevor BuildScatterGatherListEx- zurückgegeben wird.
Wenn der Treiber keine AdapterListControl- Routine liefert, kann der Treiber die zugeordneten Ressourcen und Punkt-/Gather-Listen verwenden, nachdem BuildScatterGatherListEx zurückgegeben wird. In diesem Fall muss der Treiber einen gültigen, nichtNULL-ScatterGatherList- Zeiger angeben. Darüber hinaus muss der Treiber nach Abschluss der vom Treiber initiierten DMA-Übertragung die FreeAdapterObject- Routine aufrufen, um die Ressourcen freizugeben, die BuildScatterGatherListEx für das Adapterobjekt zugewiesen wurden.
BuildScatterGatherListEx ist eine erweiterte Version der BuildScatterGatherList Routine. In der folgenden Liste sind die Features zusammengefasst, die nur in der erweiterten Version verfügbar sind:
| Merkmal | Beschreibung |
|---|---|
| Anfangsoffset | Der aufrufende Treiber kann einen Startoffset für eine X/Gather-DMA-Übertragung angeben, anstatt die Übertragung an der ersten Pufferadresse am Anfang der MDL-Kette zu starten. |
| Zuordnungsanforderungsabbruch | Der Treiber kann CancelAdapterChannel- aufrufen, um eine ausstehende Zuordnungsanforderung abzubrechen, wenn der DMA-Adapter in die Warteschlange gestellt wird, um auf DMA-Ressourcen zu warten. |
| Synchroner Rückruf | Der Treiber kann das DMA_SYNCHRONOUS_CALLBACK Flag festlegen, um anzufordern, dass die vom Treiber bereitgestellte AdapterListControl- routine im aufrufenden Thread aufgerufen werden soll, bevor BuildScatterGatherListEx zurückgibt. |
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar ab Windows 8. |
| Zielplattform- | Desktop |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL- | DISPATCH_LEVEL |