HW_BUILDIOコールバック関数 (storport.h)

  • [アーティクル]

HwStorBuildIo ルーチンは、共有システム データ構造への同期されていないアクセス権を持つ SRB を HwStorStartIo に渡す前に処理します。

構文

HW_BUILDIO HwBuildio;

BOOLEAN HwBuildio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

パラメーター

DeviceExtension

HBA 記憶域ごとのミニポート ドライバーへのポインター。

Srb

処理する SCSI 要求ブロック (SRB) へのポインター。

戻り値

HwStorBuildIo はTRUE を 返し、StorPort が LUN を I/O を受信する準備ができていると判断した場合、StorPort が HwStorStartIo ルーチンを呼び出す必要があることを呼び出し元に通知します。 HwStorBuildIo はFALSE を 返し、SRB を HwStorStartIo に渡してはならないことを呼び出し元に通知します。 このような場合、ミニポート ドライバーは、通知の種類が RequestCompleteで StorPortNotification を呼び出すことによって SRB を完了する必要があります。 これは、SRB 構造体の TimeOutValue フィールドで指定されたタイムアウトの前に SRB が完了している限り、HwStorBuildIo またはミニポート ドライバー内の他の場所で実行できます。

注釈

HwStorBuildIo という名前は、HW_INITIALIZATION_DATA構造体の HwBuildIo メンバーによって指されるミニポート関数のプレースホルダーにすぎません。 このルーチンの実際のプロトタイプは、 Storport.h で次のように定義されています。

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

ポート ドライバーは、スピン ロックを保持せずに DISPATCH IRQL で HwStorBuildIo ルーチンを呼び出します。 このため、HwStorBuildIo では、StorPortAllocatePool を使用したメモリ割り当てと StorPortAcquireSpinLock による相互除外が許可されます。 マルチプロセッサ環境では、一度に複数 の HwStorBuildIo をアクティブにできるため、ミニポート ドライバーはシステム リソースへのアクセスを同期するために必要です。これは、 HwStorBuildIo の複数のインスタンスが任意の時点でアクティブになっている場合に競合が発生する可能性があります。

