NdisMGetVirtualFunctionLocation function (ndis.h)

Article
11/04/2021

A miniport driver calls the NdisMGetVirtualFunctionLocation function to query the device location of a PCI Express (PCIe) Virtual Function (VF) on a PCI bus. The driver uses the device location to construct the PCIe Requestor ID (RID) for the VF.

Note NdisMGetVirtualFunctionLocation must only be called by the miniport driver for the network adapter's PCIe Physical Function (PF).

Syntax

void NdisMGetVirtualFunctionLocation(
  [in]  NDIS_HANDLE            NdisMiniportHandle,
  [in]  NDIS_SRIOV_FUNCTION_ID VFId,
  [out] PUSHORT                SegmentNumber,
  [out] PUCHAR                 BusNumber,
  [out] PUCHAR                 FunctionNumber
);

Parameters

[in] NdisMiniportHandle

The network adapter handle that NDIS passed to the MiniportAdapterHandle parameter of MiniportInitializeEx.

[in] VFId

The identifier of the VF for which the device location is returned.

[out] SegmentNumber

A pointer to a caller-supplied variable in which this function returns a USHORT 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 function returns a UCHAR 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 function returns a UCHAR value. This value specifies the function number of a logical device on the device.

Return value

None

Remarks

When it handles a method request of OID_NIC_SWITCH_ALLOCATE_VF, the PF miniport driver must return the RID for the VF that the driver has successfully allocated on the network adapter. The driver generates the RID in the following way:

The driver first calls the NdisMGetVirtualFunctionLocation function to obtain the bus-related location information for the VF.
The driver then calls the NDIS_MAKE_RID macro with the bus-related location information to generate the RID.

For more information on how to allocate VF resources, see Virtual Function Initialization Sequence.

For more information about the SR-IOV interface, see Overview of Single Root I/O Virtualization (SR-IOV).

Interfacing to a Virtual Bus Driver

If an independent hardware vendor (IHV) provides a virtual bus driver (VBD) as part of its SR-IOV driver package, its miniport driver must not call NdisMGetVirtualFunctionLocation. Instead, the driver must interface with the VBD through a private communication channel, and request that the VBD call GetLocation. This function is exposed from the GUID_PCI_VIRTUALIZATION_INTERFACE interface supported by the underlying PCI bus driver.

The VBD that runs in the Hyper-V parent partition's management operating system can query the GUID_PCI_VIRTUALIZATION_INTERFACE interface by issuing an IRP_MN_QUERY_INTERFACE request to its physical device object (PDO) on the PCI bus. This request must be made from IRQL = PASSIVE_LEVEL. In this request, the driver must set the InterfaceType parameter to GUID_PCI_VIRTUALIZATION_INTERFACE.

Requirements

Requirement	Value
Minimum supported client	None supported,Supported in NDIS 6.30 and later.
Minimum supported server	Windows Server 2012
Target Platform	Universal
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL