PALLOCATE_ADAPTER_CHANNEL_EX回呼函式 (wdm.h)

發行項
02/29/2024

AllocateAdapterChannelEx 例程會配置執行 DMA 傳輸所需的資源，然後呼叫驅動程式提供的 AdapterControl 例程來起始 DMA 傳輸。

語法

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
)
{...}

參數

[in] DmaAdapter

DMA_ADAPTER 結構的指標。這個結構是代表驅動程式總線主要 DMA 裝置或系統 DMA 通道的配接器物件。呼叫端從先前呼叫IoGetDmaAdapter 例程取得此指標。

[in] DeviceObject

DEVICE_OBJECT 結構的指標。此結構是 PDO (實體裝置物件，) ，代表所要求 DMA 作業的目標裝置。

[in] DmaTransferContext

已初始化 DMA 傳輸內容的指標。此內容是由先前呼叫 InitializeDmaTransferContext 例程所初始化。此內容在所有適配卡配置要求中都必須是唯一的。若要取消擱置的配置要求，呼叫端必須將 DMA 傳輸內容提供給 CancelAdapterChannel 例程。

[in] NumberOfMapRegisters

在 DMA 傳輸中使用的對應緩存器數目。呼叫驅動程式應該將此值設定為滿足目前傳輸要求所需的對應緩存器數目，以及可用的地圖緩存器數目。驅動程式先前稱為 GetDmaTransferInfo 例程，以取得傳輸所需的地圖緩存器數目，並呼叫 IoGetDmaAdapter 例程以取得可用的地圖緩存器數目。

[in] Flags

配接器通道配置旗標。支援下列旗標。

旗標	意義
DMA_SYNCHRONOUS_CALLBACK	AllocateAdapterChannelEx 例程會以同步方式呼叫。如果已設定此旗標，而且必要的 DMA 資源無法立即使用，則呼叫會失敗並傳回STATUS_INSUFFICIENT_RESOURCES。

如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標， ExecutionRoutine 參數是選擇性的，而且可以是 NULL。如需此旗標的詳細資訊，請參閱一節。

[in, optional] ExecutionRoutine

驅動程式提供的 AdapterControl 例程指標，可起始驅動程式的 DMA 傳輸。 I/O 管理員會在為配接器物件配置必要的資源之後呼叫 AdapterControl 例程。 在 AdapterControl 例程傳回之後，I/O 管理員會自動釋放配接器物件。根據這個例程所傳回的值，I/O 管理員可能會額外釋放為此物件配置的資源。

如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標， ExecutionRoutine 是選擇性的，而且可以是 NULL。在此情況下，呼叫端可以使用 AllocateAdapterChannelEx所配置的資源，稍後藉由呼叫 FreeAdapterObject 例程釋放這些資源。如需詳細資訊，請參閱＜備註＞一節。

[in, optional] ExecutionContext

驅動程式決定的配接器控件內容。此內容會當做 Context 參數傳遞至 AdapterControl 例程。

[out, optional] MapRegisterBase

例程將句柄寫入配置之對應緩存器之變數的指標。呼叫端可以將這個句柄當做參數提供給 FlushAdapterBuffersEx、 FlushAdapterBuffers、 FreeMapRegisters 或 MapTransferEx 例程。

如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標， MapRegisterBase 必須是有效的非 NULL 指標。如果 ExecutionRoutine 參數不是 NULL，MapRegisterBase 必須是 NULL。如果 MapRegisterBase 不是 NULL 且 未設定DMA_SYNCHRONOUS_CALLBACK 旗標，或者 MapRegisterBase 和 ExecutionRoutine 都是 NULL，則呼叫會失敗。

傳回值

如果呼叫成功，AllocateAdapterChannelEx 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列狀態代碼。

傳回碼	Description
STATUS_INVALID_PARAMETERS	例程失敗，因為呼叫端傳遞的參數值無效。
STATUS_INSUFFICIENT_RESOURCES	例程無法配置 DMA 傳輸所需的資源。

備註

AllocateAdapterChannelEx 不是可直接依名稱呼叫的系統例程。這個例程只能由DMA_OPERATIONS結構中傳回之位址的指標呼叫。驅動程式會呼叫IoGetDmaAdapter，並將DeviceDescription參數的Version成員設定為 DEVICE_DESCRIPTION_VERSION3，以取得此例程的位址。如果 IoGetDmaAdapter 傳回 NULL，則您的平台上無法使用例程。

AllocateAdapterChannelEx 會配置執行 DMA 作業所需的資源。這些資源包括 DMA 通道和地圖快取器。配置所有必要資源以供 DMA 配接器使用之後， AllocateAdapterChannelEx 會 呼叫呼叫端提供的 AdapterControl 例程來起始 DMA 作業。

根據預設， AllocateAdapterChannelEx 會以異步方式傳回，而不需要等待要求的資源配置完成。在此傳回之後，呼叫端可以視需要呼叫 CancelAdapterChannel 例程來取消擱置的配置要求。

如果呼叫驅動程式設定 DMA_SYNCHRONOUS_CALLBACK 旗標， AllocateAdapterChannelEx 例程的行為如下：

如果要求的 DMA 資源無法立即使用， AllocateAdapterChannelEx 不會等候資源，也不會呼叫 AdapterControl 例程。相反 地，AllocateAdapterChannelEx 會失敗並傳回STATUS_INSUFFICIENT_RESOURCES。
如果已設定 DMA_SYNCHRONOUS_CALLBACK 旗標，則不需要驅動程式提供 AdapterControl 例程。
如果驅動程式提供 AdapterControl 例程， DMA_SYNCHRONOUS_CALLBACK 旗標表示在呼叫線程的內容中呼叫這個例程，然後再傳回 AllocateAdapterChannelEx 。
如果驅動程式未提供 AdapterControl 例程，驅動程式可以在 AllocateAdapterChannelEx 傳回之後使用已配置的資源。在此情況下，驅動程式必須在使用已配置的資源完成之後呼叫 FreeAdapterObject 。