Prise en charge du débogueur 2PF KDNET

Cette rubrique explique comment activer votre pilote NDIS miniport pour la prise en charge du débogueur 2PF afin d’augmenter les performances des adaptateurs haute vitesse, souvent utilisés dans les centres de données. Cette fonctionnalité est disponible dans Windows 11 et versions ultérieures.

Lors de l’activation du débogage du noyau sur une carte réseau, la prise en charge du débogage du noyau prend en charge l’appareil physique pour fournir un débogage du noyau et une connexion réseau sur la zone. Cela fonctionne correctement sur les cartes réseau à faible bande passante grand public (1 à 10 Gbits/s), mais sur les appareils à débit élevé qui prennent en charge 10 à 40 Gbits/s, les modules d’extensibilité de débogage du noyau qui parlent au matériel ne peuvent généralement pas suivre la quantité de trafic provenant de la pile réseau Windows, de sorte que cela dégrade les performances globales du système.

L’utilisation de la fonctionnalité DE fonction physique multiple (PF) PCI pour KDNET permet de déboguer avec presque aucun impact sur les performances.

La fonction physique (PF) est une fonction PCI Express (PCIe) d’une carte réseau qui prend en charge l’interface de virtualisation d’E/S racine unique (SR-IOV). Le pf inclut la fonctionnalité étendue SR-IOV dans l’espace configuration PCIe. La fonctionnalité est utilisée pour configurer et gérer les fonctionnalités SR-IOV de la carte réseau, telles que l’activation de la virtualisation et l’exposition de fonctions virtuelles PCIe.

Le PF prend en charge la structure de capacité étendue SR-IOV dans son espace de configuration PCIe. Cette structure est définie dans la spécification PCI-SIG Single Root I/O Virtualization and Sharing 1.1.

Le transport du débogueur tirera parti de plusieurs pilotes miniport activés par 2PF. Pour permettre le débogage des systèmes de serveurs à haute vitesse, il est recommandé que les fournisseurs de cartes réseau activent 2PF dans toutes les cartes réseau qui prennent en charge plusieurs PF dans le microprogramme carte réseau.

Pour plus d’informations sur la configuration de la prise en charge de 2PF pour tester une connexion, consultez Configuration du débogage en mode noyau 2PF à l’aide de KDNET.

Vue d’ensemble de l’architecture KDNET PF multiple

• La fonctionnalité PF multiple (2PF) consiste à ajouter/affecter un nouveau PF au port réseau PCI d’origine (par exemple, Bus.dev.fun0.0).

• Le nouveau PF ajouté (par exemple, bus.dev.fun0.1) est utilisé uniquement par KDNET pour acheminer les paquets du débogueur vers/depuis la cible.

• Le pf d’origine sera utilisé par le pilote de carte réseau de boîte de réception Windows pour router les paquets réseau Windows (TCP/IP).

• À l’aide de cette approche, les deux pilotes peuvent travailler en parallèle w/o interférant entre eux.

• Les deux pilotes s’exécutent sur l’espace de configuration PCI partitionné

  • Le pilote de boîte de réception Windows s’exécute sur le port réseau d’origine à bus.dev.fun0.0

  • KDNET-KDNET-Ext. le module va manquer du PF ajouté à bus.dev.fun0.1, de cette façon garantit que le pilote de carte réseau de boîte de réception Windows n’est pas affecté par le partage de la carte réseau avec KDNET.

• L’outil kdnet.exe mode utilisateur configure la fonctionnalité 2PF à l’aide du pilote de boîte de réception Windows en ajoutant des codes IOCTL spécifiques pour ajouter/supprimer KDNET PF.

Exigences de conception de fonctionnalités multiples pour les FS

1. La fonctionnalité KDNET 2PF doit fonctionner pour tous les scénarios KD actuels, qu’il s’agisse du système d’exploitation pré-NT (par exemple, Gestionnaire de démarrage, chargeur de système d’exploitation, WinResume, Hyper-V, SK, etc.), du système d’exploitation NT ou du Bureau Windows.

2. Le redémarrage du système sera nécessaire lors de l’ajout d’un nouveau PF pour un appareil entraîne une modification nécessaire à la configuration BCD pour les paramètres de débogage. Cela signifie que la configuration d’un pf supplémentaire doit être persistante entre les démarrages.

3. Le KDNET 2PF doit être utilisé uniquement par le débogueur pour s’assurer qu’il n’existe aucun autre pilote Ethernet Windows/UEFI accédant/s’exécutant à partir de l’emplacement PCI 2PF lorsque le débogueur possède l’appareil de débogage (l’emplacement 2PF est configuré à l’aide de dbgsettings ::busparams).

4. Les pilotes Ethernet Windows ou UEFI ne peuvent pas manquer du KDNET 2PF ajouté, même si KDNET n’est pas activé dans le système.

5. La fonctionnalité 2PF doit prendre en charge un mécanisme dynamique pour l’ajout/l’activation et la suppression/désactivation de la fonctionnalité sur la carte réseau actuelle.

6. Les pilotes de miniport Windows implémentent la fonctionnalité 2PF via la maintenance des NDIS OID suivants.

Les OID et leurs structures sont définies dans les fichiers ntddndis.h et kdnetpf.h publiés avec le WDK public.

Consultez les détails ci-dessous sur les paramètres d’entrée/sortie pour chaque OID et les informations fournies dans le fichier d’en-tête kdnetpf.h.

7. KDNET doit être configuré via la fonctionnalité KDNET 2PF sur les cartes réseau où plusieurs fonctionnalités PF sont disponibles, et la carte réseau active la fonctionnalité 2PF en suivant toutes les exigences décrites ci-dessus.

Interface KDNET multiple PF pour les pilotes de carte réseau Windows

Pour prendre en charge les pilotes Miniport de l’interface PF multiple KDNET, vous devez implémenter la gestion des quatre OID NDIS suivants.

• OID_KDNET_ENUMERATE_PFS

• OID_KDNET_ADD_PF

• OID_KDNET_REMOVE_PF

• OID_KDNET_QUERY_PF_INFORMATION

Ces OID et structures sont renseignées dans les fichiers ntddndis.h et kdnetpf.h dans la version publique de WDK sur ce chemin :

<WDK root directory>\ddk\inc\ndis

Ces fichiers sont également disponibles dans le Kit de développement logiciel (SDK) Windows et se trouvent dans ce répertoire.

\Program Files (x86)\Windows Kits\10\Include\<Version for example 10.0.21301.0>\shared

L’outil client (kdnet.exe) utilise une NDIS IOCTL privée pour acheminer les OID NDIS KDNET 2PF vers les pilotes miniports.

Les OID NDIS multiples de fonctionnalités PF

La fonctionnalité PF multiple est exploitée à l’aide de ces quatre OID NDIS.

1. Énumérez les FDF sur le port principal BDF miniport à l’aide de l’OID : OID_KDNET_ENUMERATE_PFS, voir la définition ci-dessous.

• OID_KDNET_ENUMERATE_PFS retourne une liste de tous les fichiers BDF associés au port principal donné à partir duquel le pilote miniport s’exécute. Le port est représenté par le bus.dev.fun (BDF). L’opération répertorie/énumère la liste des fichiers PFs associés uniquement au bus.dev.fun (port BDF) à partir duquel le pilote miniport s’exécute sur le système, car chaque pilote miniport peut déterminer son emplacement BDF.

• La liste des FS est retournée au client via une opération de requête NDIS.

• L’OID OID_KDNET_ENUMERATE_PFS est associé à la structure NDIS_KDNET_ENUMERATE_PFS .

