NDIS_SWITCH_NIC_PARAMETERS-Struktur (ntddndis.h)

Artikel
02/26/2024

Die NDIS_SWITCH_NIC_PARAMETERS-Struktur gibt die Konfigurationsparameter für einen Netzwerkadapter (NIC) an, der mit einem erweiterbaren Hyper-V-Switchport verbunden ist.

Syntax

typedef struct _NDIS_SWITCH_NIC_PARAMETERS {
  NDIS_OBJECT_HEADER           Header;
  ULONG                        Flags;
  NDIS_SWITCH_NIC_NAME         NicName;
  NDIS_SWITCH_NIC_FRIENDLYNAME NicFriendlyName;
  NDIS_SWITCH_PORT_ID          PortId;
  NDIS_SWITCH_NIC_INDEX        NicIndex;
  NDIS_SWITCH_NIC_TYPE         NicType;
  NDIS_SWITCH_NIC_STATE        NicState;
  NDIS_VM_NAME                 VmName;
  NDIS_VM_FRIENDLYNAME         VmFriendlyName;
  GUID                         NetCfgInstanceId;
  ULONG                        MTU;
  USHORT                       NumaNodeId;
  UCHAR                        PermanentMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH];
  UCHAR                        VMMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH];
  UCHAR                        CurrentMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH];
  BOOLEAN                      VFAssigned;
  ULONG64                      NdisReserved[2];
} NDIS_SWITCH_NIC_PARAMETERS, *PNDIS_SWITCH_NIC_PARAMETERS;

Member

Header

Der Typ, die Revision und die Größe der NDIS_SWITCH_NIC_PARAMETERS Struktur. Dieses Element ist als NDIS_OBJECT_HEADER-Struktur formatiert.

Das Type-Element von Header muss auf NDIS_OBJECT_TYPE_DEFAULT festgelegt werden. Um die Version der NDIS_SWITCH_NIC_PARAMETERS-Struktur anzugeben, muss der Revisionsmember von Header auf den folgenden Wert festgelegt werden:

NDIS_SWITCH_NIC_PARAMETERS_REVISION_1

Ursprüngliche Version für NDIS 6.30 und höher.

Legen Sie das Element Größe auf NDIS_SIZEOF_NDIS_SWITCH_NIC_PARAMETERS_REVISION_1 fest.

Flags

Ein ULONG-Wert , der ein bitweises OR von Flags enthält. Der folgende Flagwert wird definiert.

Wert	Bedeutung
NDIS_SWITCH_NIC_FLAGS_NIC_INITIALIZING	Dieses Flag wird festgelegt, wenn die OID_SWITCH_NIC_CREATE OID zum ersten Mal in der Lebensdauer eines VM-NIC-Objekts ausgegeben wird. Wenn dieses Flag festgelegt ist: Eine Hyper-V Extensible Switch-Erweiterung kann optional den Wert des MTU-Members in der NDIS_SWITCH_NIC_PARAMETERS-Struktur reduzieren, wenn der Kopfraum für die Kapselung reserviert werden muss, bevor die OID im Stapel übergeben wird. Die Erweiterung kann keine Kapselungskopfraum für andere Arten von NIC reservieren. Die Erweiterung sollte den MTU-Wert nicht erhöhen. Dieses Flag wird nur festgelegt, wenn das NicType-ElementNdisSwitchNicTypeSynthetic ist.

Wert

Bedeutung

NDIS_SWITCH_NIC_FLAGS_NIC_INITIALIZING

Dieses Flag wird festgelegt, wenn die OID_SWITCH_NIC_CREATE OID zum ersten Mal in der Lebensdauer eines VM-NIC-Objekts ausgegeben wird. Wenn dieses Flag festgelegt ist:

Eine Hyper-V Extensible Switch-Erweiterung kann optional den Wert des MTU-Members in der NDIS_SWITCH_NIC_PARAMETERS-Struktur reduzieren, wenn der Kopfraum für die Kapselung reserviert werden muss, bevor die OID im Stapel übergeben wird. Die Erweiterung kann keine Kapselungskopfraum für andere Arten von NIC reservieren.
Die Erweiterung sollte den MTU-Wert nicht erhöhen.

Dieses Flag wird nur festgelegt, wenn das NicType-ElementNdisSwitchNicTypeSynthetic ist.

NicName

Ein NDIS_SWITCH_NIC_NAME Wert, der den eindeutigen internen Namen des Netzwerkadapters angibt, der mit einem erweiterbaren Switchport verbunden ist.

Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

NicFriendlyName

Ein NDIS_SWITCH_NIC_FRIENDLYNAME Wert, der die benutzerfreundliche Beschreibung des Netzwerkadapters angibt.

PortId

Ein NDIS_SWITCH_PORT_ID Wert, der den eindeutigen Bezeichner des erweiterbaren Switchports enthält, mit dem der Netzwerkadapter verbunden ist.

NicIndex

Ein NDIS_SWITCH_NIC_INDEX Wert, der den Index des Netzwerkadapters angibt, der mit dem erweiterbaren Switchport verbunden ist, der vom PortId-Member angegeben wird.

