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

[アーティクル]
02/26/2024

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 ルーチンを呼び出します。このため、 StorPortAllocatePool を使用したメモリ割り当てと 、StorPortAcquireSpinLock による相互除外は HwStorBuildIo で許可されます。マルチプロセッサ環境では、一度に複数 の 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 (「解説」セクションを参照)。