WdfDmaEnablerGetFragmentLength 函式 (wdfdmaenabler.h)

  • 發行項

[僅適用於 KMDF]

WdfDmaEnablerGetFragmentLength 方法會傳回作業系統支援單一 DMA 傳輸的最大傳輸長度。

語法

size_t WdfDmaEnablerGetFragmentLength(
  [in] WDFDMAENABLER     DmaEnabler,
  [in] WDF_DMA_DIRECTION DmaDirection
);

參數

[in] DmaEnabler

驅動程式從先前呼叫 WdfDmaEnablerCreate 取得的 DMA 啟用器物件的句柄。

[in] DmaDirection

指定 DMA 傳輸作業方向 的WDF_DMA_DIRECTION型別值。 如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

WdfDmaEnablerGetFragmentLength 會傳回 DMA 傳輸的最大長度，以位元組為單位，如果 DmaDirection 參數的值無效，則為零。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

操作系統可支援的 DMA 傳輸長度上限取決於可用的 地圖緩存器 數目。 如果有足夠的地圖緩存器可用， WdfDmaEnablerGetFragmentLength 會傳回 WdfDmaEnablerGetMaximumLength 傳 回的相同值。 否則， WdfDmaEnablerGetFragmentLength 傳回的值會小於 WdfDmaEnablerGetMaximumLength 傳 回的值。

您的驅動程式可以使用 BYTE_TO_PAGES 宏來判斷可用的地圖緩存器數目，如下所示：

BYTE_TO_PAGES(WdfDmaEnablerGetFragmentLength()) + 1

如果您的驅動程式在呼叫 WdfDmaEnablerCreate 時指定雙工配置檔， 則 DmaDirection 參數的值必須是 WdfDmaDirectionReadFromDevice ，才能取得讀取作業的最大傳輸長度和 WdfDmaDirectionWriteToDevice ，以取得寫入作業的最大傳輸長度。 如果您的驅動程式未指定雙工配置檔，驅動程式可以指定 WdfDmaDirectionReadFromDevice 或 WdfDmaDirectionWriteToDevice for DmaDirection。

請注意，如果驅動程式的裝置支援雙工作業， WdfDmaEnablerGetFragmentLength 可以針對 DmaDirection 參數指定的讀取和寫入方向傳回不同的值。 此差異是因為架構會為每個方向建立個別的 配接器物件 ，而操作系統可能會為每個配接器物件提供不同的對應緩存器數目。

範例

下列程式代碼範例會決定處理 NIC 裝置讀取作業所需的地圖緩存器數目下限、計算可用的地圖緩存器數目，以及如果配置的地圖緩存器數目不足，則會報告錯誤。

ULONG  minimumMapRegisters;
ULONG  maxLengthSupported;
ULONG  mapRegistersAllocated;

miniMapRegisters = BYTES_TO_PAGES(NIC_MAX_PACKET_SIZE) + 1;

maxLengthSupported = 
    (ULONG) WdfDmaEnablerGetFragmentLength(
                                           FdoData->WdfDmaEnabler,
                                           WdfDmaDirectionReadFromDevice
                                           );

mapRegistersAllocated = BYTES_TO_PAGES(maxLengthSupported) + 1;

if (mapRegistersAllocated < minimumMapRegisters) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    return status;
}

規格需求

需求 值
目標平台 Universal
最小 KMDF 版本 1.1
標頭 wdfdmaenabler.h (包含 Wdf.h)
程式庫 Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL <=DISPATCH_LEVEL
DDI 合規性規則 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另請參閱

WDF_DMA_DIRECTION

WdfDmaEnablerCreate

WdfDmaEnablerGetMaximumLength