IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Artigo
08/08/2023

O driver de uma VF (função virtual) PCI Express (PCIe) emite um IOCTL_VPCI_WRITE_BLOCK IOCTL (código de controle de E/S) para gravar dados em um bloco de configuração de VF. O driver emite esse IOCTL para o driver mais baixo na pilha de driver.

Nota Essa solicitação IOCTL é emitida pelo driver de uma VF PCIe em um dispositivo que dá suporte à interface SR-IOV (virtualização de E/S de raiz única).

Quando o driver emite o IOCTL_VPCI_WRITE_BLOCK IOCTL, o driver deve seguir estas etapas:

Preparando uma estrutura de pacote de solicitação de E/S

Preparando uma estrutura de localização de pilha de E/S

Emitindo a solicitação IOCTL

Resultados da conclusão da solicitação IOCTL

Para obter mais informações sobre como emitir IOCTLs entre drivers no modo kernel, consulte Criando solicitações IOCTL em drivers.

Código principal

IRP_MJ_DEVICE_CONTROL

Bloco de status

Irp-IoStatus.Status será definido como STATUS_SUCCESS se a solicitação for bem-sucedida>.

Caso contrário, Status para a condição de erro apropriada como um código NTSTATUS.

Para obter mais informações, consulte [Valores XREF-LINK:NTSTATUS].

Comentários

Preparando uma estrutura de pacote de solicitação de E/S

O driver deve primeiro alocar ou reutilizar um IRP (pacote de solicitação de E/S). Você pode usar a rotina IoBuildDeviceIoControlRequest para alocar especificamente um IRP IOCTL. Você também pode usar rotinas de criação e inicialização de IRP de uso geral, como IoAllocateIrp, IoReuseIrp ou IoInitializeIrp. Para obter mais informações sobre alocação de IRP, consulte Criando IRPs para drivers de Lower-Level.

Em seguida, o driver deve definir os membros da estrutura IRP , conforme descrito na tabela a seguir.

Membro IRP	Valor
UserBuffer	NULL
UserEvent	O endereço do objeto de evento que foi inicializado na chamada para a rotina KeInitializeEvent . Nota Se a conclusão assíncrona da solicitação IOCTL não for necessária, esse membro deverá ser definido como NULL. Para obter mais informações, consulte Criando solicitações IOCTL em drivers.
UserIosb	O endereço de uma estrutura de IO_STATUS_BLOCK alocada pelo chamador. Essa estrutura é atualizada pelo driver inferior para indicar o status final da solicitação de E/S.

Preparando uma estrutura de localização de pilha de E/S

O driver chama a rotina IoGetNextIrpStackLocation para acessar o local da pilha de E/S do driver inferior. Essa função retorna um ponteiro para uma estrutura IO_STACK_LOCATION que contém os parâmetros para o local da pilha de E/S.

Em seguida, o driver deve definir os membros na estrutura IO_STACK_LOCATION conforme descrito na tabela a seguir:

membro IO_STACK_LOCATION	Valor
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Um ponteiro para uma estrutura VPCI_WRITE_BLOCK_INPUT . O driver formata essa estrutura com os parâmetros para a solicitação de E/S IOCTL_VPCI_WRITE_BLOCK .
IParameters.DeviceIoControl.InputBufferLength	O tamanho, em bytes, da estrutura VPCI_WRITE_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	Zero

Emitindo a solicitação IOCTL

Para emitir essa solicitação IOCTL, o driver chama a rotina IoCallDriver para passar a solicitação para o driver mais baixo na pilha de driver. O driver define os parâmetros de IoCallDriver conforme descrito na tabela a seguir.

Parâmetro IoCallDriver	Valor
DeviceObject	O objeto de dispositivo do driver inferior.
Irp	O endereço do IRP que foi alocado e inicializado anteriormente. Para obter mais informações, consulte Preparando uma estrutura de IRP (pacote de solicitação de E/S).

Resultados da conclusão da solicitação IOCTL

Quando o IOCTL_VPCI_WRITE_BLOCK solicitação IOCTL é concluído, o membro Status da estrutura de IO_STATUS_BLOCK alocada pelo chamador é definido como um dos valores na tabela a seguir.:

Valor de status	Descrição
STATUS_SUCCESS	O IOCTL foi concluído com êxito.
STATUS_PENDING	O IOCTL não foi concluído. O driver deve chamar a rotina KeWaitForSingleObject para colocar o thread atual em um estado de espera. O driver define o parâmetro Object como o endereço de um objeto de evento que foi inicializado na chamada para a rotina KeInitializeEvent . O evento é sinalizado quando a solicitação IOCTL é concluída. Depois que o evento é sinalizado, o thread retoma a execução.
STATUS_BUFFER_TOO_SMALL	O membro Parameters.DeviceIoControl.InputBufferLength foi definido como um valor menor que o tamanho, em bytes, da estrutura VPCI_WRITE_BLOCK_INPUT .

Se a solicitação for concluída com êxito, o membro Informações da estrutura IO_STATUS_BLOCK será definido como o número de bytes gravados. Caso contrário, o membro Informações será definido como zero.

Quando o IOCTL_VPCI_WRITE_BLOCK IOCTL é emitido, o driver da função física PCIe (PF) é notificado para gravar os dados no bloco de configuração de VF especificado.

Nota O sistema operacional reserva e gerencia os recursos necessários para a conclusão bem-sucedida deste IOCTL.

Um bloco de configuração de VF é usado para comunicação backchannel entre os drivers do PCIe PF e um VF em um dispositivo que dá suporte à interface SR-IOV. O driver PF aloca um bloco de configuração para cada VF em blocos não utilizados do espaço de configuração PCI do dispositivo.

Assim que o bloco de configuração do VF for alocado, os dados de configuração do VF poderão ser trocados de maneira protegida entre os seguintes drivers:

O driver VF, que é executado no sistema operacional convidado. Esse sistema operacional é executado em uma partição filho do Hyper-V.
O driver PF, que é executado no sistema operacional de gerenciamento.
Esse sistema operacional é executado dentro da partição pai do Hyper-V.

O uso do bloco de configuração do VF e o formato de seus dados de configuração são definidos pelo IHV (fornecedor independente de hardware) do dispositivo. Os dados de configuração são usados apenas pelos drivers do PF e do VF.

Nota O IOCTL_VPCI_WRITE_BLOCK IOCTL oferece uma alternativa assíncrona à rotina WriteVfConfigBlock .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível em Windows Server 2012 e versões posteriores do Windows.
Cabeçalho	vpci.h (inclua Wdm.h)
IRQL	DISPATCH_LEVEL