structure NDIS_SWITCH_NIC_PARAMETERS (ntddndis.h)

Article
08/07/2023

La structure NDIS_SWITCH_NIC_PARAMETERS spécifie les paramètres de configuration d’une carte réseau connectée à un port de commutateur extensible Hyper-V.

Syntaxe

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;

Membres

Header

Type, révision et taille de la structure NDIS_SWITCH_NIC_PARAMETERS . Ce membre est mis en forme en tant que structure NDIS_OBJECT_HEADER .

Le membre Type de l’en-tête doit être défini sur NDIS_OBJECT_TYPE_DEFAULT. Pour spécifier la version de la structure NDIS_SWITCH_NIC_PARAMETERS , le membre Revision de Header doit avoir la valeur suivante :

NDIS_SWITCH_NIC_PARAMETERS_REVISION_1

Version d’origine pour NDIS 6.30 et versions ultérieures.

Définissez le membre Size sur NDIS_SIZEOF_NDIS_SWITCH_NIC_PARAMETERS_REVISION_1.

Flags

Valeur ULONG qui contient un OR au niveau du bit d’indicateurs. La valeur d’indicateur suivante est définie.

Valeur	Signification
NDIS_SWITCH_NIC_FLAGS_NIC_INITIALIZING	Cet indicateur est défini lorsque le OID_SWITCH_NIC_CREATE OID est émis pour la première fois dans la durée de vie d’un objet de carte réseau de machine virtuelle. Si cet indicateur est défini : Une extension de commutateur extensible Hyper-V peut éventuellement réduire la valeur du membre MTU dans la structure NDIS_SWITCH_NIC_PARAMETERS si elle doit réserver une marge d’attente pour l’encapsulation avant de passer l’OID dans la pile. L’extension ne sera pas en mesure de réserver la salle d’encapsulation pour tout autre type de carte réseau. L’extension ne doit pas augmenter la valeur MTU . Cet indicateur sera défini uniquement si le membre NicType est NdisSwitchNicTypeSynthetic.

Valeur

Signification

NDIS_SWITCH_NIC_FLAGS_NIC_INITIALIZING

Cet indicateur est défini lorsque le OID_SWITCH_NIC_CREATE OID est émis pour la première fois dans la durée de vie d’un objet de carte réseau de machine virtuelle. Si cet indicateur est défini :

Une extension de commutateur extensible Hyper-V peut éventuellement réduire la valeur du membre MTU dans la structure NDIS_SWITCH_NIC_PARAMETERS si elle doit réserver une marge d’attente pour l’encapsulation avant de passer l’OID dans la pile. L’extension ne sera pas en mesure de réserver la salle d’encapsulation pour tout autre type de carte réseau.
L’extension ne doit pas augmenter la valeur MTU .

Cet indicateur sera défini uniquement si le membre NicType est NdisSwitchNicTypeSynthetic.

NicName

Valeur NDIS_SWITCH_NIC_NAME qui spécifie le nom interne unique de la carte réseau connectée à un port de commutateur extensible.

Pour plus d'informations, consultez la section Notes.

NicFriendlyName

Valeur NDIS_SWITCH_NIC_FRIENDLYNAME qui spécifie la description conviviale de la carte réseau.

PortId

Valeur NDIS_SWITCH_PORT_ID qui contient l’identificateur unique du port de commutateur extensible auquel la carte réseau est connectée.

NicIndex

Valeur NDIS_SWITCH_NIC_INDEX qui spécifie l’index de la carte réseau connectée au port de commutateur extensible spécifié par le membre PortId .

Pour plus d’informations sur les valeurs NDIS_SWITCH_NIC_INDEX, consultez Valeurs d’index de carte réseau.

NicType

Valeur NDIS_SWITCH_NIC_TYPE qui spécifie le type de la carte réseau connectée à un port de commutateur extensible.

NicState

Valeur NDIS_SWITCH_NIC_STATE qui spécifie l’état actuel de la carte réseau.

VmName

