Debugger 2PF KDNET-Unterstützung

In diesem Thema wird beschrieben, wie Sie Ihren Miniport-NDIS-Treiber für die Unterstützung von 2PF-Debuggern aktivieren, um eine höhere Leistung für Hochgeschwindigkeitsadapter zu ermöglichen, die häufig in Rechenzentren verwendet werden. Dieses Feature ist in Windows 11 und höher verfügbar.

Beim Aktivieren des Kerneldebuggings auf einer NIC übernimmt die Kerneldebuggingunterstützung das physische Gerät, um sowohl ein Kerneldebugging als auch eine Netzwerkverbindung im Feld bereitzustellen. Dies funktioniert gut für NiCs mit geringer Bandbreite für Verbraucher (1 bis 10 GBit/s). Auf Geräten mit hohem Durchsatz, die 10 bis 40 GBit/s unterstützen, können Kerneldebuggingerweiterungsmodule jedoch nicht mit dem Datenverkehr aus dem Windows-Netzwerkstapel schritt halten. Daher wird die Gesamtleistung des Systems beeinträchtigt.

Die Verwendung der FUNKTION PCI multiple Physical Function (PF) für KDNET ermöglicht die Aktivierung des Debuggings ohne Leistungseinbußen.

Die physische Funktion (PF) ist eine PCI Express(PCIe)-Funktion eines Netzwerkadapters, der die einzelne I/O-Virtualisierungsschnittstelle (SR-IOV) unterstützt. Die PF enthält die SR-IOV erweiterten Funktionen im PCIe-Konfigurationsbereich. Die Funktion wird verwendet, um die SR-IOV Funktionen des Netzwerkadapters zu konfigurieren und zu verwalten, z. B. zum Aktivieren der Virtualisierung und Zum Verfügbarmachen von virtuellen PCIe-Funktionen (VFs).

Die PF unterstützt die SR-IOV Extended Capability-Struktur im PCIe-Konfigurationsbereich. Diese Struktur wird in der spezifikation PCI-SIG Single Root I/O Virtualization and Sharing 1.1definiert.

Der Debuggertransport nutzt mehrere oder 2PF-aktivierte Miniporttreiber. Um das Debuggen von Systemen mit Hochgeschwindigkeitsservern zu ermöglichen, wird empfohlen, dass NIC-Anbieter 2PF in allen NICs aktivieren, die mehrere PF in der Netzwerkkartenfirmware unterstützen.

Informationen zum Konfigurieren der 2PF-Unterstützung zum Testen einer Verbindung finden Sie unter Einrichten von 2PF-Kernel-Mode Debugging mithilfe von KDNET-.

Übersicht über mehrere PF-KDNET-Architekturen

• Die Funktion "Multiple PF(2PF)" besteht darin, dem ursprünglichen PCI-Netzwerkanschluss (z. B. Bus.dev.fun0.0) einen neuen PF hinzuzufügen/zuzuweisen.

• Die neue hinzugefügte PF (z. B. bus.dev.fun0.1) wird nur von KDNET verwendet, um Debuggerpakete an/vom Ziel zu leiten.

• Der Windows-Posteingangs-NIC-Treiber verwendet den ursprünglichen PF zum Weiterleiten von Windows-Netzwerkpaketen (TCP/IP).

• Bei verwendung dieses Ansatzes können beide Faktoren parallel arbeiten, indem sie sich gegenseitig stören.

• Beide Treiber werden über den partitionierten PCI-Konfigurationsraum ausgeführt

  • Der Windows-Posteingangstreiber ist bei bus.dev außerhalb des ursprünglichen Netzwerkports. fun0.0

  • KDNET-KDNET-Ext. das Modul läuft bei bus.dev aus dem hinzugefügten PF aus. fun0.1, Auf diese Weise wird sichergestellt, dass der Windows-Posteingangs-NIC-Treiber nicht durch die Freigabe der NIC mit KDNET beeinträchtigt wird.

• Das kdnet.exe Benutzermodustool konfiguriert das 2PF-Feature mithilfe des Windows-Posteingangstreibers, indem bestimmte IOCTL-Codes hinzugefügt werden, um KDNET PF hinzuzufügen/zu entfernen.

Designanforderungen für mehrere PFs

1. Das KDNET 2PF-Feature muss für alle aktuellen KD-Szenarien funktionieren, unabhängig davon, ob es sich um das Vorab-NT-Betriebssystem handelt (z. B. Start-Manager, Betriebssystemladeprogramm, WinResume, Hyper-V, SK usw.), NT OS oder Windows Desktop.

2. Ein Systemneustart ist erforderlich, wenn das Hinzufügen eines neuen PF für ein Gerät die BCD-Konfiguration für Debuggingeinstellungen ändert. Diese Anforderung bedeutet, dass die Konfiguration für einen zusätzlichen PF für den Start beständig sein muss.

