IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

Articolo
08/08/2023

Il driver per una funzione virtuale PCI Express (PCIe) genera un IOCTL_VPCI_READ_BLOCK

Codice di controllo I/O (IOCTL) per leggere i dati da 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_READ_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 funzione IoBuildDeviceIoControlRequest per allocare in modo specifico un IOCTL IRP. È anche possibile usare funzioni 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	Indirizzo del buffer allocato dal chiamante che conterrà i dati di configurazione da leggere.
UserEvent	Indirizzo dell'oggetto evento inizializzato nella chiamata alla funzione 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 funzione IoGetNextIrpStackLocation per accedere alla posizione dello stack di 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_READ_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Puntatore a una struttura VPCI_READ_BLOCK_INPUT . Il driver formatta questa struttura con i parametri per la richiesta di I/O IOCTL_VPCI_READ_BLOCK .
IParameters.DeviceIoControl.InputBufferLength	Dimensione, in byte, della struttura VPCI_READ_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	Dimensioni, in byte, del buffer allocato dal chiamante che conterrà i dati di configurazione da leggere. Nota Questo valore deve essere uguale al valore del membro BytesRequested della struttura VPCI_READ_BLOCK_INPUT .

Emissione della richiesta IOCTL

Per eseguire questa richiesta IOCTL, il driver chiama la funzione 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_READ_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 funzione 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 funzione 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 o parameters.DeviceIoControl.OutputBufferLength è stato impostato su un valore minore delle dimensioni del buffer necessarie.

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

Quando viene emesso il IOCTL_VPCI_READ_BLOCK IOCTL, il driver della funzione fisica PCIe riceve una notifica per restituire i dati dal 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. I dati di un blocco di configurazione VF possono essere scambiati 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_READ_BLOCK IOCTL offre un'alternativa asincrona alla funzione ReadVfConfigBlock .

Requisiti

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