Valeur NDIS_VM_NAME qui spécifie le nom interne unique de la partition enfant Hyper-V dans laquelle le système d’exploitation invité qui expose la carte réseau est en cours d’exécution.

La partition enfant Hyper-V est également appelée machine virtuelle.

Note Ce membre est valide uniquement si le membre NicType contient une valeur de NdisSwitchNicSyntheticNic ou NdisSwitchNicEmulatedNic.

VmFriendlyName

NetCfgInstanceId

Valeur GUID qui spécifie la valeur de Registre NetCfgInstanceId de la carte réseau sous-jacente.

Note Ce membre est valide uniquement si le membre NicType est défini sur NdisSwitchNicTypeExternal ou NdisSwitchNicTypeInternal. NetCfgInstanceId n’est valide qu’après l’initialisation de la carte réseau virtuelle.

MTU

Valeur ULONG qui spécifie la taille maximale de l’unité de transmission (MTU), en octets, pour la carte réseau.

Note La valeur de ce membre peut changer pendant la durée de vie d’une carte réseau de machine virtuelle. Par conséquent, les extensions doivent lire ce membre de la structure NDIS_SWITCH_NIC_PARAMETERS transmise avec les OID suivants :

NumaNodeId

Valeur USHORT qui spécifie l’identificateur du nœud NUMA (Non Uniform Memory Access) préféré d’un processeur. Sur les ordinateurs qui prennent en charge l’architecture NUMA, le nœud NUMA préféré est le processeur qui a la plus petite distance par rapport à la carte réseau.

Note Ce membre est valide uniquement si le membre NicType est défini sur NdisSwitchNicTypeSynthetic ou NdisSwitchNicTypeEmulated.

PermanentMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]

Tableau UCHAR qui spécifie l’adresse de contrôle d’accès au média (MAC) telle que configurée sur la partition hôte de la carte réseau. Cela peut être différent de l’adresse MAC actuellement utilisée par la carte réseau.

VMMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]

Tableau UCHAR qui spécifie l’adresse MAC configurée sur la carte réseau à l’intérieur de la machine virtuelle elle-même. Le champ correspond à tous les zéros pour les cartes réseau autres que les machines virtuelles. Si AllowMacSpoofing (à partir de NDIS_SWITCH_PORT_PROPERTY_SECURITY) a la valeur TRUE, cette adresse sera également appliquée à CurrentMacAddress.

CurrentMacAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]

Tableau UCHAR qui spécifie l’adresse MAC actuellement utilisée dans le commutateur pour la carte réseau. Si AllowMacSpoofing et AllowTeaming sont tous deux FALSE, cette valeur est égale à PermanentMacAddress. Si AllowMacSpoofing a la valeur TRUE, cette valeur sera égale à vmMacAddress. Si AllowTeaming a la valeur TRUE et que le basculement d’association s’est produit à l’intérieur de la machine virtuelle, l’adresse CurrentMacAddress est égale à l’adresse MAC qui a été basculée sur la carte réseau ou à PermanentMacAddress si aucun basculement n’a eu lieu.

VFAssigned

Valeur BOOLEAN qui, si elle est définie sur TRUE, spécifie que la carte réseau est attachée à une fonction virtuelle (VF) PCI Express (PCIe). Une VF est exposée par une carte réseau physique sous-jacente qui prend en charge l’interface de virtualisation d’E/S racine unique (SR-IOV).

Pour plus d'informations, consultez la section Notes.

Note Le membre VFAssigned est valide uniquement si le membre NicType contient une valeur de NdisSwitchNicTypeEmulated ou NdisSwitchNicTypeSynthetic. Ce membre doit avoir la valeur FALSE si le membre NicType contient une valeur de NdisSwitchNicTypeExternal ou NdisSwitchNicTypeInternal.

NdisReserved[2]

Remarques

Les requêtes OID de OID_SWITCH_NIC_ARRAY retournent une structure NDIS_SWITCH_NIC_ARRAY qui contient zéro élément ou plus. Chaque élément est mis en forme en tant que structure NDIS_SWITCH_NIC_PARAMETERS .