• Le gestionnaire de pilotes OID_KDNET_ENUMERATE_PFS retournera une mémoire tampon contenant la liste des FS avec chaque élément PF décrit par le type NDIS_KDNET_PF_ENUM_ELEMENT.

  Le champ PfNumber contient le numéro de fonction PF (par exemple, bus.dev.fun)

  Le champ PfState contient les valeurs possibles de l’état PF : chaque type d’élément décrit par NDIS_KDNET_PF_STATE énumération.

  NDIS_KDNET_PF_STATE ::NdisKdNetPfStatePrimary : il s’agit d’un PF principal et il est généralement utilisé uniquement par le pilote miniport.

  NDIS_KDNET_PF_STATE ::NdisKdnetPfStateEnabled : il s’agit d’un PF secondaire ajouté, utilisé par KDNET.

  NDIS_KDNET_PF_STATE ::NdisKdnetPfStateConfigured : il s’agit d’un PF ajouté, mais il est uniquement ajouté/configuré et n’est pas utilisé.

• Si la taille de la mémoire tampon de sortie de la liste PF n’est pas suffisante pour allouer la liste PFs réelle, le gestionnaire OID doit retourner E_NOT_SUFFICIENT_BUFFER la valeur de retour d’erreur, ainsi que la taille de mémoire tampon requise, afin que l’outil client puisse allouer la mémoire tampon de taille requise, puis le client peut effectuer un autre appel avec la taille de mémoire tampon appropriée allouée. En outre, le champ d’état de la demande OID (décrit par NDIS_IOCTL_OID_REQUEST_INFO.status) doit être défini sur égal à NDIS_STATUS_BUFFER_TOO_SHORT.

2. Ajouter PCI PF au port principal BDF miniport (OID : OID_KDNET_ADD_PF, voir la définition ci-dessous)

• Ajoutez un PF au port principal miniport. Le port est représenté par la fonction BDF.

• Le pf nouvellement ajouté est retourné au client via une opération de requête NDIS.

• L’OID OID_KDNET_ADD_PF est associé à la structure NDIS_KDNET_ADD_PF.

• Le gestionnaire de pilotes OID_KDNET_ADD_PF retourne un ULONG contenant le numéro de fonction PF ajouté .

• Cette requête OID n’aura qu’un seul paramètre de sortie : AddedFunctionNumber. Indique AddedFunctionNumber la valeur de numéro de fonction ajoutée à l’emplacement PCI miniport (miniport BDF). L’utilitaire kdnet.exe reçoit cette valeur et configure dbgsettings ::busparams pour qu’il pointe vers le PF ajouté.

3. Supprimer PCI PF (OID : OID_KDNET_REMOVE_PF, voir la définition ci-dessous)

• Supprimez un pf du port donné. Le port est représenté par la fonction BDF.

• L’OID OID_KDNET_REMOVE_PF est associé à la structure NDIS_KDNET_REMOVE_PF .

• L’OID OID_KDNET_REMOVE_PF a un port BDF d’entrée et retourne un ULONG contenant le numéro de fonction PF supprimé via une opération de méthode NDIS.

• Cette fonction réussit uniquement sur les FS qui ont été ajoutées à l’aide de l’OID OID_KDNET_ADD_PF .

• Cette requête OID aura le port BDF d’entrée à partir duquel doit être supprimé la fonction BDF. Cette fonction a un paramètre Output de FunctionNumber. La sortie FunctionNumber contient la valeur du numéro de fonction supprimé.

4. Interroger les informations PCI PF (OID : OID_KDNET_QUERY_PF_INFORMATION, voir la définition ci-dessous)

• Ce code OID permet d’interroger des données PF spécifiques sur un port donné. Le port est représenté par la fonction BDF.

• Les informations PF demandées sont retournées au client via une opération de méthode NDIS.

• L’OID OID_KDNET_QUERY_PF_INFORMATION est associé à la structure NDIS_KDNET_QUERY_PF_INFORMATION .

• L’OID OID_KDNET_QUERY_PF_INFORMATION a un port BDF d’entrée et retourne une mémoire tampon contenant les données suivantes :

  • Adresse MAC : adresse réseau du nouveau KDNET PF attribué s’il existe.

  • Balise d’utilisation : décrit l’entité propriétaire du port PF. Elle contient une valeur constante décrite par NDIS_KDNET_PF_USAGE_TAG énumération.

  • Nombre maximal de FS : contient un ULONG avec le nombre maximal de FS pouvant être ajoutés à la fonction BDF donnée.

  • ID d’appareil : contient l’ID d’appareil associé au port BDF donné. Cela est nécessaire pour les cas où le FW de la carte réseau affecte un nouvel ID d’appareil au nouveau port KDNET PF ajouté.