Weitere Informationen zu NDIS_SWITCH_NIC_INDEX Werten finden Sie unter Indexwerte des Netzwerkadapters.

NicType

Ein NDIS_SWITCH_NIC_TYPE Wert, der den Typ des Netzwerkadapters angibt, der mit einem erweiterbaren Switchport verbunden ist.

NicState

Ein NDIS_SWITCH_NIC_STATE Wert, der den aktuellen Zustand des Netzwerkadapters angibt.

VmName

Ein NDIS_VM_NAME Wert, der den eindeutigen internen Namen der untergeordneten Hyper-V-Partition angibt, in der das Gastbetriebssystem ausgeführt wird, das den Netzwerkadapter verfügbar macht.

Die untergeordnete Hyper-V-Partition wird auch als virtueller Computer (VM) bezeichnet.

Hinweis Dieser Member ist nur gültig, wenn das NicType-Element den Wert NdisSwitchNicSyntheticNic oder NdisSwitchNicEmulatedNic Enthält.

VmFriendlyName

NetCfgInstanceId

Ein GUID-Wert, der den NetCfgInstanceId-Registrierungswert des zugrunde liegenden Netzwerkadapters angibt.

Hinweis Dieser Member ist nur gültig, wenn das NicType-Element auf NdisSwitchNicTypeExternal oder NdisSwitchNicTypeInternal festgelegt ist. NetCfgInstanceId ist erst gültig, nachdem der virtuelle Netzwerkadapter initialisiert wurde.

MTU

Ein ULONG-Wert , der die maximale MTU-Größe (Transmission Unit) in Bytes für den Netzwerkadapter angibt.

Hinweis Der Wert dieses Members kann sich während der Lebensdauer einer VM-NIC ändern. Daher sollten Erweiterungen diesen Member der NDIS_SWITCH_NIC_PARAMETERS Struktur lesen, die mit den folgenden OIDs übergeben wird:

NumaNodeId

Ein USHORT-Wert , der den Bezeichner für den bevorzugten NUMA-Knoten (Non-Uniform Memory Access) einer CPU angibt. Auf Computern, die die NUMA-Architektur unterstützen, ist der bevorzugte NUMA-Knoten die CPU, die den geringsten Abstand zum Netzwerkadapter aufweist.

Hinweis Dieser Member ist nur gültig, wenn das NicType-Element auf NdisSwitchNicTypeSynthetic oder NdisSwitchNicTypeEmulated festgelegt ist.

PermanentMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]

Ein UCHAR-Array , das die MAC-Adresse (Media Access Control) angibt, wie sie auf der Hostpartition für den Netzwerkadapter konfiguriert ist. Dies kann sich von der mac-Adresse unterscheiden, die derzeit vom Netzwerkadapter verwendet wird.

VMMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]

Ein UCHAR-Array , das die MAC-Adresse angibt, die auf dem Netzwerkadapter innerhalb der VM selbst konfiguriert ist. Das Feld ist alle Nullen für keine VM-NICs. Wenn AllowMacSpoofing (von NDIS_SWITCH_PORT_PROPERTY_SECURITY) true ist, wird diese Adresse auch auf die CurrentMacAddress angewendet.

CurrentMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]

Ein UCHAR-Array , das die MAC-Adresse angibt, die derzeit im Switch für den Netzwerkadapter verwendet wird. Wenn AllowMacSpoofing und AllowTeaming false sind, ist dieser Wert gleich PermanentMacAddress. Wenn AllowMacSpoofing TRUE ist, ist dieser Wert gleich dem VMMacAddress. Wenn AllowTeaming TRUE ist und ein Teamingfailover innerhalb des virtuellen Computers aufgetreten ist, entspricht die CurrentMacAddress der MAC-Adresse, die auf den Netzwerkadapter oder permanentMacAddress übertragen wurde, wenn kein Failover aufgetreten ist.

VFAssigned

Ein BOOLEAN-Wert , der bei Festlegung auf TRUE angibt, dass der Netzwerkadapter an eine VIRTUELLE PCI Express-Funktion (PCIe) angefügt ist. Ein VF wird von einem zugrunde liegenden physischen Netzwerkadapter verfügbar gemacht, der die SR-IOV-Schnittstelle (Single Root E/O Virtualization) unterstützt.

Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Hinweis Das VFAssigned-Element ist nur gültig, wenn das NicType-Element den Wert NdisSwitchNicTypeEmulated oder NdisSwitchNicTypeSynthetic enthält. Dieses Element muss auf FALSE festgelegt werden, wenn das NicType-Element den Wert NdisSwitchNicTypeExternal oder NdisSwitchNicTypeInternal enthält.

NdisReserved[2]

Hinweise

OID-Abfrageanforderungen von OID_SWITCH_NIC_ARRAY geben eine NDIS_SWITCH_NIC_ARRAY-Struktur zurück, die null oder mehr Elemente enthält. Jedes Element ist als NDIS_SWITCH_NIC_PARAMETERS-Struktur formatiert.

