IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Articolo
02/29/2024

Il driver per una funzione virtuale PCI Express (PCIe) genera un codice di controllo I/O (IOCTL) IOCTL_VPCI_WRITE_BLOCK per scrivere dati in un blocco di configurazione VF. Il driver rilascia questo IOCTL al driver inferiore successivo nello stack di driver.

Nota Questa richiesta IOCTL viene inviata dal driver di un pcIe VF in un dispositivo che supporta l'interfaccia di virtualizzazione I/O radice singola (SR-IOV).

Quando il driver rilascia il IOCTL_VPCI_WRITE_BLOCK IOCTL, il driver deve seguire questa procedura:

Preparazione di una struttura di pacchetti di richiesta di I/O

Preparazione di una struttura di posizione dello stack di I/O

Emissione della richiesta IOCTL

Risultati del completamento della richiesta IOCTL

Per altre informazioni sull'emissione di IOCTLs tra driver in modalità kernel, vedere Creazione di richieste IOCTL nei driver.

Codice principale

IRP_MJ_DEVICE_CONTROL

Blocco dello stato

Irp-IoStatus.Status> è impostato su STATUS_SUCCESS se la richiesta ha esito positivo.

In caso contrario, stato alla condizione di errore appropriata come codice NTSTATUS.

Per altre informazioni, vedere [XREF-LINK:NTSTATUS Values].

Commenti

Preparazione di una struttura di pacchetti di richiesta di I/O

Il driver deve prima allocare o riutilizzare un pacchetto di richiesta di I/O . È possibile usare la routine IoBuildDeviceIoControlRequest per allocare in modo specifico un IOCTL IRP. È anche possibile usare routine di creazione e inizializzazione di IRP per utilizzo generico, ad esempio IoAllocateIrp, IoReuseIrp o IoInitializeIrp. Per altre informazioni sull'allocazione di IRP, vedere Creazione di provider di integrazione per i driver Lower-Level.

Il driver deve quindi impostare i membri della struttura IRP come descritto nella tabella seguente.

Membro IRP	Valore
UserBuffer	NULL
UserEvent	Indirizzo dell'oggetto evento inizializzato nella chiamata alla routine KeInitializeEvent . Nota Se il completamento asincrono della richiesta IOCTL non è obbligatorio, questo membro deve essere impostato su NULL. Per altre informazioni, vedere Creazione di richieste IOCTL nei driver.
UserIosb	Indirizzo di una struttura di IO_STATUS_BLOCK allocata dal chiamante. Questa struttura viene aggiornata dal driver inferiore per indicare lo stato finale della richiesta di I/O.

Preparazione di una struttura di posizione dello stack di I/O

Il driver chiama la routine IoGetNextIrpStackLocation per accedere alla posizione dello stack I/O del driver inferiore. Questa funzione restituisce un puntatore a una struttura IO_STACK_LOCATION che contiene i parametri per la posizione dello stack di I/O.

Il driver deve quindi impostare i membri nella struttura IO_STACK_LOCATION come descritto nella tabella seguente:

membro IO_STACK_LOCATION	Valore
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Puntatore a una struttura VPCI_WRITE_BLOCK_INPUT . Il driver formatta questa struttura con i parametri per la richiesta di I /O IOCTL_VPCI_WRITE_BLOCK.
IParameters.DeviceIoControl.InputBufferLength	Dimensione, in byte, della struttura VPCI_WRITE_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	Zero

Emissione della richiesta IOCTL

Per eseguire questa richiesta IOCTL, il driver chiama la routine IoCallDriver per passare la richiesta al driver inferiore successivo nello stack di driver. Il driver imposta i parametri di IoCallDriver come descritto nella tabella seguente.

Parametro IoCallDriver	Valore
DeviceObject	Oggetto dispositivo del driver inferiore.
Irp	Indirizzo dell'IRP allocato e inizializzato in precedenza. Per altre informazioni, vedere Preparazione di una struttura IRP (Request Packet) di I/O.

Risultati del completamento della richiesta IOCTL

Al termine della richiesta IOCTL_VPCI_WRITE_BLOCK IOCTL, il membro Status della struttura IO_STATUS_BLOCK allocata dal chiamante viene impostato su uno dei valori della tabella seguente:

Valore di stato	Descrizione
STATUS_SUCCESS	L'IOCTL è stato completato correttamente.
STATUS_PENDING	IOCTL non è stato completato. Il driver deve chiamare la routine KeWaitForSingleObject per inserire il thread corrente in uno stato di attesa. Il driver imposta il parametro Object sull'indirizzo di un oggetto evento inizializzato nella chiamata alla routine KeInitializeEvent . L'evento viene segnalato quando viene completata la richiesta IOCTL. Dopo aver segnalato l'evento, il thread riprende l'esecuzione.
STATUS_BUFFER_TOO_SMALL	Il membro Parameters.DeviceIoControl.InputBufferLength è stato impostato su un valore minore delle dimensioni, in byte, della struttura VPCI_WRITE_BLOCK_INPUT .

Se la richiesta è stata completata correttamente, il membro Informazioni della struttura IO_STATUS_BLOCK viene impostato sul numero di byte scritti. In caso contrario, il membro Informazioni è impostato su zero.

Quando viene emesso il IOCTL_VPCI_WRITE_BLOCK IOCTL, il driver della funzione fisica PCIe riceve una notifica per scrivere i dati nel blocco di configurazione VF specificato.

Nota Il sistema operativo riserva e gestisce le risorse necessarie per il completamento corretto di questo IOCTL.

Un blocco di configurazione VF viene usato per la comunicazione backchannel tra i driver del file PF PCIe e un VF in un dispositivo che supporta l'interfaccia SR-IOV. Il driver PF alloca un blocco di configurazione per ogni VF all'interno di blocchi inutilizzati dello spazio di configurazione PCI del dispositivo.

Non appena viene allocato il blocco di configurazione VF, i dati di configurazione VF possono essere scambiati in modo protetto tra i driver seguenti:

Driver VF, che viene eseguito nel sistema operativo guest. Questo sistema operativo viene eseguito all'interno di una partizione figlio Hyper-V.
Driver PF, che viene eseguito nel sistema operativo di gestione.
Questo sistema operativo viene eseguito all'interno della partizione padre hyper-V.

L'utilizzo del blocco di configurazione VF e il formato dei relativi dati di configurazione sono definiti dal fornitore hardware indipendente (IHV) del dispositivo. I dati di configurazione vengono usati solo dai driver di PF e VF.

Nota Il IOCTL_VPCI_WRITE_BLOCK IOCTL offre un'alternativa asincrona alla routine WriteVfConfigBlock .

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Server 2012 e versioni successive di Windows.
Intestazione	vpci.h (include Wdm.h)
IRQL	DISPATCH_LEVEL