• Cet OID demande les informations relatives à tout port BDF transmis (BDF est un paramètre d’entrée pour cette opération), de sorte qu’il n’est pas nécessairement lié à la fonction BDF actuelle à partir de laquelle le pilote s’exécute.

NDIS OID pour KDNET sur 2PF

Le fichier Ntddndis.h définit les OID.

#if (NDIS_SUPPORT_NDIS686)

 //

 // Optional OIDs to handle network multiple PF feature.

 //
#define OID_KDNET_ENUMERATE_PFS 0x00020222
#define OID_KDNET_ADD_PF 0x00020223
#define OID_KDNET_REMOVE_PF 0x00020224
#define OID_KDNET_QUERY_PF_INFORMATION 0x00020225
#endif // (NDIS_SUPPORT_NDIS686)

Le fichier Kdnetpf.h décrit le type et les structures associés aux OID NDIS.

#if (NDIS_SUPPORT_NDIS686)

 //
 // Used to query/add/remove Physical function on a network port.
 // These structures are used by these OIDs:
 // OID_KDNET_ENUMERATE_PFS
 // OID_KDNET_ADD_PF
 // OID_KDNET_REMOVE_PF
 // OID_KDNET_QUERY_PF_INFORMATION
 // These OIDs handle PFs that are primary intended to be used by  KDNET.
 //
 //
 // PCI location of the port to query
 //
 typedef struct _NDIS_KDNET_BDF
 {
 ULONG SegmentNumber;
 ULONG BusNumber;
 ULONG DeviceNumber;
 ULONG FunctionNumber;
 ULONG Reserved;
 } NDIS_KDNET_BDF, *PNDIS_KDNET_PCI_BDF;

 //
 // PF supported states.
 //
 typedef enum _NDIS_KDNET_PF_STATE
 {
 NdisKdNetPfStatePrimary = 0x0,
 NdisKdnetPfStateEnabled = 0x1,
 NdisKdnetPfStateConfigured = 0x2,
 } NDIS_KDNET_PF_STATE,*PNDIS_KDNET_PF_STATE;

 //
 // PF Usage Tag
 // Used to indicate the entity that owns the PF.
 // Used by the query NdisKdnetQueryUsageTag.
 //
 typedef enum _NDIS_KDNET_PF_USAGE_TAG
 {
 NdisKdnetPfUsageUnknown = 0x0,
 NdisKdnetPfUsageKdModule = 0x1,
 } NDIS_KDNET_PF_USAGE_TAG,*PNDIS_KDNET_PF_USAGE_TAG;

 //
 // PF element array structure
 //
 typedef struct _NDIS_KDNET_PF_ENUM_ELEMENT
 {
 NDIS_OBJECT_HEADER Header;

 //
 // PF value (e.g. if <bus.dev.fun>, then PF value = fun)
 //
 ULONG PfNumber;

 //
 // The PF state value (defined by NDIS_KDNET_PF_STATE)
 //
 NDIS_KDNET_PF_STATE PfState;

 } NDIS_KDNET_PF_ENUM_ELEMENT, *PNDIS_KDNET_PF_ENUM_ELEMENT;
#define NDIS_KDNET_PF_ENUM_ELEMENT_REVISION_1 1
#define NDIS_SIZEOF_KDNET_PF_ENUM_ELEMENT_REVISION_1 \
 RTL_SIZEOF_THROUGH_FIELD(NDIS_KDNET_PF_ENUM_ELEMENT, PfState)

 //
 // This structure describes the data required to enumerate the list of PF
 // Used by OID_KDNET_ENUMERATE_PFS.
 //
 typedef struct _NDIS_KDNET_ENUMERATE_PFS
 {
 NDIS_OBJECT_HEADER Header;

 //
 // The size of each element is the sizeof(NDIS_KDNET_PF_ENUM_ELEMENT)
 //
 ULONG ElementSize;

 //
 // The number of elements in the returned array
 //
 ULONG NumberOfElements;

 //
 // Offset value to the first element of the returned array.
 // Each array element is defined by NDIS_KDNET_PF_ENUM_ELEMENT.
 //
 ULONG OffsetToFirstElement;
 } NDIS_KDNET_ENUMERATE_PFS, *PNDIS_KDNET_ENUMERATE_PFS;