Die NDIS_SWITCH_NIC_PARAMETERS-Struktur wird auch in den folgenden OID-Anforderungen verwendet:

Hinweis Die Datentypen NDIS_SWITCH_NIC_NAME, NDIS_SWITCH_NIC_FRIENDLYNAME, NDIS_VM_NAME und NDIS_VM_FRIENDLYNAME werden von der IF_COUNTED_STRING-Struktur typdefiniert. Eine Zeichenfolge, die von dieser Struktur definiert wird, muss nicht NULL-endend sein. Die Länge der Zeichenfolge muss jedoch im Length-Element dieser Struktur festgelegt werden. Wenn die Zeichenfolge null-beendet ist, darf das Length-Element das beendende NULL-Zeichen nicht enthalten.

Richtlinien für die NicType- und NicName-Elemente

Basierend auf dem Wert NicType-Member ist das Format des NicName-Members wie folgt:

Wenn das NicType-Element auf NdisSwitchNicTypeExternal festgelegt ist, ist der Wert des NicName-Members der eindeutige instance Bezeichner (InstanceId) des physischen Netzwerkadapters, der an den externen Netzwerkadapter gebunden ist. Dieser Netzwerkadaptertyp wird im Verwaltungsbetriebssystem verfügbar gemacht, das in der übergeordneten Hyper-V-Partition ausgeführt wird.
Der externe Netzwerkadapter stellt eine Verbindung mit der physischen Netzwerkschnittstelle bereit, die auf dem Host verfügbar ist. Auf den externen Netzwerkadapter kann von der übergeordneten Hyper-V-Partition und allen untergeordneten Partitionen zugegriffen werden.

Hinweis Der InstanceId-Wert wird vom Plug & Play-Manager generiert, der im Verwaltungsbetriebssystem ausgeführt wird.
Wenn das NicType-Element auf NdisSwitchNicTypeInternal festgelegt ist, ist der Wert des NicName-Members der Geräteanzeigename, der den internen Netzwerkadapter identifiziert. Dieser Netzwerkadaptertyp wird im Verwaltungsbetriebssystem einer übergeordneten Hyper-V-Partition verfügbar gemacht.
Auf den internen Netzwerkadapter kann die übergeordnete Hyper-V-Partition und alle untergeordneten Partitionen zugreifen. Der interne Netzwerkadapter stellt jedoch keine Verbindung mit der physischen Netzwerkschnittstelle her, die auf dem Host verfügbar ist.

Hinweis Der Geräteanzeigename wird von der Hyper-V WMI-Verwaltungsschicht generiert, die im Verwaltungsbetriebssystem ausgeführt wird.
Für alle anderen NicType-Memberwerte wird der Wert des NicName-Members durch die Richtlinienverwaltungsschnittstelle eindeutig dem synthetischen oder emulierten Netzwerkadapter zugewiesen. Diese Arten von Netzwerkadaptern werden im Gastbetriebssystem verfügbar gemacht, das ausgeführt wird, ist eine untergeordnete Hyper-V-Partition.

Richtlinien für das VFAssignierte Element

Ein PCIe VF wird von einem zugrunde liegenden physischen Adapter erstellt und zugeordnet, der die SR-IOV-Schnittstelle unterstützt. Nachdem die PCIe VF erstellt wurde, fügt der Virtualisierungsstapel dem VF eine untergeordnete Hyper-V-Partition an oder weist sie zu. Das Gastbetriebssystem, das in dieser Partition ausgeführt wird, macht einen VM-Netzwerkadapter verfügbar, der dem zugrunde liegenden physischen SR-IOV-Adapter angefügt oder zugewiesen ist.

Wenn der VFAssigned-Member auf TRUE festgelegt ist, werden Pakete direkt zwischen dem zugrunde liegenden physischen SR-IOV-Netzwerkadapter und dem virtuellen Adapter weitergeleitet. Da der erweiterbare Switch jedoch nicht an der Paketübermittlung beteiligt ist, werden erweiterbare Switchportrichtlinien wie Zugriffssteuerungslisten (Access Control Lists, ACLs) nicht auf diese Pakete angewendet.

Die Erweiterung kann eine VF-Zuweisung entfernen, indem sie eine NDIS_STATUS_SWITCH_PORT_REMOVE_VF status Angabe ausgibt. Dieser Hinweis bewirkt, dass die Pakete über einen erweiterbaren Switchport statt direkt zwischen dem VM-Netzwerkadapter und dem physischen SR-IOV-Adapter übermittelt werden. Dadurch können die erweiterbaren Switchportrichtlinien auf Pakete angewendet werden, die über den erweiterbaren Switchport empfangen oder gesendet werden. Wenn die Erweiterung den NDIS_STATUS_SWITCH_PORT_REMOVE_VF status Angabe macht, gibt sie an, mit welchem erweiterbaren Switchport der virtuelle Netzwerkadapter verbunden ist.

Weitere Informationen finden Sie unter NDIS_STATUS_SWITCH_PORT_REMOVE_VF.