WdfDmaEnablerGetFragmentLength 関数 (wdfdmaenabler.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfDmaEnablerGetFragmentLength メソッドは、オペレーティング システムが 1 つの 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 パラメーターの値が無効な場合は 0 を返します。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

オペレーティング システムでサポートできる DMA 転送の最大長は、使用可能な マップ レジスタ の数によって異なります。 十分なマップ レジスタが使用可能な場合、 WdfDmaEnablerGetFragmentLength は WdfDmaEnablerGetMaximumLength が返すのと同じ値を返します。 それ以外の場合、 WdfDmaEnablerGetFragmentLength が返す値は 、WdfDmaEnablerGetMaximumLength が 返す値より小さくなります。

ドライバーは、次のように、BYTE_TO_PAGES マクロを使用して使用可能なマップ レジスタの数を決定できます。

BYTE_TO_PAGES(WdfDmaEnablerGetFragmentLength()) + 1

ドライバーが WdfDmaEnablerCreate を呼び出したときに二重プロファイルを指定した場合、読み取り操作の最大転送長を取得するには DmaDirection パラメーターの値を WdfDmaDirectionReadFromDevice に、書き込み操作の最大転送長を取得するには WdfDmaDirectionWriteToDevice を指定する必要があります。 ドライバーで二重プロファイルが指定されていない場合、ドライバーは、DmaDirection の WdfDmaDirectionReadFromDevice または WdfDmaDirectionWriteToDevice を指定できます。

ドライバーのデバイスで双方向操作がサポートされている場合、 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;
}

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.1
Header wdfdmaenabler.h (Wdf.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL <=DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

こちらもご覧ください

WDF_DMA_DIRECTION

WdfDmaEnablerCreate

WdfDmaEnablerGetMaximumLength