#define NDIS_KDNET_ENUMERATE_PFS_REVISION_1 1
#define NDIS_SIZEOF_KDNET_ENUMERATE_PFS_REVISION_1 \
 RTL_SIZEOF_THROUGH_FIELD(NDIS_KDNET_ENUMERATE_PFS,
 OffsetToFirstElement)

 //
 // This structure indicates the data required to add a PF to the BDF port.
 // Used by OID_KDNET_ADD_PF.
 //
 typedef struct _NDIS_KDNET_ADD_PF
 {
 NDIS_OBJECT_HEADER Header;

 //
 // One element containing the added PF port number
 //
 ULONG AddedFunctionNumber;
 } NDIS_KDNET_ADD_PF, *PNDIS_KDNET_ADD_PF;

#define NDIS_KDNET_ADD_PF_REVISION_1 1
#define NDIS_SIZEOF_KDNET_ADD_PF_REVISION_1 \
 RTL_SIZEOF_THROUGH_FIELD(NDIS_KDNET_ADD_PF, AddedFunctionNumber)

 //
 // This structure indicates the data required to remove a PF from the BDF port.
 // Used by OID_KDNET_REMOVE_PF.
 //

 typedef struct _NDIS_KDNET_REMOVE_PF
 {
 NDIS_OBJECT_HEADER Header;

 //
 // PCI location that points to the PF that needs to be removed
 //
 NDIS_KDNET_BDF Bdf;

 //
 // One element containing the removed PF port
 //
 ULONG FunctionNumber;
 } NDIS_KDNET_REMOVE_PF, *PNDIS_KDNET_REMOVE_PF;
#define NDIS_KDNET_REMOVE_PF_REVISION_1 1
#define NDIS_SIZEOF_KDNET_REMOVE_PF_REVISION_1 \
 RTL_SIZEOF_THROUGH_FIELD(NDIS_KDNET_REMOVE_PF, FunctionNumber)

 //
 // This structure describes the data required to query the PF management data
 // Used by OID_KDNET_QUERY_PF_INFORMATION
 //
 typedef struct _NDIS_KDNET_QUERY_PF_INFORMATION
 {
 NDIS_OBJECT_HEADER Header;

 //
 // PF PCI location to query for
 //
 NDIS_KDNET_BDF Bdf;

 //
 // PF assigned MAC address
 //
 UCHAR NetworkAdddress[6];

 //
 // PF Usage tag described by NDIS_KDNET_PF_USAGE_TAG
 //
 ULONG UsageTag;

 //
 // Maximum number of Pfs that can be associated to the Primary BDF.
 //
 ULONG MaximumNumberOfSupportedPfs;

 //
 // KDNET PF device ID (Used if there is a new added PF and
 // the FW assigns a new DeviceID to the added KDNET PF)
 //
 ULONG DeviceId;

 } NDIS_KDNET_QUERY_PF_INFORMATION, *PNDIS_KDNET_QUERY_PF_INFORMATION;
#define NDIS_KDNET_QUERY_PF_INFORMATION_REVISION_1 1
#define NDIS_SIZEOF_KDNET_QUERY_PF_INFORMATION_REVISION_1 \
 RTL_SIZEOF_THROUGH_FIELD(NDIS_KDNET_QUERY_PF_INFORMATION, DeviceId)

#endif // (NDIS_SUPPORT_NDIS686)

Voir aussi

Configuration du débogage en mode noyau 2PF à l’aide de KDNET

OID réseau

en-tête kdnetpf.h