SerCx2SystemDmaTransmitCreate 関数 (sercx.h)

[アーティクル]
03/08/2024

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

構文

NTSTATUS SerCx2SystemDmaTransmitCreate(
  [in]           WDFDEVICE                          Device,
  [in]           PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES             Attributes,
  [out]          SERCX2SYSTEMDMATRANSMIT            *SystemDmaTransmit
);

パラメーター

[in] Device

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

[in] SystemDmaTransmitConfig

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

[in, optional] Attributes

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

[out] SystemDmaTransmit

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

戻り値

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

リターンコード	説明
STATUS_INVALID_DEVICE_REQUEST	system-DMA-transmit オブジェクトは、以前の SerCx2SystemDmaTransmitCreate 呼び出しから既に存在します。または、 SerCx2CustomTransmitCreate メソッドの以前の呼び出しからカスタム送信オブジェクトが存在します。または、 SerCx2CustomReceiveCreate メソッドの以前の呼び出しからカスタム受信オブジェクトが存在します。または SerCx2PioTransmitCreate は、PIO-transmit オブジェクトを作成するためにまだ呼び出されていません。
STATUS_INFO_LENGTH_MISMATCH	Config->Size の値が sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG) と等しくありません。
STATUS_INVALID_PARAMETER	パラメーター値が無効です。
STATUS_INSUFFICIENT_RESOURCES	system-DMA-transmit オブジェクトを作成するために使用できるリソースが不足しています。

注釈

シリアルコントローラードライバーでは、このメソッドを使用して、システム DMA 送信オブジェクトを作成できます。 SerCx2 では、このオブジェクトを使用してシステム DMA 送信トランザクションを実行します。これは、システム DMA コントローラーを使用して、送信するシリアルコントローラーにデータを書き込むトランザクションです。

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

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

SerCx2SystemDmaTransmitCreate を呼び出す前に、シリアルコントローラードライバーは SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT 関数を呼び出して、SystemDmaTransmitConfig が指すSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG構造体を初期化する必要があります。この関数は、構造体の次のメンバーを 0 に設定します。

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
[排他]

必要に応じて、シリアルコントローラードライバーは、初期化関数が返された後、これらのメンバーのいずれかを 0 以外の値に設定できます。ただし、便宜上、 SerCx2SystemDmaTransmitCreate では、これらのメンバーが 0 の場合、次の既定値が使用されます。

MaximumScatterGatherFragments が 0 の場合、SerCx2 は散布/収集リスト内の要素の最大数を ((ULONG)-1) に設定します。
MinimumTransferUnitOverride が 0 の場合、SerCx2 は最小転送単位を既定値に設定します。これは、システム DMA コントローラーのDMA_ADAPTER構造体で指定されます。この構造体の詳細については、「 WdfDmaEnablerWdmGetDmaAdapter」を参照してください。
DmaAlignment が 0 の場合、SerCx2 はアラインメント値を最小転送単位に設定します。 MinimumTransferUnitOverride が 0 の場合、既定の最小転送単位が使用されます。
MinimumTransactionLength が 0 の場合、SerCx2 はトランザクションの最小長を 1 バイトに設定します。
Exclusive が 0 (FALSE) の場合、排他モードは無効になります。

呼び出し元のドライバーが Exclusive を TRUE に設定する場合、 MinimumTransferUnitOverride、 DmaAlignment、 および MinimumTransactionLength メンバーは 0 である必要があります。詳細については、「 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG」を参照してください。

実装されたコールバック関数の指定された組み合わせが無効な場合、 SerCx2SystemDmaTransmitCreate は失敗し、STATUS_INVALID_PARAMETERを返します。ドライバーは、 EvtSerCx2SystemDmaTransmitDrainFifo、 EvtSerCx2SystemDmaTransmitCancelDrainFifo、 EvtSerCx2SystemDmaTransmitPurgeFifo 関数のいずれかを実装する必要があります。

オプションとして、シリアルコントローラードライバーは Attributes パラメーターを使用して、system-DMA-transmit オブジェクトのコンテキストを作成し、削除のためにオブジェクトを準備するために呼び出される EvtCleanupCallback 関数と EvtDestroyCallback 関数へのポインターを指定できます。詳細については、「 WDF_OBJECT_ATTRIBUTES」を参照してください。

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

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

要件

要件	値
サポートされている最小のクライアント	Windows 8.1以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	sercx.h
IRQL	PASSIVE_LEVEL