PALLOCATE_ADAPTER_CHANNEL回呼函式 (wdm.h)

發行項
02/27/2024

AllocateAdapterChannel 例程會代表目標裝置對象準備 DMA 作業的系統，然後呼叫驅動程式提供的 AdapterControl 例程來執行 DMA 作業。

語法

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

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

參數

[in] DmaAdapter

IoGetDmaAdapter 所傳回之DMA_ADAPTER結構的指標，代表總線主機適配卡或 DMA 控制器。

[in] DeviceObject

代表所要求 DMA 作業之目標裝置的裝置物件的指標。

[in] NumberOfMapRegisters

指定要在傳輸中使用的地圖緩存器數目。這個值是滿足目前傳輸要求所需的地圖緩存器數目，以及 IoGetDmaAdapter傳回的可用地圖緩存器數目。

[in] ExecutionRoutine

驅動程式提供的 AdapterControl 例程指標。當系統 DMA 控制器或總線主機適配卡可供使用時，就會呼叫例程。

[in] Context

要傳遞至 AdapterControl 例程之驅動程式決定內容的指標。

傳回值

此例程可以傳回下列其中一個NTSTATUS值。

傳回碼	Description
STATUS_SUCCESS	配接器通道已配置。系統會在 DMA 作業開始之後呼叫 AdapterControl 例程。
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters 大於 IoGetDmaAdapter 所傳回的值。不會呼叫 AdapterControl 例程。

備註

AllocateAdapterChannel 不是可直接依名稱呼叫的系統例程。這個例程只能由 DMA_OPERATIONS結構中傳回之位址的指標呼叫。驅動程式會呼叫 IoGetDmaAdapter來取得此例程的位址。

驅動程式會呼叫 AllocateAdapterControl 例程來註冊 AdapterControl 例程，以執行驅動程式的 DMA 作業。 AdapterControl 例程會使用系統 DMA 控制器或總線主機適配卡來執行 DMA 作業。

如果可以立即執行 DMA 作業，系統會立即呼叫 AdapterControl。如果系統 DMA 控制器或總線主機適配卡目前正在使用中， AllocateAdapterChannel 會將 AdapterControl 排入佇列，直到配接器可供使用為止。在這兩種情況下， AllocateAdapterChannel 會傳回STATUS_SUCCESS。

如果系統缺少執行 DMA 作業的資源， AllocateAdapterChannel 會傳回STATUS_INSUFFICIENT_RESOURCES。在此情況下， AdapterControl 不會排入佇列，而且驅動程式應該會以適當的錯誤碼完成目前的 IRP (，例如 STATUS_INSUFFICIENT_RESOURCES) 。

此例程會保留 DMA 控制器通道的獨佔存取權，並對應一或多個滿足指定裝置目前 IRP 傳輸要求所需的 DMA 作業。

一次只能針對裝置物件排入佇列一個 DMA 要求。因此，在 AdapterControl 例程完成執行之前，驅動程式不應該針對相同裝置物件上的另一個 DMA 作業再次呼叫 AllocateAdapterChannel。此外，驅動程式不得從其 AdapterControl 例程內呼叫 AllocateAdapterChannel。

系統會將 DeviceObject 的 CurrentIrp 成員值傳遞為 AdapterControl 的 Irp 參數。如果從驅動程式的 StartIo 例程呼叫 AllocateAdapterChannel，這保證會指向呼叫 StartIo 所要處理的 IRP。否則，若要使用 AdapterControl 的 Irp 參數，驅動程式必須先將 CurrentIrp 設定為指向目前的 IRP，再呼叫 AllocateAdapterChannel。

規格需求

需求	值
最低支援的用戶端	從 Windows 2000 開始提供。
目標平台	桌面
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL	DISPATCH_LEVEL
DDI 合規性規則	IrqlDispatch (storport) 、IrqlDispatch (storport ) 、 IrqlDispatch (wdm)