PALLOCATE_ADAPTER_CHANNEL_EX Rückruffunktion (wdm.h)

Artikel
02/27/2024

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 den Bus-master DMA-Gerät oder System-DMA-Kanal des Treibers darstellt. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf der 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 Adapterzuordnungsanforderungen eindeutig sein. Um eine ausstehende Zuordnungsanforderung abzubrechen, muss der Aufrufer den DMA-Übertragungskontext für die Anforderung an die CancelAdapterChannel-Routine angeben.

[in] NumberOfMapRegisters

Die Anzahl der Kartenregister, die in der DMA-Übertragung verwendet werden sollen. Der aufrufende Treiber sollte diesen Wert auf die geringere Anzahl von Kartenregistern festlegen, die zum Erfüllen der aktuellen Übertragungsanforderung erforderlich sind, und auf die Anzahl der verfügbaren Kartenregister. Der Treiber hat zuvor die GetDmaTransferInfo-Routine aufgerufen, um die Anzahl der für die Übertragung erforderlichen Kartenregister abzurufen, und die IoGetDmaAdapter-Routine aufgerufen, um die Anzahl der verfügbaren Kartenregister abzurufen.

[in] Flags

Die Adapterkanalzuordnungsflags. Das folgende Flag wird unterstützt.

Flag	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 flag DMA_SYNCHRONOUS_CALLBACK festgelegt ist, ist der ExecutionRoutine-Parameter optional und kann NULL sein. Weitere Informationen zu diesem Flag 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 zugewiesen wurden. Nachdem die AdapterControl-Routine zurückgegeben wurde, gibt der E/A-Manager das Adapterobjekt automatisch frei. Der E/A-Manager gibt möglicherweise zusätzlich die Ressourcen frei, die für dieses Objekt zugewiesen wurden, abhängig vom Wert, der von dieser Routine zurückgegeben wird.

Wenn das flag DMA_SYNCHRONOUS_CALLBACK festgelegt ist, ist die ExecutionRoutine optional und kann NULL sein. In diesem Fall kann der Aufrufer die von AllocateAdapterChannelEx zugewiesenen Ressourcen verwenden und diese Ressourcen später durch Aufrufen der FreeAdapterObject-Routine freigeben. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in, optional] ExecutionContext

Der treiberbestimmte Adaptersteuerungskontext. 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 Routinen FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters oder MapTransferEx bereitstellen.

Wenn das DMA_SYNCHRONOUS_CALLBACK-Flag festgelegt ist, muss MapRegisterBase ein gültiger Nicht-NULL-Zeiger sein. Wenn der ExecutionRoutine-Parameter nicht NULL ist, muss MapRegisterBaseNULL sein. Der Aufruf schlägt fehl, wenn MapRegisterBase nicht NULL 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 umfassen die folgenden status-Codes.

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETERS	Fehler bei der Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben wurden.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte die für die DMA-Übertragung erforderlichen Ressourcen nicht zuordnen.

Hinweise

AllocateAdapterChannelEx 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_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 zugewiesen wurden, ruft AllocateAdapterChannelEx die vom Aufrufer bereitgestellte AdapterControl-Routine auf, um den DMA-Vorgang zu initiieren.

AllocationAdapterChannelEx gibt standardmäßig asynchron zurück, ohne auf den Abschluss der angeforderten Ressourcenzuordnung zu warten. Nach dieser Rückgabe kann der Aufrufer die ausstehende Zuordnungsanforderung bei Bedarf abbrechen, indem er die CancelAdapterChannel-Routine aufruft.

Wenn der aufrufende Treiber das flag 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 muss keine AdapterControl-Routine bereitstellen, wenn das DMA_SYNCHRONOUS_CALLBACK-Flag festgelegt ist.
Wenn der Treiber eine AdapterControl-Routine bereitstellt, gibt das Flag DMA_SYNCHRONOUS_CALLBACK an, dass diese Routine im Kontext des aufrufenden Threads aufgerufen werden soll, bevor AllocateAdapterChannelEx zurückgegeben wird.
Wenn der Treiber keine AdapterControl-Routine zur Verfügung stellt, kann der Treiber die zugeordneten Ressourcen verwenden, nachdem AllocateAdapterChannelEx zurückgegeben wird. In diesem Fall muss der Treiber FreeAdapterObject aufrufen, nachdem er die zugewiesenen 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
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL