PALLOCATE_ADAPTER_CHANNEL_EX Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die AllocateAdapterChannelEx Routine weist die Ressourcen zu, die zum Ausführen einer DMA-Übertragung erforderlich sind, und ruft dann die vom Treiber bereitgestellte AdapterControl- Routine auf, um die DMA-Übertragung zu initiieren.

Syntax

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

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] NumberOfMapRegisters

Die Anzahl der Kartenregister, die bei der DMA-Übertragung verwendet werden sollen. Der aufrufende Treiber sollte diesen Wert auf die geringere Anzahl der Kartenregister festlegen, die erforderlich sind, um die aktuelle Übertragungsanforderung zu erfüllen, und die Anzahl der verfügbaren Kartenregister. Der Treiber hat zuvor die GetDmaTransferInfo Routine aufgerufen, um die Anzahl der kartenregister abzurufen, die für die Übertragung erforderlich sind, und die IoGetDmaAdapter Routine aufgerufen, um die Anzahl der verfügbaren Kartenregister abzurufen.

[in] Flags

Die Zuordnungskennzeichnungen des Adapterkanals. Das folgende Flag wird unterstützt.

Flagge	Bedeutung
DMA_SYNCHRONOUS_CALLBACK	Die AllocateAdapterChannelEx 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 die ExecutionRoutine Parameter optional und kann NULL sein. Weitere Informationen zu dieser Kennzeichnung finden Sie im Abschnitt "Hinweise".

[in, optional] ExecutionRoutine

Ein Zeiger auf die vom Treiber bereitgestellte AdapterControl Routine, die die DMA-Übertragung für den Treiber initiiert. Der E/A-Manager ruft die AdapterControl Routine auf, nachdem die erforderlichen Ressourcen für das Adapterobjekt zugeordnet wurden. Nachdem die AdapterControl Routine zurückgegeben wurde, gibt der E/A-Manager das Adapterobjekt automatisch frei. Der E/A-Manager kann zusätzlich die Ressourcen freigeben, die für dieses Objekt zugeordnet wurden, je nach dem von dieser Routine zurückgegebenen Wert.

Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist, ist die ExecutionRoutine optional und kann NULL-sein. In diesem Fall kann der Aufrufer die von AllocateAdapterChannelExzugeordneten Ressourcen verwenden und diese Ressourcen später freigeben, indem die FreeAdapterObject Routine aufgerufen wird. Weitere Informationen finden Sie im Abschnitt "Hinweise".

[in, optional] ExecutionContext

Der vom Treiber bestimmte Kontext des Adaptersteuerelements. Dieser Kontext wird als Context Parameter an die AdapterControl Routine übergeben.

[out, optional] MapRegisterBase

Ein Zeiger auf eine Variable, in die die Routine ein Handle in die zugeordneten Kartenregister schreibt. Der Aufrufer kann dieses Handle als Parameter für die FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegistersoder MapTransferEx Routine bereitstellen.

Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist, muss MapRegisterBase- ein gültiger, nichtNULL- Zeiger sein. Wenn der ExecutionRoutine Parameter nichtNULL-ist, muss MapRegisterBaseNULL-sein. Der Aufruf schlägt fehl, wenn MapRegisterBase- nichtNULL- ist und das DMA_SYNCHRONOUS_CALLBACK Flag nicht festgelegt ist oder wenn MapRegisterBase- und ExecutionRoutine- beide NULL-sind.

Rückgabewert

AllocateAdapterChannelEx 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_INSUFFICIENT_RESOURCES	Die Routine konnte ressourcen, die für die DMA-Übertragung erforderlich sind, nicht zuordnen.

Bemerkungen

AllocateAdapterChannelEx 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 aufrufen, der auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapterNULL-zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

AllocateAdapterChannelEx weist die Ressourcen zu, die zum Ausführen eines DMA-Vorgangs erforderlich sind. Zu diesen Ressourcen gehören DMA-Kanäle und Kartenregister. Nachdem alle erforderlichen Ressourcen für die Verwendung durch den DMA-Adapter zugeordnet wurden, ruft AllocateAdapterChannelEx den vom Aufrufer bereitgestellten AdapterControl Routine auf, um den DMA-Vorgang zu initiieren.

Standardmäßig gibt AllocateAdapterChannelEx asynchron zurück, 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 kennzeichen DMA_SYNCHRONOUS_CALLBACK festlegt, verhält sich die AllocateAdapterChannelEx- Routine wie folgt:

Wenn die angeforderten DMA-Ressourcen nicht sofort verfügbar sind, wartet AllocateAdapterChannelEx- nicht auf Ressourcen und ruft die AdapterControl Routine nicht auf. Stattdessen schlägt AllocateAdapterChannelEx fehl und gibt STATUS_INSUFFICIENT_RESOURCES zurück.
Der Treiber ist nicht erforderlich, um eine AdapterControl Routine zu liefern, wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist.
Wenn der Treiber eine AdapterControl Routine bereitstellt, gibt das DMA_SYNCHRONOUS_CALLBACK Flag an, dass diese Routine im Kontext des aufrufenden Threads aufgerufen werden soll, bevor AllocateAdapterChannelEx- zurückgegeben wird.
Wenn der Treiber keine AdapterControl Routine liefert, kann der Treiber die zugeordneten Ressourcen verwenden, nachdem AllocateAdapterChannelEx zurückgegeben wurde. In diesem Fall muss der Treiber FreeAdapterObject aufrufen, nachdem er die zugeordneten Ressourcen verwendet hat.

AllocateAdapterChannelEx ist eine erweiterte Version der AllocateAdapterChannel Routine. Die folgenden Features sind nur in der erweiterten Version verfügbar:

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