IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

Artículo
02/07/2025

El controlador para una función virtual PCI Express (PCIe) emite una 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 Esta solicitud de IOCTL la emite el controlador de un VF PCIe 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 del de solicitud de IOCTL

resultados de finalización de solicitudes de IOCTL

Para obtener más información sobre cómo emitir ICTLs entre controladores en modo kernel, consulte Creación de 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, status to the appropriate error condition as a NTSTATUS code.

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

Observaciones

preparar una estructura de paquetes de solicitud de E/S

El controlador primero debe asignar o reutilizar 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, IoReuseIrpo 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 tal 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 de	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 Creación de solicitudes de 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 de 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 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.
IParameters.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 de IOCTL, el controlador llama a la función IoCallDriver para pasar la solicitud al controlador siguiente inferior de la pila de controladores. El controlador establece los parámetros de ioCallDriver tal 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, consulte Preparación de una estructura de paquetes de solicitud de E/S (IRP).

resultados de finalización de solicitudes de IOCTL

Cuando se completa la solicitud IOCTL_VPCI_READ_BLOCK IOCTL, el Estado miembro de la estructura 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 poner 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 indica cuando se completa la solicitud IOCTL. Una vez que se señala 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 inferior al tamaño de búfer necesario.

Si la solicitud se completó correctamente, el Información miembro de la estructura IO_STATUS_BLOCK se establece en el número de bytes leídos. De lo contrario, el miembro de Information está establecido 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 VF especificado.

Nota El sistema operativo reserva y administra los recursos necesarios para completar correctamente 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 controladores siguientes:

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 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 The IOCTL_VPCI_READ_BLOCK IOCTL ofrece una alternativa asincrónica a la función ReadVfConfigBlock.

Requisitos

Requisito	Valor
cliente mínimo admitido	Compatible con Windows Server 2012 y versiones posteriores de Windows.
encabezado de	vpci.h (include Wdm.h)
irQL	DISPATCH_LEVEL