GET_VIRTUAL_DEVICE_LOCATION função de retorno de chamada (wdm.h)

Artigo
02/07/2025

A rotina GetLocation retorna o local do dispositivo de uma VF (função virtual) PCI Express (PCIe) em um barramento PCI. Um dispositivo que dá suporte à interface de virtualização de E/S raiz única (SR-IOV) pode expor um ou mais VFs no barramento PCI.

Sintaxe

GET_VIRTUAL_DEVICE_LOCATION GetVirtualDeviceLocation;

NTSTATUS GetVirtualDeviceLocation(
  [in, out] PVOID Context,
  [in]      USHORT VirtualFunction,
  [out]     PUINT16 SegmentNumber,
  [out]     PUINT8 BusNumber,
  [out]     PUINT8 FunctionNumber
)
{...}

Parâmetros

[in, out] Context

Um ponteiro para informações de contexto específicas da interface. O chamador passa o valor passado como o membro Context da estrutura PCI_VIRTUALIZATION_INTERFACE da interface.

[in] VirtualFunction

Um valor baseado em zero que especifica o VF no dispositivo para o qual o local do dispositivo é retornado

[out] SegmentNumber

Um ponteiro para uma variável fornecida pelo chamador na qual essa rotina retorna um valor UINT16 para o número de segmento de PCI atual. Esse valor especifica o grupo de barramentos PCI nos quais o dispositivo está anexado.

[out] BusNumber

Um ponteiro para uma variável fornecida pelo chamador na qual essa rotina retorna um valor UINT8. Esse valor especifica o número atual do barramento PCI no qual o dispositivo está anexado.

[out] FunctionNumber

Um ponteiro para uma variável fornecida pelo chamador na qual essa rotina retorna um valor UINT8. Esse valor contém o número da função do VF especificado no barramento PCI.

Valor de retorno

A rotina GetLocation retorna um dos seguintes valores NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	A operação foi concluída com êxito.
STATUS_INVALID_PARAMETER	O parâmetro VirtualFunction é maior que o valor do totalVFs membro da estrutura SR-IOV Capacidade Estendida do dispositivo.

Observações

A rotina GetLocation retorna o local atual do dispositivo de um VF na hierarquia pcie. Essas informações são necessárias para um sistema de virtualização que está usando uma IOMMU (unidade de gerenciamento de memória de E/S) para rotear o tráfego de ou para o dispositivo.

Após um retorno bem-sucedido de uma chamada para a rotina de GetLocation, o parâmetro FunctionNumber contém um valor que representa o número da função para o VF especificado no barramento PCI. Esse valor baseia-se na opção ARI (Interpretação de Roteamento Alternativo) da especificação PCI Express 3.0. A ARI trata um barramento PCIe como um único dispositivo com um espaço de função de 8 bits, o que permite 256 funções no barramento.

A rotina de GetLocation é fornecida pela interface GUID_PCI_VIRTUALIZATION_INTERFACE.

O número do barramento PCI no qual a VF está localizada pode ser alterado. Não recomendamos que os drivers armazenem o local do dispositivo para uma VF no armazenamento nãovolatile, como o Registro.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Com suporte no Windows Server 2012 e versões posteriores do Windows Server.
da Plataforma de Destino	Área de trabalho
cabeçalho	wdm.h (inclua Wdm.h)
IRQL	PASSIVE_LEVEL

Consulte também

PCI_VIRTUALIZATION_INTERFACE

Compartilhar via