La structure NDIS_SWITCH_NIC_PARAMETERS est également utilisée dans les requêtes OID suivantes :

Note Les types de données NDIS_SWITCH_NIC_NAME, NDIS_SWITCH_NIC_FRIENDLYNAME, NDIS_VM_NAME et NDIS_VM_FRIENDLYNAME sont définis par la structure IF_COUNTED_STRING . Une chaîne définie par cette structure n’a pas besoin d’être terminée par null. Toutefois, la longueur de la chaîne doit être définie dans le membre Length de cette structure. Si la chaîne est terminée par null, le membre Length ne doit pas inclure le caractère null de fin.

Instructions pour les membres NicType et NicName

En fonction de la valeur du membre NicType , le format du membre NicName est le suivant :

Si le membre NicType a la valeur NdisSwitchNicTypeExternal, la valeur du membre NicName est l’identificateur de instance unique (InstanceId) de la carte réseau physique liée à la carte réseau externe. Ce type de carte réseau est exposé dans le système d’exploitation de gestion qui s’exécute dans la partition parente Hyper-V.
La carte réseau externe fournit une connexion à l’interface réseau physique disponible sur l’hôte. La carte réseau externe est accessible par la partition parente Hyper-V et toutes les partitions enfants.

Note La valeur InstanceId est générée par le gestionnaire de Plug-and-Play qui s’exécute dans le système d’exploitation de gestion.
Si le membre NicType est défini sur NdisSwitchNicTypeInternal, la valeur du membre NicName est le nom d’affichage de l’appareil qui identifie la carte réseau interne. Ce type de carte réseau est exposé dans le système d’exploitation de gestion d’une partition parente Hyper-V.
La carte réseau interne est accessible par la partition parente Hyper-V et toutes les partitions enfants. Toutefois, la carte réseau interne ne se connecte pas à l’interface réseau physique disponible sur l’hôte.

Note Le nom d’affichage de l’appareil est généré par la couche de gestion WMI Hyper-V qui s’exécute dans le système d’exploitation de gestion.
Pour toutes les autres valeurs de membre NicType , la valeur du membre NicName est affectée de manière unique à la carte réseau synthétique ou émulée par l’interface de gestion des stratégies. Ces types de cartes réseau sont exposés dans le système d’exploitation invité qui s’exécute est une partition enfant Hyper-V.

Instructions pour le membre VFAssigned

Une VF PCIe est créée et allouée par une carte physique sous-jacente qui prend en charge l’interface SR-IOV. Une fois la VF PCIe créée, la pile de virtualisation attache ou affecte une partition enfant Hyper-V à la VF. Le système d’exploitation invité qui s’exécute dans cette partition expose une carte réseau de machine virtuelle qui est attachée ou affectée à la carte physique SR-IOV sous-jacente.

Si le membre VFAssigned a la valeur TRUE, les paquets sont acheminés directement entre la carte réseau physique SR-IOV sous-jacente et la carte virtuelle. Toutefois, étant donné que le commutateur extensible n’est pas impliqué dans la remise de paquets, les stratégies de port de commutateur extensible, telles que les listes de contrôle d’accès (ACL), ne sont pas appliquées à ces paquets.

L’extension peut supprimer une affectation VF en émettant une NDIS_STATUS_SWITCH_PORT_REMOVE_VF status indication. Cette indication entraîne la remise des paquets via un port de commutateur extensible plutôt que directement entre la carte réseau de machine virtuelle et la carte physique SR-IOV. Cela permet d’appliquer les stratégies de port de commutateur extensible aux paquets reçus ou envoyés via le port de commutateur extensible. Lorsque l’extension indique le NDIS_STATUS_SWITCH_PORT_REMOVE_VF status, elle spécifie le port de commutateur extensible auquel la carte réseau virtuelle est connectée.

Pour plus d’informations, consultez NDIS_STATUS_SWITCH_PORT_REMOVE_VF.