次の方法で共有

SerCx2SystemDmaReceiveCreate 関数 (sercx.h)

  • [アーティクル]

SerCx2SystemDmaReceiveCreate メソッドは、SerCx2 システム DMA 受信オブジェクトを作成します。このオブジェクトは、シリアル フレームワーク拡張機能 (SerCx2) のバージョン 2 がシステム DMA 受信トランザクションの実行に使用します。

構文

NTSTATUS SerCx2SystemDmaReceiveCreate(
  [in]           WDFDEVICE                         Device,
  [in]           PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES            Attributes,
  [out]          SERCX2SYSTEMDMARECEIVE            *SystemDmaReceive
);

パラメーター

[in] Device

シリアル コントローラーを表すフレームワーク デバイス オブジェクトへの WDFDEVICE ハンドル。 シリアル コントローラー ドライバーは、EvtDriverDeviceAdd コールバック関数でこのオブジェクトを作成しました。 詳細については、「SerCx2InitializeDevice」を参照してください。

[in] SystemDmaReceiveConfig

SERCX2_SYSTEM_DMA_RECEIVE_CONFIG 構造体へのポインター。 このメソッドを呼び出す前に、呼び出し元は SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT または SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 関数を呼び出して構造体を初期化する必要があります。 この構造体には、シリアル コントローラー ドライバーによって実装されるイベント コールバック ルーチンのセットへのポインターが含まれています。 SerCx2 はこれらの関数を呼び出して、システム DMA 受信トランザクションを実行します。

[in, optional] Attributes

新しいシステム DMA 受信オブジェクトに割り当てる属性を記述する WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 このメソッドを呼び出す前に、呼び出し元は WDF_OBJECT_ATTRIBUTES_INIT 関数を呼び出して構造体を初期化する必要があります。 このパラメーターは省略可能であり、シリアル コントローラー ドライバーがオブジェクトに属性を割り当てる必要がない場合は、WDF_NO_OBJECT_ATTRIBUTESとして指定できます。 詳細については、「解説」を参照してください。

[out] SystemDmaReceive

このメソッドが新しく作成されたシステム DMA 受信オブジェクトに SERCX2SYSTEMDMARECEIVE ハンドルを書き込む場所へのポインター。 SerCx2 とシリアル コントローラー ドライバーは、このオブジェクトを参照する後続の呼び出しでこのハンドルを使用します。

戻り値

このメソッドは、呼び出しが成功した場合にSTATUS_SUCCESSを返します。 考えられるエラー戻り値には、次の状態コードが含まれます。

リターン コード 形容
STATUS_INVALID_DEVICE_REQUEST
 システム DMA 受信オブジェクトは、SerCx2SystemDmaReceiveCreate 呼び出しの前の から既に存在します。または、SerCx2CustomReceiveCreate メソッドの前の呼び出しからカスタム受信オブジェクトが既に存在します。または、SerCx2CustomTransmitCreate メソッドへの以前の呼び出しからカスタム送信オブジェクトが存在します。または serCx2PioReceiveCreate PIO 受信オブジェクトを作成するためにまだ呼び出されていません。
STATUS_INFO_LENGTH_MISMATCH
 ConfigSize 値が sizeof(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG) 等しくありません。
STATUS_INVALID_PARAMETER
 パラメーター値が無効です。
STATUS_INSUFFICIENT_RESOURCES
 要求された操作を実行するために使用できるリソースが不足しています。

備考

このメソッドは、システム DMA 受信オブジェクトを作成するシリアル コント ローラー ドライバーによって呼び出されます。 SerCx2 は、このオブジェクトを使用してシステム DMA 受信トランザクションを実行します。これは、システム DMA コントローラーを使用してシリアル コントローラーが受信したデータを読み取る I/O トランザクションです。

通常、シリアル コントローラー ドライバーは、EvtDevicePrepareHardware コールバック関数から SerCx2SystemDmaReceiveCreate を呼び出します。 この関数は、システム DMA チャネルを含めることができるハードウェア リソースの一覧を受け取ります。

シリアル コントローラー ドライバーは、SerCx2SystemDmaReceiveCreateを呼び出す前に、serCx2InitializeDevice を正常に呼び出し、SerCx2PioReceiveCreate メソッド 呼び出す必要があります。

