IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Artículo
08/08/2023

El controlador de una función virtual PCI Express (PCIe) emite un código de control de E/S (IOCTL) de IOCTL_VPCI_WRITE_BLOCK para escribir datos en 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_WRITE_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 rutina IoBuildDeviceIoControlRequest para asignar específicamente un IRP de IOCTL. También puede usar rutinas 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	NULL
UserEvent	Dirección del objeto de evento que se inicializó en la llamada a la rutina 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 rutina 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_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Puntero a una estructura de VPCI_WRITE_BLOCK_INPUT . El controlador da formato a esta estructura con los parámetros de la solicitud de E/S de IOCTL_VPCI_WRITE_BLOCK .
I Parameters.DeviceIoControl.InputBufferLength	Tamaño, en bytes, de la estructura VPCI_WRITE_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	Cero

Emisión de la solicitud IOCTL

Para emitir esta solicitud IOCTL, el controlador llama a la rutina 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_WRITE_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 rutina 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 rutina 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 se estableció en un valor menor que el tamaño, en bytes, de la estructura VPCI_WRITE_BLOCK_INPUT .

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

Cuando se emite el IOCTL_VPCI_WRITE_BLOCK IOCTL, se notifica al controlador de la función física PCIe (PF) que escriba los datos en el 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. El controlador PF asigna un bloque de configuración para cada VF dentro de bloques sin usar del espacio de configuración PCI del dispositivo.

En cuanto se asigna el bloque de configuración de VF, los datos de configuración de VF se pueden intercambiar de forma protegida 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 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_WRITE_BLOCK IOCTL ofrece una alternativa asincrónica a la rutina WriteVfConfigBlock .

Requisitos

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