Edit

GET_VIRTUAL_DEVICE_LOCATION callback function (wdm.h)

  • Article

The GetLocation routine returns the device location of a PCI Express (PCIe) virtual function (VF) on a PCI bus. A device that supports the single root I/O virtualization (SR-IOV) interface can expose one or more VFs on the PCI bus.

Syntax

GET_VIRTUAL_DEVICE_LOCATION GetVirtualDeviceLocation;

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

Parameters

[in, out] Context

A pointer to interface-specific context information. The caller passes the value that is passed as the Context member of the PCI_VIRTUALIZATION_INTERFACE structure for the interface.

[in] VirtualFunction

A zero-based value that specifies the VF on the device for which the device location is returned

[out] SegmentNumber

A pointer to a caller-supplied variable in which this routine returns a UINT16 value for the current PCI segment number. This value specifies the group of PCI buses on which the device is attached.

[out] BusNumber

A pointer to a caller-supplied variable in which this routine returns a UINT8 value. This value specifies the current PCI bus number on which the device is attached.

[out] FunctionNumber

A pointer to a caller-supplied variable in which this routine returns a UINT8 value. This value contains the function number for the specified VF on the PCI bus.

Return value

The GetLocation routine returns one of the following NTSTATUS values:

Return code Description
STATUS_SUCCESS The operation completed successfully.
STATUS_INVALID_PARAMETER The VirtualFunction parameter is larger than the value of the TotalVFs member of the SR-IOV Extended Capability structure for the device.

Remarks

The GetLocation routine returns the current device location of a VF in the PCIe hierarchy. This information is necessary for a virtualization system that is using an I/O memory management unit (IOMMU) to route traffic to or from the device.

Upon a successful return from a call to the GetLocation routine, the FunctionNumber parameter contains a value that represents the function number for the specified VF on the PCI bus. This value is based on the Alternative Routing Interpretation (ARI) option of the PCI Express 3.0 specification. ARI treats a PCIe bus as a single device with an 8-bit function space, which allows for 256 functions on the bus.

The GetLocation routine is provided by the GUID_PCI_VIRTUALIZATION_INTERFACE interface.

The PCI bus number on which the VF is located can change. We do not recommend that drivers store the device location for a VF in nonvolatile storage such as the registry.

Requirements

Requirement Value
Minimum supported client Supported in Windows Server 2012 and later versions of Windows Server.
Target Platform Desktop
Header wdm.h (include Wdm.h)
IRQL PASSIVE_LEVEL

See also

PCI_VIRTUALIZATION_INTERFACE