PALLOCATE_ADAPTER_CHANNEL_EX Rückruffunktion (wdm.h)

Die Routine AllocateAdapterChannelEx ordnet 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-Systemkanal 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 bereitstellen.

[in] NumberOfMapRegisters

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

[in] Flags

Die Zuordnungsflags des Adapterkanals. 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 DMA_SYNCHRONOUS_CALLBACK-Flag 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 zugeordnet wurden. Nachdem die AdapterControl-Routine zurückgegeben wurde, gibt der E/A-Manager das Adapterobjekt automatisch frei. Je nach dem von dieser Routine zurückgegebenen Wert gibt der E/A-Manager möglicherweise zusätzlich die Ressourcen frei, die diesem Objekt zugeordnet wurden.

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

[in, optional] ExecutionContext

Der vom Treiber festgelegte 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 Zuordnungsregister schreibt. Der Aufrufer kann dieses Handle als Parameter für die Routine FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters oder MapTransferEx bereitstellen.

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

Rückgabewert

AllocateAdapterChannelEx gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Mögliche Fehlerrückgabewerte sind die folgenden Statuscodes.

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 anhand des Namens aufgerufen werden kann. Diese Routine kann nur durch einen Zeiger von der Adresse aufgerufen werden, die in einer DMA_OPERATIONS-Struktur zurückgegeben wird. Treiber rufen die Adresse dieser Routine ab, indem sie IoGetDmaAdapter aufrufen, wobei der Version-Member des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapter NULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

AllocateAdapterChannelEx ordnet 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 die vom Aufrufer bereitgestellte 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 bei Bedarf die ausstehende Zuordnungsanforderung 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 nicht die AdapterControl-Routine 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 angibt, 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 angibt, 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

   
Unterstützte Mindestversion (Client) Verfügbar ab Windows 8.
Zielplattform Desktop
Kopfzeile wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL DISPATCH_LEVEL

Siehe auch

AdapterControl

AllocateAdapterChannel

CancelAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

FlushAdapterBuffers

FlushAdapterBuffersEx

FreeAdapterObject

FreeMapRegisters

GetDmaTransferInfo

InitializeDmaTransferContext

IoGetDmaAdapter

MapTransferEx