HwStorStartIo ではなく HwStorBuildIo で時間のかかる I/O セットアップ アクティビティを完了すると、ミニポート ドライバーによって I/O コンカレンシーが向上し、I/O スループットが向上します。 最高のパフォーマンスを得るために、ミニポート ドライバーは、可能な限り短い時間で HwStorStartIo 経由で HBA に要求を送信できるように 、HwStorBuildIo で可能な限り多くの前処理を行う必要があります。 前処理されたデータと状態は、 DeviceExtension または SrbExtension 構造体のいずれかに格納できます。 ロックが保持されていないので、 DeviceExtension の一意の部分に対する変更のみを行う必要があります。 HwStorBuildIo と HwStorStartIo は 、次の Srb 関数型を受け取ります。

  • SRB_FUNCTION_EXECUTE_SCSI: 指定したバス/ターゲット/lun に CDB を送信します。

    • Srb-DataTransferLength> はすべての Cdbs に対して有効です。
    • Srb-DataBuffer> は、読み取りと書き込みの要求に 対して NULL です 。 関連付けられたデータにアクセスするには、 StorPortGetScatterGatherList (Dma 転送の場合) または StorPortGetSystemAddress (プログラム制御 I/O の場合) を使用して、散布図の一覧またはバッファーの仮想アドレスを取得します。 他の要求の場合、Srb-Databuffer> は Srb に関連付けられているデータを指します。
    • Srb-PathId> は有効であり、 StorPortNotification (BusChange) の Storport に指定された pathid を表します。 ミニポート ドライバーのライターは、ミニポート内のバスのテーブルのインデックスとして pathid を使用する必要があります。
    • Srb-TargetId> と Srb-Lun> は有効です。

  • SRB_FUNCTION_IO_CONTROL: ミニポートが定義されています。

    • 要求元によって設定されている場合、Srb-DataTransferLength> と Srb-DataBuffer> は有効です。
    • Srb-PathId>、Srb-TargetId>、および Srb-Lun> はすべて有効です。

  • SRB_FUNCTION_RESET_LOGICAL_UNIT: 指定した論理ユニットをリセットします (デバイスが可能な場合)。

    • Srb-DataTransferLength> と Srb-DataBuffer> が無効です。
    • Srb-PathId>、Srb-TargetId>、および Srb-Lun> はすべて有効です。

  • SRB_FUNCTION_RESET_DEVICE: 指定した Scsi ターゲットをリセットします。

    • Srb-DataTransferLength> および Srb-DataBuffer>、Srb-Lun> は無効です。
    • Srb-PathId> と Srb-TargetId> は有効です。

  • SRB_FUNCTION_RESET_BUS: 指定した SCSI バス上のすべてのターゲットをリセットします。

    • Srb-PathId> のみが有効です。

  • SRB_FUNCTION_FLUSH: キャッシュされたすべてのデータをフラッシュするようにミニポート ドライバーに指示します。

    • ミニポート ドライバーによって実行されるのは、PORT_CONFIGURATION_INFORMATION構造で CachesData == TRUE を設定した場合のみです。
    • Srb-PathId>、Srb-TargetId>、および Srb-Lun> はすべて有効です。

  • SRB_FUNCTION_SHUTDOWN: ミニポート ドライバーに対して、キャッシュされているすべてのデータ準備をフラッシュしてシャットダウンするように指示します。

    • ミニポート ドライバーによって実行されるのは、PORT_CONFIGURATION_INFORMATION構造で CachesData == TRUE を設定した場合のみです。
    • Srb-PathId>、Srb-TargetId>、および Srb-Lun> はすべて有効です。

  • SRB_FUNCTION_DUMP_POINTERS: ミニポート ドライバーがクラッシュ ダンプと休止状態をサポートするために必要な情報を提供します。

    • この要求は、クラッシュ ダンプ データを保持するディスクを制御するために使用される Storport 仮想ミニポート ドライバーに送信されます。 Windows 8以降、仮想以外のミニポート ドライバーは、必要に応じてこの要求を受け取ることができます。
    • Srb-PathId>、Srb-TargetId>、および Srb-Lun> はすべて有効です。

  • SRB_FUNCTION_FREE_DUMP_POINTERS: Windows 8以降、この要求はミニポートに送信され、SRB_FUNCTION_DUMP_POINTERS要求中に割り当てられたリソースを解放します。

    • Srb-PathId>、Srb-TargetId>、および Srb-Lun> はすべて有効です。

Windows 8以降、Srb パラメーターは SCSI_REQUEST_BLOCK または STORAGE_REQUEST_BLOCK を指す場合があります。 Srb の Function フィールドの関数識別子がSRB_FUNCTION_STORAGE_REQUEST_BLOCK場合、SRB はSTORAGE_REQUEST_BLOCK要求構造体です。

このミニポート ドライバー ルーチンで安全に実行できることとできないことの詳細については、「 非同期 HwStorBuildIo ルーチン」を参照してください。

例

HwStorBuildIo コールバック関数を定義するには、まず、定義するコールバック関数の種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数の種類のセットが用意されています。 コールバック関数の種類を使用して関数を宣言すると、ドライバー、静的ドライバー検証ツール (SDV)、およびその他の検証ツールのコード分析でエラーが検出され、Windows オペレーティング システム用のドライバーを記述するための要件になります。

たとえば、MyHwBuildIo という名前の HwStorBuildIo コールバック ルーチンを定義するには、次のコード例に示すように、HW_BUILDIO型を使用します。

HW_BUILDIO MyHwBuildIo;

次に、コールバック ルーチンを次のように実装します。

_Use_decl_annotations_
BOOLEAN
MyHwBuildIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

HW_BUILDIO関数型は、Storport.h ヘッダー ファイルで定義されています。 コード分析ツールを実行するときにエラーをより正確に識別するには、 Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations注釈を使用すると、ヘッダー ファイル内のHW_BUILDIO関数型に適用される注釈が確実に使用されます。 関数宣言の要件の詳細については、「 Storport ドライバーの関数ロール型を使用した関数の宣言」を参照してください。 Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。

要件

要件 値
対象プラットフォーム ユニバーサル
Header storport.h (Storport.h を含む)
IRQL DISPATCH_LEVEL (「解説」セクションを参照)。

こちらもご覧ください

HwStorStartIo

PORT_CONFIGURATION_INFORMATION

SCSI_REQUEST_BLOCK

STORAGE_REQUEST_BLOCK

StorPortAcquireSpinLock

StorPortAllocatePool

StorPortNotification