3. Verwenden Sie KDNET 2PF nur für das Debuggen. Dadurch wird sichergestellt, dass kein Windows- oder UEFI-Ethernet-Treiber auf den PCI 2PF-Speicherort zugreift, wenn der Debugger das Gerät besitzt. Der 2PF-Speicherort wird mithilfe von dbgsettings::busparams konfiguriert.

4. Windows- oder UEFI-Ethernet-Treiber können nicht mehr über das hinzugefügte KDNET 2PF verfügen, auch wenn KDNET nicht im System aktiviert ist.

5. Das 2PF-Feature sollte einen dynamischen Mechanismus zum Hinzufügen/Aktivieren und Entfernen/Deaktivieren der Funktionalität auf der aktuellen NIC unterstützen.

6. Die Windows Miniport-Treiber implementieren das 2PF-Feature über die Wartung der folgenden NDIS-OIDs.

Die OIDs und ihre Strukturen werden in ntddndis.h- und kdnetpf.h-Dateien definiert, die mit dem öffentlichen WDK veröffentlicht werden.

Lesen Sie die folgenden Details zu den Eingabe-/Ausgabeparametern für jedes OID und die informationen, die in der Headerdatei "kdnetpf.h" angegeben sind.

7. Konfigurieren Sie KDNET mithilfe des KDNET 2PF-Features auf NICs, die mehrere PFs unterstützen. Stellen Sie sicher, dass die NIC alle in diesem Abschnitt beschriebenen Anforderungen erfüllt, um die 2PF-Funktionalität zu aktivieren.

KDNET Multiple PF Interface für Windows NIC-Treiber

Um die KDNET Multiple PF Interface zu unterstützen, müssen Miniport-Treiber die Behandlung der folgenden vier NDIS-OIDs implementieren.

• OID_KDNET_ENUMERATE_PFS

• OID_KDNET_ADD_PF

• OID_KDNET_REMOVE_PF

• OID_KDNET_QUERY_PF_INFORMATION

Diese OIDs und Strukturen werden in den Dateien ntddndis.h und kdnetpf.h in der öffentlichen WDK-Version auf diesem Pfad aufgefüllt:

<WDK root directory>\ddk\inc\ndis

Diese Dateien sind auch im Windows SDK verfügbar und finden Sie in diesem Verzeichnis.

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

Das Clienttool (kdnet.exe) verwendet eine private NDIS IOCTL, um die KDNET 2PF NDIS OIDs an die Miniporttreiber weiterzuleiten.

Die Mehrfach-PF-Funktion NDIS-OIDs

Das Feature "Multiple PF" wird mit diesen vier NDIS-OIDs betrieben.

1. Aufzählen von PFs auf dem primären Miniport-BDF-Port mithilfe von OID: OID_KDNET_ENUMERATE_PFS, siehe folgende Definition.

• OID_KDNET_ENUMERATE_PFS gibt eine Liste aller BDFs zurück, die dem angegebenen primären Port zugeordnet sind, von dem der Miniporttreiber ausgeführt wird. Der bus.dev.fun (BDF) stellt den Port dar. Der Vorgang listet die PFs auf, die nur dem bus.dev.fun (BDF-Port) zugeordnet sind, in dem der Miniporttreiber ausgeführt wird. Jeder Miniporttreiber kann seinen BDF-Speicherort ermitteln.

• Die Liste der PFs wird über einen NDIS-Abfragevorgang an den Client zurückgegeben.

• Die OID_KDNET_ENUMERATE_PFS OID ist der NDIS_KDNET_ENUMERATE_PFS Struktur zugeordnet.

• Der OID_KDNET_ENUMERATE_PFS Treiberhandler gibt einen Puffer zurück, der die Liste der PFs mit jedem PF-Element enthält, das vom Typ NDIS_KDNET_PF_ENUM_ELEMENT beschrieben wird.

  Das Feld "PfNumber" enthält die PF-Funktionsnummer (z. B. bus.dev.Spaß)

  Das Feld "PfState" enthält den PF-Zustand, die möglichen Werte enthalten. Jeder Elementtyp, der durch NDIS_KDNET_PF_STATE Enumeration beschrieben wird.

  NDIS_KDNET_PF_STATE::NdisKdNetPfStatePrimary – Dies ist eine primäre PF und wird normalerweise nur vom Miniporttreiber verwendet.

  NDIS_KDNET_PF_STATE::NdisKdnetPfStateEnabled – Dies ist eine hinzugefügte sekundäre PF, die von KDNET verwendet wird.

  NDIS_KDNET_PF_STATE::NdisKdnetPfStateConfigured – Dies ist eine hinzugefügte PF, aber sie wird nur hinzugefügt/konfiguriert und nicht verwendet.

