IOCTL_VPCI_INVALIDATE_BLOCK IOCTL (vpci.h)

Artigo
02/07/2025

O driver de uma VF (função virtual) PCI Express (PCIe) emite o IOCTL_VPCI_INVALIDATE_BLOCK solicitação IOCTL para ser notificado sobre alterações nos dados em um ou mais blocos de configuração de VF. O driver é notificado sobre essas alterações quando o IOCTL é concluído. Depois de notificado, o driver deve assumir que todos os dados lidos anteriormente dos blocos de configuração de VF especificados se tornaram inválidos. Portanto, o driver deve atualizar seu cache lendo os dados do bloco de configuração novamente.

O driver emite esse IOCTL para o próximo driver inferior na pilha de driver.

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

Quando o driver emite o IOCTL_VPCI_INVALIDATE_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 o de solicitação IOCTL

resultados de 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].

Observações

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

O driver deve primeiro alocar ou reutilizar um pacote de solicitação de E/S (IRP). Você pode usar a rotina de 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 Lower-Level Drivers.

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

membro do DO IRP	Valor
UserBuffer	NULL
UserEvent	O endereço do objeto de evento que foi inicializado na chamada para a rotina KeInitializeEvent. Observação 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
parâmetros .DeviceIoControl. IoControlCode	IOCTL_VPCI_INVALIDATE_BLOCK
parâmetros .DeviceIoControl. Type3InputBuffer	Um ponteiro para uma estrutura VPCI_INVALIDATE_BLOCK_OUTPUT. O driver formata essa estrutura com os parâmetros para a solicitação de E/S IOCTL_VPCI_INVALIDATE_BLOCK.
IParameters.DeviceIoControl. InputBufferLength	O tamanho, em bytes, da estrutura VPCI_INVALIDATE_BLOCK_OUTPUT.
parâmetros .DeviceIoControl. OutputBufferLength	O tamanho, em bytes, do buffer alocado pelo chamador que conterá os dados de configuração a serem lidos. Observação Esse valor deve ser o mesmo que o valor do membro BytesRequested da estrutura VPCI_INVALIDATE_BLOCK_OUTPUT.

emitindo a solicitação IOCTL

Para emitir essa solicitação IOCTL, o driver chama a rotina de 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 do IoCallDriver	Valor
DeviceObject	O objeto do dispositivo do driver inferior.
de Irp	O endereço do IRP que foi alocado e inicializado anteriormente. Para obter mais informações, consulte Preparando uma estrutura de pacotes de solicitação de E/S.

resultados da conclusão da solicitação IOCTL

Quando a solicitação IOCTL_VPCI_INVALIDATE_BLOCK IOCTL é concluída, os membros da estrutura de IO_STATUS_BLOCK alocada pelo chamador são definidos como os valores na tabela a seguir.

Valor do status	Valor
de Status do	STATUS_SUCCESS
de Informações	Zero

Quando o IOCTL_VPCI_INVALIDATE_BLOCK IOCTL é emitido e concluído, o driver VF é notificado de que o driver PF alterou dados (invalidados) em um ou mais blocos de configuração de VF.

Observação 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 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 Hyper-V.
O driver PF, que é executado no sistema operacional de gerenciamento.
Esse sistema operacional é executado na partição pai Hyper-V.

A partir do NDIS 6.30, o driver de miniporto VF não deve emitir uma solicitação de IOCTL_VPCI_INVALIDATE_BLOCK. Em vez disso, as etapas a seguir são executadas para lidar com notificações de dados de bloco de configuração de VF invalidados.

No sistema operacional convidado, o NDIS emite uma solicitação de IOCTL_VPCI_INVALIDATE_BLOCK.
No sistema operacional de gerenciamento, as seguintes etapas ocorrem:
1. O driver de miniporto PF chama a função NdisMInvalidateConfigBlock para notificar o NDIS de que os dados de configuração do VF foram alterados e não são mais válidos. O driver define o parâmetro BlockMask como um bitmask ULONGLONG que especifica quais blocos de configuração de VF foram alterados. Cada bit na máscara de bits corresponde a um bloco de configuração de VF. Se um bit for definido como um, os dados no bloco de configuração de VF correspondente serão alterados.
2. O NDIS sinaliza a pilha de virtualização, que é executada no sistema operacional de gerenciamento, sobre a alteração nos dados do bloco de configuração de VF. A pilha de virtualização armazena em cache os dados do parâmetro BlockMask.
  Observação Sempre que o driver de miniporto PF chama NdisMInvalidateConfigBlock, a pilha de virtualização OUos dados do parâmetro BlockMask com o valor atual em seu cache.
3. A pilha de virtualização notifica o driver VPCI (PCI virtual), que é executado no sistema operacional convidado, sobre a invalidação dos dados de configuração do VF. A pilha de virtualização envia os dados de parâmetro BlockMask armazenados em cache para o driver VPCI.
No so convidado, as seguintes etapas ocorrem:
1. O driver VPCI salva os dados de parâmetro BlockMask armazenados em cache no membro BlockMask da estrutura VPCI_INVALIDATE_BLOCK_OUTPUT associada à solicitação IOCTL_VPCI_INVALIDATE_BLOCK.
2. O driver VPCI conclui com êxito a solicitação de IOCTL_VPCI_INVALIDATE_BLOCK. Quando isso acontece, o NDIS emite uma solicitação OID (identificador de objeto) de OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK para o driver de miniporto VF. Um ponteiro para uma estrutura de NDIS_SRIOV_VF_INVALIDATE_CONFIG_BLOCK_INFO é passado na solicitação OID. Essa estrutura contém os dados de parâmetro BlockMask armazenados em cache.
  O NDIS também emite outro IOCTL_VPCI_INVALIDATE_BLOCK solicitação para lidar com notificações sucessivas de alterações nos dados de configuração do VF.
3. Quando o driver VF manipula a solicitação OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK, ele lê dados dos blocos de configuração de VF especificados.

Observação 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.