PALLOCATE_ADAPTER_CHANNEL Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die AllocateAdapterChannel-Routine bereitet das System für einen DMA-Vorgang im Namen des Zielgeräteobjekts vor und ruft dann die vom Treiber bereitgestellte AdapterControl-Routine auf, um den DMA-Vorgang auszuführen.

Syntax

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

Parameter

[in] DmaAdapter

Zeiger auf die DMA_ADAPTER Struktur, die von IoGetDmaAdapter zurückgegeben wird und den Bus-master-Adapter oder DMA-Controller darstellt.

[in] DeviceObject

Zeiger auf das Geräteobjekt, das das Zielgerät für einen angeforderten DMA-Vorgang darstellt.

[in] NumberOfMapRegisters

Gibt die Anzahl der Kartenregister an, die in der Übertragung verwendet werden sollen. Dieser Wert ist der geringere Wert der Anzahl von Kartenregistern, die zum Erfüllen der aktuellen Übertragungsanforderung erforderlich sind, und der Anzahl der verfügbaren Kartenregister, die von IoGetDmaAdapter zurückgegeben werden.

[in] ExecutionRoutine

Zeiger auf eine vom Treiber bereitgestellte AdapterControl-Routine . Die Routine wird aufgerufen, wenn der System-DMA-Controller oder der Bus-master-Adapter verfügbar wird.

[in] Context

Zeiger auf den vom Treiber bestimmten Kontext, der an die AdapterControl-Routine übergeben werden soll.

Rückgabewert

Diese Routine kann einen der folgenden NTSTATUS-Werte zurückgeben.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Adapterkanal wurde zugeordnet. Das System ruft die AdapterControl-Routine auf, sobald der DMA-Vorgang beginnen kann.
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters ist größer als der von IoGetDmaAdapter zurückgegebene Wert. Die AdapterControl-Routine wird nicht aufgerufen.

Hinweise

AllocateAdapterChannel 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.

Ein Treiber ruft die AllocateAdapterControl-Routine auf, um eine AdapterControl-Routine zu registrieren, die einen DMA-Vorgang für den Treiber ausführt. Die AdapterControl-Routine führt einen DMA-Vorgang mithilfe des System-DMA-Controllers oder eines Bus-master-Adapters durch.

Wenn der DMA-Vorgang sofort ausgeführt werden kann, ruft das System sofort AdapterControl auf. Wenn der DMA-Controller des Systems oder der Bus-master-Adapter derzeit verwendet wird, stellt AllocateAdapterChannel das AdapterControl-Steuerelement in die Warteschlange, bis der Adapter verfügbar ist. In beiden Fällen gibt AllocateAdapterChannel STATUS_SUCCESS zurück.

Wenn dem System die Ressourcen zum Ausführen des DMA-Vorgangs fehlen, gibt AllocateAdapterChannel STATUS_INSUFFICIENT_RESOURCES zurück. In diesem Fall befindet sich AdapterControl nicht in der Warteschlange, und der Treiber sollte die aktuelle IRP mit dem entsprechenden Fehlercode (z. B. STATUS_INSUFFICIENT_RESOURCES) abschließen.

Diese Routine behält sich exklusiven Zugriff auf einen DMA-Controllerkanal und Zuordnungsregister für einen oder mehrere DMA-Vorgänge vor, die erforderlich sind, um die aktuelle IRP-Übertragungsanforderung für das angegebene Gerät zu erfüllen.

Nur eine DMA-Anforderung kann für ein Geräteobjekt gleichzeitig in die Warteschlange gestellt werden. Daher sollte der Treiber AllocateAdapterChannel für einen anderen DMA-Vorgang auf demselben Geräteobjekt erst erneut aufrufen, wenn die AdapterControl-Routine die Ausführung abgeschlossen hat. Darüber hinaus darf ein Treiber "AllocateAdapterChannel " nicht innerhalb seiner AdapterControl-Routine aufrufen.

Das System übergibt den Wert des CurrentIrp-Members von DeviceObject als Irp-Parameter von AdapterControl. Wenn AllocateAdapterChannel aus der StartIo-Routine eines Treibers aufgerufen wird, wird garantiert, dass dies auf den IRP verweist, für den StartIo aufgerufen wurde. Andernfalls muss der Treiber CurrentIrp so festlegen, dass er auf den aktuellen IRP zeigt, bevor er AllocateAdapterChannel aufruft, um den Irp-Parameter von AdapterControl verwenden zu können.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
DDI-Complianceregeln	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)