SerCx2 カスタム-送信トランザクション
一部のシリアル コントローラー ハードウェアは、シリアル コントローラーにデータを書き込むための PIO またはシステム DMA 以外のデータ転送メカニズムを実装する場合があります。 シリアル コントローラー ドライバーは、カスタム送信トランザクションをサポートして、このデータ転送メカニズムを SerCx2 で使用できるようにすることができます。
カスタム送信トランザクションを開始するには、SerCx2 はドライバーの EvtSerCx2CustomTransmitTransactionStart イベントコールバック関数を呼び出し、書き込み (IRP_MJ_WRITE) リクエストとトランザクションの書き込みバッファの説明をパラメータとして提供します。 この呼び出しでは、関数はトランザクションを開始して返します。 その後、ドライバーはトランザクションを完了し、書き込み要求を完了する必要があります。
カスタム送信オブジェクトの作成
SerCx2 がシリアル コントローラー ドライバーの EvtSerCx2CustomTransmitTransactionXxx** 関数のいずれかを呼び出す前に、ドライバーは SerCx2CustomTransmitTransactionCreate メソッドを呼び出して、これらの関数を SerCx2 に登録する必要があります。 このメソッドは、ドライバーの EvtSerCx2CustomTransmitTransactionXxx** 関数へのポインターを含む SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG 構造体へのポインターを入力パラメーターとして受け取ります。
ドライバーは、次の関数を実装する必要があります。
オプションとして、ドライバーは次の関数のいずれかまたは両方を実装できます。
SerCx2CustomTransmitTransactionCreate メソッドは、カスタム送信オブジェクトを作成し、呼び出し元ドライバーにこのオブジェクトへの SERCX2CUSTOMTRANSMITTRANSACTION ハンドルを提供します。 ドライバーの EvtSerCx2CustomTransmitTransactionXxx** 関数はすべて、このハンドルを最初のパラメーターとして受け取ります。 次の SerCx2 メソッドは、このハンドルを最初のパラメーターとして受け取ります。
ハードウェアの初期化とクリーンアップ
一部のシリアル コントローラー ドライバーでは、カスタム送信トランザクションの開始時にシリアル コントローラー ハードウェアを初期化したり、トランザクションの終了時にシリアル コントローラーのハードウェア状態をクリーンアップしたりする必要があります。
ドライバーが EvtSerCx2CustomTransmitTransactionInitialize イベント コールバック関数を実装する場合、SerCx2 はこの関数を呼び出して、トランザクションを開始する前にシリアル コントローラーを初期化します。 EvtSerCx2CustomTransmitTransactionInitialize 関数を実装する場合、SerCx2CustomTransmitTransactionInitializeComplete メソッドを呼び出して、ドライバーがシリアル コントローラーの初期化を完了したときに SerCx2 に通知する必要があります。
ドライバーが EvtSerCx2CustomTransmitTransactionCleanup イベント コールバック関数を実装する場合、SerCx2 はこの関数を呼び出して、トランザクションの終了後にハードウェアの状態をクリーンアップします。 EvtSerCx2CustomTransmitTransactionInitialize 関数を実装する場合、SerCx2CustomTransmitTransactionCleanupComplete メソッドを呼び出して、ドライバーがシリアル コントローラーのクリーンアップを完了したときに SerCx2 に通知する必要があります。
要求オブジェクトへのアクセス
カスタム送信トランザクションを開始するために、SerCx2 はドライバーの EvtSerCx2CustomTransmitTransactionStart 関数を呼び出し、関連付けられている書き込み要求 (WDFREQUEST オブジェクト ハンドルにカプセル化) をパラメーターとしてこの関数に渡します。 ドライバーは、トランザクションが完了したときにこの要求を完了する WdfRequestComplete などのメソッドを呼び出す役割を担います。 要求をすぐに完了できない限り、EvtSerCx2CustomTransmitTransactionStart 関数が返される前に、ドライバーは WdfRequestMarkCancelableEx などのメソッドを呼び出して要求をキャンセル可能としてマークする必要があります。
シリアル コントローラー ドライバーは、WdfRequestRetrieveInputBuffer などのメソッドを使用して、書き込み要求のデータ バッファーにアクセスすることはできません。 代わりに、ドライバーは、このバッファーにアクセスするために EvtSerCx2CustomTransmitTransactionStart 関数に渡される Mdl、Offset、Length パラメーター値を使用する必要があります。
カスタム送信トランザクション中に、ドライバーは、要求オブジェクトにアタッチされているコンテキストでトランザクションに関する情報の格納が必要になる場合があります。 その場合、ドライバーの EvtDriverDeviceAdd イベント コールバック関数は、WdfDeviceInitSetRequestAttributes メソッドを呼び出して、要求オブジェクトに使用する属性を設定できます。 これらの属性には、要求コンテキストに使用する名前と割り当てサイズが含まれます。 この呼び出しで指定された要求属性は、SerCx2InitializeDevice メソッドの呼び出しでドライバーが指定する要求属性と一致する必要があります。 これらの属性は、ドライバーが SerCx2InitializeDevice に渡す SERCX2_CONFIG 構造体の RequestAttributes メンバーで指定されます。 詳細については、「SERCX2_CONFIG」を参照してください。
シリアル コントローラー ドライバーがカスタム送信トランザクションの開始時に受信する書き込み要求の場合、ドライバー フレームワークによって割り当てられた要求コンテキストは初期化されていません。 ドライバーは、ベスト プラクティスとして、RtlZeroMemory ルーチンを呼び出して、この要求コンテキストをすべてのゼロに初期化する必要があります。