The order of device labels in the guest OS does not correspond to the order in which they appear in the VM configuration.

Products

• VMware vSphere ESXi

Issue/Introduction

Symptoms:

• The order of device labels in the guest OS does not correspond to the order in which they appear in the VM configuration.
• For instance, the first and second virtual network adapters in the virtual machine's configuration might be labeled "eth1" and "eth0" respectively inside the guest OS, or the fifth network adapter might be labeled "eth1" inside the guest OS.

Environment

VMware vSphere ESXi 7.0
VMware vSphere ESXi 8.0

Cause

• The hypervisor's design does not ensure that the order in which the guest OS enumerates devices matches the order in which the devices are described in the virtual machine's configuration.
• In virtual machines with a mixture of PCI and PCIe devices or with more than four PCIe devices, the guest OS enumeration might not match the order of the virtual machine configuration.
• The guest OS determines its own PCI/PCIe enumeration policy. Possibilities include depth-first or breadth-first exploration of the device hierarchy, although other enumeration policies are possible.

Resolution

This behavior is by design. A guest OS or application must not make any assumptions about the order in which the devices will be enumerated.

A guest OS may obtain the identity of a device by using the ACPI _DSM (Device Specific Method) on the PCI slot object. The ACPI _DSM method for PCI slot objects is described in PCI Firmware Specification Revision 3.3 section 4.6.7, "_DSM for Naming a PCI or PCI Express Device Under Operating Systems". Further information on guest OS support for device identification using _DSM might be found in guest OS documentation or obtained from the guest OS vendor.

_DSM support for PCI/PCIe device naming is available in virtual hardware version 10 and newer. Calling the ACPI _DSM method on the slot object for a given PCI Bus/Device/Function and requesting PCI _DSM function 7 will return an ACPI Package object, the first element of which is the Instance Number (which will be a large unsigned 32-bit integer) and the second of which is the String Name, Unicode-encoded (UTF16-LE). The Instance Number is expected to be a very large value, unsuitable for direct use as a user-visible identifier.

There are a few ways to use this information:

1. The Instance Number can be treated as an opaque number. The relevant Implementation Note in the PCI Firmware Specification Revision 3.3 describes how the Instance Number may be used to produce an ordered list of devices. This method is not specific to VMware virtual machines, but is not robust against discontinuities in the list of devices described in the virtual machine configuration -- it will always result in a monotonically increasing enumeration within the guest OS.
2. The Instance Number also has a VMware-specific interpretation: The most-significant byte of the Instance Number is the exact instance number of the device from the VM's configuration file _plus_ _one_. For example: The device identified in the VM's configuration file as ethernet0 (and displayed as "Network Adapter 1" in the user interface) will have the value 1 in the most-significant byte of its Instance Number; For ethernet1 ("Network Adapter 2"), it will be 2, and so on. This method is VMware-specific but will result in a list which correctly reflects any discontinuities in the list of devices described in the virtual machine configuration.
3. The String Name may be decoded from UTF16-LE and directly used. It is the label from the Ethernet adapter's identity in the VM's configuration file (e.g. "ethernet0"). This approach is not VMware-specific, although platforms may vary in their support and the format of the returned string is not standardized.

Alternative approaches to determining guest device identity include configuring the guest OS to identify Ethernet adapters by their MAC address, or manually evaluating the PCI hierarchy information from the virtual machine's configuration file.