PALLOCATE_ADAPTER_CHANNEL Rückruffunktion (wdm.h)
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 |
|---|---|
|
Der Adapterkanal wurde zugeordnet. Das System ruft die AdapterControl-Routine auf, sobald der DMA-Vorgang beginnen kann. |
|
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) |