IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

[アーティクル]
08/08/2023

PCI Express (PCIe) 仮想関数 (VF) のドライバーは、VF 構成ブロックにデータを書き込むために、IOCTL_VPCI_WRITE_BLOCK I/O 制御コード (IOCTL) を発行します。ドライバーは、ドライバースタック内の次の下位ドライバーにこの IOCTL を発行します。

メモこの IOCTL 要求は、単一ルート I/O 仮想化 (SR-IOV) インターフェイスをサポートするデバイス上の PCIe VF のドライバーによって発行されます。

ドライバーが IOCTL_VPCI_WRITE_BLOCK IOCTL を発行する場合、ドライバーは次の手順に従う必要があります。

カーネルモードドライバー間での IOCTL の発行の詳細については、「ドライバーでの IOCTL 要求の作成」を参照してください。

メジャーコード

IRP_MJ_DEVICE_CONTROL

ステータスブロック

要求が成功した場合、Irp-IoStatus.Status> はSTATUS_SUCCESSに設定されます。

それ以外の場合は、NTSTATUS コードとして適切なエラー条件の状態。

詳細については、「XREF-LINK:NTSTATUS 値」を参照してください。

注釈

I/O 要求パケット構造の準備

ドライバーは、最初に割り当てるか、I/O 要求パケット (IRP) を再利用する必要があります。 IoBuildDeviceIoControlRequest ルーチンを使用して、IOCTL IRP を具体的に割り当てることができます。 IoAllocateIrp、IoReuseIrp、IoInitializeIrp などの汎用 IRP の作成および初期化ルーチンを使用することもできます。 IRP の割り当ての詳細については、「 Lower-Level ドライバーの IRP の作成」を参照してください。

ドライバーは、次の表で説明するように IRP 構造体のメンバーを設定する必要があります。

IRP メンバー	値
UserBuffer	NULL
UserEvent	KeInitializeEvent ルーチンの呼び出しで初期化されたイベントオブジェクトのアドレス。メモ IOCTL 要求の非同期完了が不要な場合は、このメンバーを NULL に設定する必要があります。詳細については、「ドライバーでの IOCTL 要求の作成」を参照してください。
UserIosb	呼び出し元によって割り当てられた IO_STATUS_BLOCK構造体のアドレス。この構造体は、I/O 要求の最終的な状態を示すために下位ドライバーによって更新されます。

I/O スタック位置構造の準備

ドライバーは IoGetNextIrpStackLocation ルーチンを呼び出して、下位のドライバーの I/O スタックの場所にアクセスします。この関数は、I/O スタックの場所のパラメーターを含む IO_STACK_LOCATION 構造体へのポインターを返します。

ドライバーは、次の表で説明するように、IO_STACK_LOCATION 構造体のメンバーを設定する必要があります。

IO_STACK_LOCATION メンバー	値
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	VPCI_WRITE_BLOCK_INPUT構造体へのポインター。ドライバーは、 IOCTL_VPCI_WRITE_BLOCK I/O 要求のパラメーターを使用して、この構造体を書式設定します。
IParameters.DeviceIoControl.InputBufferLength	VPCI_WRITE_BLOCK_INPUT構造体のサイズ (バイト単位)。
Parameters.DeviceIoControl.OutputBufferLength	ゼロ

IOCTL 要求の発行

この IOCTL 要求を発行するために、ドライバーは IoCallDriver ルーチンを呼び出して、ドライバースタック内の次の下位ドライバーに要求を渡します。ドライバーは、次の表で説明するように IoCallDriver のパラメーターを設定します。

IoCallDriver パラメーター	値
DeviceObject	下位ドライバーのデバイスオブジェクト。
Irp	以前に割り当てられ、初期化された IRP のアドレス。詳細については、「 I/O 要求パケット (IRP) 構造体の準備」を参照してください。

IOCTL 要求の完了結果

IOCTL_VPCI_WRITE_BLOCK IOCTL 要求が完了すると、呼び出し元によって割り当てられたIO_STATUS_BLOCK構造体の Status メンバーは、次の表のいずれかの値に設定されます。

ステータス値	説明
STATUS_SUCCESS	IOCTL が正常に完了しました。
STATUS_PENDING	IOCTL が完了していません。ドライバーは、現在のスレッドを待機状態にするために KeWaitForSingleObject ルーチンを呼び出す必要があります。ドライバーは、KeInitializeEvent ルーチンの呼び出しで初期化されたイベントオブジェクトのアドレスに Object パラメーターを設定します。イベントは、IOCTL 要求が完了したときに通知されます。イベントが通知されると、スレッドは実行を再開します。
STATUS_BUFFER_TOO_SMALL	Parameters.DeviceIoControl.InputBufferLength メンバーは、VPCI_WRITE_BLOCK_INPUT構造体のサイズ (バイト単位) 未満の値に設定されました。

要求が正常に完了した場合、IO_STATUS_BLOCK構造体の Information メンバーは、書き込まれたバイト数に設定されます。それ以外の場合、 Information メンバーは 0 に設定されます。

IOCTL_VPCI_WRITE_BLOCK IOCTL が発行されると、PCIe 物理機能 (PF) のドライバーに、指定された VF 構成ブロックにデータを書き込むよう通知されます。

メモオペレーティングシステムは、この IOCTL を正常に完了するために必要なリソースを予約して管理します。

VF 構成ブロックは、PCIe PF のドライバーと、SR-IOV インターフェイスをサポートするデバイス上の VF との間のバックチャネル通信に使用されます。 PF ドライバーは、デバイスの PCI 構成領域の未使用のブロック内の各 VF の構成ブロックを割り当てます。

VF 構成ブロックが割り当てられるとすぐに、VF 構成データを次のドライバー間で保護された方法で交換できます。

ゲストオペレーティングシステムで実行される VF ドライバー。このオペレーティングシステムは、Hyper-V 子パーティション内で実行されます。
管理オペレーティングシステムで実行される PF ドライバー。
このオペレーティングシステムは、Hyper-V 親パーティション内で実行されます。

VF 構成ブロックの使用法とその構成データの形式は、デバイスの独立したハードウェアベンダー (IHV) によって定義されます。構成データは、PF と VF のドライバーによってのみ使用されます。

メモIOCTL_VPCI_WRITE_BLOCK IOCTL は、WriteVfConfigBlock ルーチンに代わる非同期の代替手段を提供します。

要件

要件	値
サポートされている最小のクライアント	Windows Server 2012以降のバージョンの Windows で使用できます。
Header	vpci.h (Wdm.h を含む)
IRQL	DISPATCH_LEVEL