IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

Artículo
08/08/2023

El controlador de una función virtual PCI Express (PCIe) emite un IOCTL_VPCI_READ_BLOCK

Código de control de E/S (IOCTL) para leer datos de un bloque de configuración de VF. El controlador emite este IOCTL al controlador inferior siguiente en la pila de controladores.

Nota El controlador de una VF PCIe emite esta solicitud IOCTL en un dispositivo que admite la interfaz de virtualización de E/S raíz única (SR-IOV).

Cuando el controlador emite el IOCTL_VPCI_READ_BLOCK IOCTL, el controlador debe seguir estos pasos:

Preparar una estructura de paquetes de solicitud de E/S

Preparar una estructura de ubicación de pila de E/S

Emisión de la solicitud IOCTL

Resultados de finalización de solicitudes IOCTL

Para obtener más información sobre cómo emitir ICTLs entre controladores en modo kernel, vea Crear solicitudes IOCTL en controladores.

Código principal

IRP_MJ_DEVICE_CONTROL

Bloque de estado

Irp-IoStatus.Status> se establece en STATUS_SUCCESS si la solicitud se realiza correctamente.

De lo contrario, estado de la condición de error adecuada como código NTSTATUS.

Para obtener más información, vea [XREF-LINK:NTSTATUS Values].

Comentarios

Preparar una estructura de paquetes de solicitud de E/S

El controlador debe asignar o reutilizar primero un paquete de solicitud de E/S (IRP). Puede usar la función IoBuildDeviceIoControlRequest para asignar específicamente un IRP de IOCTL. También puede usar funciones de creación e inicialización de IRP de uso general, como IoAllocateIrp, IoReuseIrp o IoInitializeIrp. Para obtener más información sobre la asignación de IRP, consulte Creación de IRP para controladores de Lower-Level.

A continuación, el controlador debe establecer los miembros de la estructura IRP como se describe en la tabla siguiente.

Miembro IRP	Valor
UserBuffer	Dirección del búfer asignado por el autor de la llamada que contendrá los datos de configuración que se van a leer.
UserEvent	Dirección del objeto de evento que se inicializó en la llamada a la función KeInitializeEvent . Nota Si no se requiere la finalización asincrónica de la solicitud IOCTL, este miembro debe establecerse en NULL. Para obtener más información, vea Crear solicitudes IOCTL en controladores.
UserIosb	Dirección de una estructura de IO_STATUS_BLOCK asignada por el autor de la llamada. El controlador inferior actualiza esta estructura para indicar el estado final de la solicitud de E/S.

Preparar una estructura de ubicación de pila de E/S

El controlador llama a la función IoGetNextIrpStackLocation para acceder a la ubicación de pila de E/S del controlador inferior. Esta función devuelve un puntero a una estructura IO_STACK_LOCATION que contiene los parámetros de la ubicación de la pila de E/S.

A continuación, el controlador debe establecer los miembros de la estructura IO_STACK_LOCATION tal y como se describe en la tabla siguiente.

miembro de IO_STACK_LOCATION	Valor
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_READ_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Puntero a una estructura de VPCI_READ_BLOCK_INPUT . El controlador da formato a esta estructura con los parámetros de la solicitud de E/S de IOCTL_VPCI_READ_BLOCK .
I Parameters.DeviceIoControl.InputBufferLength	Tamaño, en bytes, de la estructura VPCI_READ_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	Tamaño, en bytes, del búfer asignado por el autor de la llamada que contendrá los datos de configuración que se van a leer. Nota Este valor debe ser el mismo que el valor del miembro BytesRequested de la estructura VPCI_READ_BLOCK_INPUT .

Emisión de la solicitud IOCTL

Para emitir esta solicitud IOCTL, el controlador llama a la función IoCallDriver para pasar la solicitud al controlador inferior siguiente en la pila de controladores. El controlador establece los parámetros de IoCallDriver como se describe en la tabla siguiente.

Parámetro IoCallDriver	Valor
DeviceObject	Objeto de dispositivo del controlador inferior.
Irp	Dirección del IRP que se asignó e inicializó anteriormente. Para obtener más información, vea Preparar una estructura de paquetes de solicitud de E/S (IRP).

Resultados de finalización de solicitudes IOCTL

Cuando se completa la solicitud IOCTL_VPCI_READ_BLOCK IOCTL, el miembro Status de la estructura de IO_STATUS_BLOCK asignada por el autor de la llamada se establece en uno de los valores de la tabla siguiente.

Valor de estado	Descripción
STATUS_SUCCESS	El IOCTL se completó correctamente.
STATUS_PENDING	El IOCTL no se ha completado. El controlador debe llamar a la función KeWaitForSingleObject para colocar el subproceso actual en un estado de espera. El controlador establece el parámetro Object en la dirección de un objeto de evento que se inicializó en la llamada a la función KeInitializeEvent . El evento se señala cuando se completa la solicitud IOCTL. Una vez señalado el evento, el subproceso reanuda la ejecución.
STATUS_BUFFER_TOO_SMALL	El miembro Parameters.DeviceIoControl.InputBufferLength o el miembro Parameters.DeviceIoControl.OutputBufferLength se estableció en un valor menor que el tamaño de búfer necesario.

Si la solicitud se completó correctamente, el miembro Information de la estructura IO_STATUS_BLOCK se establece en el número de bytes leídos. De lo contrario, el miembro Information se establece en cero.

Cuando se emite el IOCTL_VPCI_READ_BLOCK IOCTL, se notifica al controlador de la función física PCIe (PF) que devuelva los datos del bloque de configuración de VF especificado.

Nota El sistema operativo reserva y administra los recursos necesarios para la finalización correcta de este IOCTL.

Un bloque de configuración de VF se usa para la comunicación backchannel entre los controladores del PCIe PF y un VF en un dispositivo que admite la interfaz SR-IOV. Los datos de un bloque de configuración de VF se pueden intercambiar entre los siguientes controladores:

Controlador VF, que se ejecuta en el sistema operativo invitado. Este sistema operativo se ejecuta dentro de una partición secundaria de Hyper-V.
Controlador PF, que se ejecuta en el sistema operativo de administración.
Este sistema operativo se ejecuta dentro de la partición primaria de Hyper-V.

El uso del bloque de configuración de VF y el formato de sus datos de configuración se definen mediante el proveedor de hardware independiente (IHV) del dispositivo. Los datos de configuración solo los usan los controladores de PF y VF.

Nota El IOCTL_VPCI_READ_BLOCK IOCTL ofrece una alternativa asincrónica a la función ReadVfConfigBlock .

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con Windows Server 2012 y versiones posteriores de Windows.
Encabezado	vpci.h (incluye Wdm.h)
IRQL	DISPATCH_LEVEL