• Wenn die Größe des PF-Listenausgabepuffers nicht groß genug ist, um die tatsächliche Liste der PFs zuzuweisen, muss der OID-Handler fehlerrückgabewert zusammen mit der erforderlichen Puffergröße zurückgeben E_NOT_SUFFICIENT_BUFFER , damit das Clienttool den erforderlichen Größenpuffer zuordnen kann, und der Client kann dann einen weiteren Aufruf mit der richtigen Puffergröße vornehmen. Darüber hinaus sollte das OID-Anforderungsstatusfeld (beschrieben durch NDIS_IOCTL_OID_REQUEST_INFO.status) auf "gleich" NDIS_STATUS_BUFFER_TOO_SHORTfestgelegt werden.

2. Hinzufügen von PCI PF zum primären Miniport-BDF-Port (OID: OID_KDNET_ADD_PF, siehe folgende Definition)

• Fügen Sie einen PF zum primären Miniportport hinzu. Der bus.dev.fun (BDF) stellt den Port dar.

• Die neu hinzugefügte PF wird über einen NDIS-Abfragevorgang an den Client zurückgegeben.

• Das OID_KDNET_ADD_PF OID ist der NDIS_KDNET_ADD_PF Struktur zugeordnet.

• Der OID_KDNET_ADD_PF Treiberhandler gibt einen ULONG zurück, der die hinzugefügte PF-Funktionsnummer enthält.

• Diese OID-Anforderung hat nur einen Ausgabeparameter: AddedFunctionNumber. Der AddedFunctionNumber gibt den zusätzlichen Funktionsnummernwert an der Miniport-PCI-Position (BDF-Miniport) an. Das hilfsprogramm kdnet.exe empfängt diesen Wert und setup dbgsettings::busparams, um auf die hinzugefügte PF zu zeigen.

3. ENTFERNEN PCI PF (OID: OID_KDNET_REMOVE_PF, siehe folgende Definition)

• Entfernen Sie eine PF aus dem angegebenen Port. Der bus.dev.fun (BDF) stellt den Port dar.

• Die OID_KDNET_REMOVE_PF OID ist der NDIS_KDNET_REMOVE_PF Struktur zugeordnet.

• Der OID_KDNET_REMOVE_PF OID verfügt über einen BDF-Eingabeport und gibt eine ULONG zurück, die die entfernt PF-Funktionsnummer über einen NDIS-Methodenvorgang zurückgibt.

• Diese Funktion ist nur auf den PFs erfolgreich, die mithilfe des OID_KDNET_ADD_PF OID hinzugefügt wurden.

• Diese OID-Anforderung verfügt über den BDF-Eingabeport, von dem die BDF entfernt werden muss. Diese Funktion weist einen Ausgabeparameter von FunctionNumberauf. Die Ausgabe FunctionNumber enthält den entfernten Funktionsnummernwert.

4. Abfrage PCI PF-Informationen (OID: OID_KDNET_QUERY_PF_INFORMATION, siehe folgende Definition)

• Dieser OID-Code ermöglicht das Abfragen bestimmter PF-Daten auf einem angegebenen Port. Der bus.dev.fun (BDF) stellt den Port dar.

• Die angeforderten PF-Informationen werden über einen NDIS-Methodenvorgang an den Client zurückgegeben.

• Die OID_KDNET_QUERY_PF_INFORMATION OID ist der NDIS_KDNET_QUERY_PF_INFORMATION Struktur zugeordnet.

• Der OID_KDNET_QUERY_PF_INFORMATION OID verfügt über einen BDF-Eingabeport und gibt einen Puffer zurück, der die folgenden Daten enthält:

  • MAC-Adresse: Netzwerkadresse des zugewiesenen neuen KDNET PF, falls vorhanden.

  • Verwendungstag: Beschreibt die Entität, die den PF-Port besitzt. Sie enthält einen konstanten Wert, der durch NDIS_KDNET_PF_USAGE_TAG Enumeration beschrieben wird.

  • Maximale Anzahl von PFs: Enthält eine ULONG mit der maximalen Anzahl von PFs, die der angegebenen BDF hinzugefügt werden können.

  • Geräte-ID: Enthält die Geräte-ID, die dem angegebenen BDF-Port zugeordnet ist. Dies ist für Fälle erforderlich, in denen die NIC FW dem neuen hinzugefügten KDNET PF-Port eine neue Geräte-ID zuweist.

• Diese OID fordert die Informationen für alle übergebenen BDF-Port an (BDF ist ein Eingabeparameter für diesen Vorgang). Es ist nicht notwendigerweise mit dem aktuellen BDF verbunden, von dem der Treiber ausgeführt wird.

NDIS OIDs für KDNET auf 2PF

Ntddndis.h Datei definiert die OIDs.

#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)

Datei "Kdnetpf.h" beschreibt den Typ und die Strukturen, die den NDIS-OIDs zugeordnet sind.

#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 (for example, 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's 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)

Siehe auch

Einrichten von 2PF-Kernel-Mode Debuggen mithilfe von KDNET-

Netzwerk-OIDs

kdnetpf.h-Header