SerCx2SystemDmaReceiveCreate呼び出す前に、シリアル コントローラー ドライバーは SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT または SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 関数を呼び出して、SystemDmaReceiveConfigによって指 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG 構造体 初期化する必要があります。 これらの関数は、構造体の次のメンバーを 0 に設定します。

  • MaximumScatterGatherFragments の
  • MinimumTransferUnitOverride の
  • DmaAlignment
  • MinimumTransactionLength
  • 排他
必要に応じて、シリアル コントローラー ドライバーは、初期化関数が返された後、これらのメンバーのいずれかを 0 以外の値に設定できます。 ただし、便宜上、SerCx2SystemDmaReceiveCreate これらのメンバーが 0 の場合、次の既定値が使用されます。
  • MaximumScatterGatherFragments が 0 の場合、SerCx2 は散布図/収集リスト内の要素の最大数を ((ULONG)-1) に設定します。
  • MinimumTransferUnitOverride が 0 の場合、SerCx2 は最小転送単位を既定値に設定します。これは、システム DMA コントローラーの DMA_ADAPTER 構造体で指定されます。 この構造体の詳細については、「WdfDmaEnablerWdmGetDmaAdapterを参照してください。
  • DmaAlignment が 0 の場合、SerCx2 はアラインメント値を最小転送単位に設定します。 MinimumTransferUnitOverride が 0 の場合、既定の最小転送単位が使用されます。
  • MinimumTransactionLength が 0 の場合、SerCx2 は最小トランザクション長を 1 バイトに設定します。
  • 排他 ゼロ (FALSE) の場合、排他モードは無効になります。
呼び出し元のドライバー 排他 を TRUEに設定する場合、MinimumTransferUnitOverride、DmaAlignment、および MinimumTransactionLength メンバー 0 である必要があります。 詳細については、SERCX2_SYSTEM_DMA_RECEIVE_CONFIGを参照してください。

実装されたコールバック関数の指定された組み合わせが無効な場合、SerCx2SystemDmaReceiveCreate 失敗し、STATUS_INVALID_PARAMETERが返されます。 ドライバーは、EvtSerCx2SystemDmaReceiveEnableNewDataNotification と EvtSerCx2SystemDmaReceiveCancelNewDataNotification 関数の両方または両方を実装する必要があります。

オプションとして、シリアル コントローラー ドライバーは、Attributes パラメーターを使用して、システム DMA 受信オブジェクトのコンテキストを作成し、EvtCleanupCallback へのポインターを提供し、EvtDestroyCallback 関数を してオブジェクトを削除する準備を行うことができます。 詳細については、WDF_OBJECT_ATTRIBUTESを参照してください。

属性 パラメーターが WDF_OBJECT_ATTRIBUTES 構造体を指している場合、呼び出し元は、WDF_OBJECT_ATTRIBUTES_INIT 初期化関数が ParentObject、ExecutionLevel、およびこの構造体の SynchronizationScope メンバーに書き込む値を上書きしてはなりません。

システム DMA 受信オブジェクトの作成の詳細については、SERCX2SYSTEMDMARECEIVEを参照してください。 システム DMA 受信トランザクションの詳細については、「SerCx2 System-DMA-Receive Transactions」を参照してください。

必要条件

要件 価値
サポートされる最小クライアント Windows 8.1以降で使用できます。
ターゲット プラットフォーム の 万国
ヘッダー sercx.h
IRQL PASSIVE_LEVEL

関連項目

DMA_ADAPTER

EvtCleanupCallback を する

EvtDestroyCallback の

EvtDevicePrepareHardware の

EvtDriverDeviceAdd の

EvtSerCx2SystemDmaReceiveCancelNewDataNotification の

EvtSerCx2SystemDmaReceiveCleanupTransaction の

EvtSerCx2SystemDmaReceiveEnableNewDataNotification の

EvtSerCx2SystemDmaReceiveInitializeTransaction の

SERCX2SYSTEMDMARECEIVE

SERCX2_SYSTEM_DMA_RECEIVE_CONFIG

SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT

SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION

SerCx2InitializeDevice の

SerCx2PioReceiveCreate

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfDmaEnablerWdmGetDmaAdapter