IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

Artigo
08/08/2023

O driver de uma VF (função virtual) PCI Express (PCIe) emite um IOCTL_VPCI_READ_BLOCK

IOCTL (código de controle de E/S) para ler dados de um bloco de configuração de VF. O driver emite esse IOCTL para o próximo driver inferior 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) raiz única.

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

Preparando uma estrutura de pacotes 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 pacotes 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 função IoBuildDeviceIoControlRequest para alocar especificamente um IRP IOCTL. Você também pode usar funções de inicialização e criaçã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	O endereço do buffer alocado pelo chamador que conterá os dados de configuração a serem lidos.
UserEvent	O endereço do objeto de evento que foi inicializado na chamada para a função 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 função 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_READ_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Um ponteiro para uma estrutura VPCI_READ_BLOCK_INPUT . O driver formata essa estrutura com os parâmetros para a solicitação de E/ S IOCTL_VPCI_READ_BLOCK .
IParameters.DeviceIoControl.InputBufferLength	O tamanho, em bytes, da estrutura VPCI_READ_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	O tamanho, em bytes, do buffer alocado pelo chamador que conterá os dados de configuração a serem lidos. Nota Esse valor deve ser o mesmo que o valor do membro BytesRequested da estrutura VPCI_READ_BLOCK_INPUT .

Emitindo a solicitação IOCTL

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

Parâmetro IoCallDriver	Valor
DeviceObject	O objeto do 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_READ_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 função 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 função 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 ou o membro Parameters.DeviceIoControl.OutputBufferLength foi definido como um valor menor que o tamanho do buffer necessário.

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 que foram lidos. Caso contrário, o membro Informações será definido como zero.

Quando o IOCTL_VPCI_READ_BLOCK IOCTL é emitido, o driver da função física PCIe (PF) é notificado para retornar os dados do 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. Os dados de um bloco de configuração de VF podem ser trocados 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_READ_BLOCK IOCTL oferece uma alternativa assíncrona à função ReadVfConfigBlock .

Requisitos

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