Obsługa debugera 2PF KDNET

W tym temacie opisano, jak włączyć sterownik NDIS miniportu dla obsługi debugera 2PF, aby umożliwić zwiększenie wydajności kart o dużej szybkości, często używanych w centrach danych. Ta funkcja jest dostępna w systemie Windows 11 lub nowszym.

Podczas włączania debugowania jądra na karcie sieciowej obsługa debugowania jądra przejmuje urządzenie fizyczne w celu zapewnienia debugowania jądra i połączenia sieciowego w polu. Działa to dobrze w przypadku kart sieciowych o niskiej przepustowości (1–10 Gb/s), ale na urządzeniach o wysokiej przepływności obsługującej 10-40 Gb/s moduły rozszerzalności jądra, które komunikują się ze sprzętem, zazwyczaj nie mogą nadążyć za ilością ruchu pochodzącego ze stosu sieciowego systemu Windows, więc obniża to ogólną wydajność systemu.

Korzystanie z funkcji PCI multiple Physical Function (PF) dla sieci KDNET umożliwia włączenie debugowania bez wpływu na wydajność.

Funkcja fizyczna (PF) jest funkcją PCI Express (PCIe) karty sieciowej obsługującej jeden główny interfejs wirtualizacji we/wy (SR-IOV). PF zawiera rozszerzoną funkcję SR-IOV w przestrzeni konfiguracji PCIe. Ta funkcja służy do konfigurowania SR-IOV funkcji karty sieciowej i zarządzania nimi, takich jak włączanie wirtualizacji i uwidacznianie funkcji wirtualnych PCIe (VFs).

Plik PF obsługuje strukturę SR-IOV rozszerzonej możliwości w przestrzeni konfiguracji PCIe. Ta struktura jest zdefiniowana w specyfikacji PCI-SIG Single Root I/O Virtualization and Sharing 1.1.

Transport debugera skorzysta z wielu lub 2PF z włączonymi miniportami sterowników. Aby umożliwić debugowanie systemów serwerów o dużej szybkości, zaleca się, aby dostawcy kart interfejsu sieciowego włączyli 2PF we wszystkich kartach sieciowych obsługujących wiele pf w oprogramowaniu układowym kart sieciowych.

Aby uzyskać informacje na temat konfigurowania obsługi 2PF w celu przetestowania połączenia, zobacz Konfigurowanie debugowania 2PF Kernel-Mode przy użyciuKDNET.

Omówienie wielu architektur PF KDNET

• Funkcja Multiple PF (2PF) polega na dodaniu/przypisaniu nowego pf do oryginalnego portu sieciowego PCI (np. Bus.dev.fun0.0).

• Nowy dodany plik PF (np. bus.dev.fun0.1) jest używany tylko przez sieć KDNET do kierowania pakietów debugera do/z miejsca docelowego.

• Oryginalny plik PF będzie używany przez sterownik karty sieciowej skrzynki odbiorczej systemu Windows do kierowania pakietów sieciowych systemu Windows (TCP/IP) .

• Użycie tego podejścia może działać równolegle w/w/o zakłócając pracę między sobą.

• Oba sterowniki będą uruchamiane przez partycjonowaną przestrzeń konfiguracji PCI

  • Sterownik skrzynki odbiorczej systemu Windows zabraknie oryginalnego portu sieciowego w bus.dev.fun0.0

  • KDNET-KDNET-Ext. Moduł zabraknie dodanego pliku PF w bus.dev.fun0.1, w ten sposób zapewnia, że sterownik karty sieciowej skrzynki odbiorczej systemu Windows nie będzie mieć wpływu na udostępnianie karty sieciowej z KDNET.

• Narzędzie trybu użytkownika kdnet.exe konfiguruje funkcję 2PF przy użyciu sterownika skrzynki odbiorczej systemu Windows przez dodanie określonych kodów IOCTL w celu dodania/usunięcia KDNET PF.

Wymagania dotyczące projektowania wielu funkcji PFS

1. Funkcja KDNET 2PF musi działać dla wszystkich bieżących scenariuszy KD niezależnie od tego, czy jest to system operacyjny przed NT (np. Menedżer rozruchu, moduł ładujący systemu operacyjnego, WinResume, Hyper-V, SK itp.), NT OS lub Windows Desktop.

2. Ponowne uruchomienie systemu będzie wymagane podczas dodawania nowego pf dla urządzenia powoduje zmianę wymaganą do konfiguracji BCD na potrzeby debugowania ustawień. Oznacza to, że konfiguracja dodatkowego pf musi być trwała w rozruchach.

3. KDNET 2PF powinien być używany tylko przez debuger, aby upewnić się, że nie ma żadnego innego sterownika ethernet systemu Windows/UEFI dostęp/działa z lokalizacji PCI 2PF, gdy debuger jest właścicielem urządzenia debugowania (lokalizacja 2PF jest skonfigurowana przy użyciu dbgsettings::busparams).

4. Sterowniki Ethernet systemu Windows lub UEFI nie mogą zabrakło dodanego KDNET 2PF nawet wtedy, gdy KDNET nie jest włączony w systemie.

5. Funkcja 2PF powinna obsługiwać dynamiczny mechanizm dodawania/włączania i usuwania/wyłączania funkcji bieżącej karty sieciowej.

6. Sterowniki miniportu systemu Windows zaimplementują funkcję 2PF za pośrednictwem obsługi następujących identyfikatorów OID NDIS.

Nazwa OID	Opis
OID_KDNET_ENUMERATE_PFS	Wylicza pliki PFs w bieżącym bus.dev.fun (BDF), gdzie jest uruchomiony sterownik miniportu.
OID_KDNET_ADD_PF	Dodaje pf do bieżącej usługi BDF, w której jest uruchomiony sterownik miniportu.
OID_KDNET_REMOVE_PF	Usuwa dodany plik PF z przekazanego pliku BDF.
OID_KDNET_QUERY_PF_INFORMATION	Wysyła zapytania do danych dotyczących informacji PF przekazanych w usłudze BDF.

Identyfikatory OID i ich struktury są definiowane w plikach ntddndis.h i kdnetpf.h, które są wydawane za pomocą publicznego zestawu WDK.

Zapoznaj się z poniższymi szczegółami dotyczącymi parametrów wejściowych/wyjściowych dla każdego identyfikatora OID oraz informacji podanych w pliku nagłówkowym kdnetpf.h.

7. KDNET należy skonfigurować za pośrednictwem funkcji KDNET 2PF na kartach sieciowych, w których jest dostępna wiele funkcji PF, a karta sieciowa włącza funkcję 2PF, postępując zgodnie z wszystkimi wymaganiami opisanymi powyżej.

KDNET — wiele interfejsów PF dla sterowników kart interfejsu sieciowego systemu Windows

Aby obsługiwać sterowniki KDNET Multiple PF Interface Miniport, należy zaimplementować obsługę następujących czterech identyfikatorów OID NDIS.

• OID_KDNET_ENUMERATE_PFS

• OID_KDNET_ADD_PF

• OID_KDNET_REMOVE_PF

• OID_KDNET_QUERY_PF_INFORMATION

Te identyfikatory operacyjnego i struktury są wypełniane w plikach ntddndis.h i kdnetpf.h w publicznej wersji zestawu WDK w tej ścieżce:

<WDK root directory>\ddk\inc\ndis

Te pliki są również dostępne w zestawie Windows SDK i można je znaleźć w tym katalogu.

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

Narzędzie klienta (kdnet.exe) używa prywatnego identyfikatora IOCTL NDIS do kierowania identyfikatorów OID KDNET 2PF NDIS do sterowników miniportu.

Identyfikatory operacyjnego NDIS funkcji Wiele pf

Funkcja Multiple PF jest obsługiwana przy użyciu tych czterech identyfikatorów OID NDIS.

1. Wyliczanie plików PFs na miniportowym porcie podstawowym BDF przy użyciu identyfikatora OID: OID_KDNET_ENUMERATE_PFS, zobacz definicję poniżej.

• OID_KDNET_ENUMERATE_PFS zwraca listę wszystkich plików BDFs skojarzonych z danym portem podstawowym, z którego jest uruchomiony sterownik miniportu. Port jest reprezentowany przez bus.dev.fun (BDF). Operacja będzie wyświetlać/wyliczać listę plików PFs, które są skojarzone tylko z bus.dev.fun (port BDF), z którego sterownik miniportu jest uruchomiony w systemie, ponieważ każdy sterownik miniportu może określić jego lokalizację BDF.

• Lista plików PFs zostanie zwrócona klientowi za pośrednictwem operacji zapytania NDIS.

• Identyfikator OID OID_KDNET_ENUMERATE_PFS jest skojarzony ze strukturą NDIS_KDNET_ENUMERATE_PFS.

• Program obsługi sterowników OID_KDNET_ENUMERATE_PFS zwróci bufor zawierający listę plików PFS z każdym elementem PF opisanym przez typ NDIS_KDNET_PF_ENUM_ELEMENT.

  Pole PfNumber zawiera numer funkcji PF (np. bus.dev.fun)

  Pole PfState zawiera możliwe wartości stanu PF — każdy typ elementu opisany przez wyliczenie NDIS_KDNET_PF_STATE.

  NDIS_KDNET_PF_STATE::NdisKdNetPfStatePrimary — jest to podstawowy plik PF, który jest zwykle używany tylko przez sterownik miniportu.

  NDIS_KDNET_PF_STATE::NdisKdnetPfStateEnabled — jest to dodatkowy pomocniczy plik PF używany przez sieć KDNET.

  NDIS_KDNET_PF_STATE::NdisKdnetPfStateConfigured — jest to dodany plik PF, ale jest dodawany/skonfigurowany i nie jest używany.

• Jeśli rozmiar buforu wyjściowego listy PF nie jest wystarczająco duży, aby przydzielić rzeczywistą listę plików PFs, program obsługi identyfikatorów OID musi zwrócić E_NOT_SUFFICIENT_BUFFER wartość zwracaną przez błąd wraz z wymaganym rozmiarem buforu, więc narzędzie klienckie może przydzielić wymagany bufor rozmiaru, a następnie klient może wykonać kolejne wywołanie z przydzielonym prawidłowym rozmiarem buforu. Ponadto pole stanu żądania identyfikatora OID (opisane przez NDIS_IOCTL_OID_REQUEST_INFO.status) powinno mieć wartość równą NDIS_STATUS_BUFFER_TOO_SHORT.

2. Dodaj interfejs PCI PF do portu podstawowego usługi BDF miniportu (identyfikator OID: OID_KDNET_ADD_PF, zobacz definicję poniżej)

• Dodaj plik PF do portu podstawowego miniportu. Port jest reprezentowany przez usługę BDF.

• Nowo dodany plik PF zostanie zwrócony klientowi za pośrednictwem operacji zapytania NDIS.

• Identyfikator OID OID_KDNET_ADD_PF jest skojarzony ze strukturą NDIS_KDNET_ADD_PF.

• Program obsługi sterowników OID_KDNET_ADD_PF zwróci element ULONG zawierający dodany numer funkcji PF.

• To żądanie identyfikatora OID będzie mieć tylko jeden parametr wyjściowy: AddedFunctionNumber. AddedFunctionNumber wskazuje dodaną wartość numeru funkcji w miniportowej lokalizacji PCI (miniport BDF). Narzędzie kdnet.exe otrzyma tę wartość i skonfiguruje dbgsettings::busparams w celu wskazywania dodanego pliku PF.

Uwaga

Dodany plik PF może być używany wyłącznie przez KDNET, dlatego sterowniki karty sieciowej systemu Windows są sfałszowane w celu wyraźnego uruchomienia *NOT* na dodanym pf, więc ma to zastosowanie również w przypadku włączenia KDNET *NOT* w systemie i PF został dodany do portu.

3. Usuń PCI PF (OID: OID_KDNET_REMOVE_PF, zobacz definicję poniżej )

• Usuń pf z podanego portu. Port jest reprezentowany przez usługę BDF.

• Identyfikator OID OID_KDNET_REMOVE_PF jest skojarzony ze strukturą NDIS_KDNET_REMOVE_PF.

• Identyfikator OID OID_KDNET_REMOVE_PF ma wejściowy port BDF i zwraca wartość ULONG zawierającą usuniętą numer funkcji PF za pośrednictwem operacji metody NDIS.

• Ta funkcja powiedzie się tylko na plikach PFS, które zostały dodane za pomocą identyfikatora OID OID_KDNET_ADD_PF.

• To żądanie identyfikatora OID będzie mieć wejściowy port usługi BDF, z którego należy usunąć usługę BDF. Ta funkcja ma parametr Wyjściowy FunctionNumber. Dane wyjściowe FunctionNumber będą zawierać usuniętą wartość numeru funkcji.

4. Wykonaj zapytanie o informacje PCI PF (identyfikator OID: OID_KDNET_QUERY_PF_INFORMATION, zobacz definicję poniżej)

• Ten kod OID umożliwia wykonywanie zapytań dotyczących określonych danych PF na danym porcie. Port jest reprezentowany przez usługę BDF.

• Żądane informacje PF zostaną zwrócone klientowi za pośrednictwem operacji metody NDIS.

• Identyfikator OID OID_KDNET_QUERY_PF_INFORMATION jest skojarzony ze strukturą NDIS_KDNET_QUERY_PF_INFORMATION.

• Identyfikator OID OID_KDNET_QUERY_PF_INFORMATION ma wejściowy port usługi BDF i zwraca bufor zawierający następujące dane:

  • Adres MAC: adres sieciowy przypisanego nowego certyfikatu KDNET PF, jeśli istnieje.

  • Tag użycia: opisuje jednostkę będącą właścicielem portu PF. Zawiera wartość stałą opisaną przez wyliczenie NDIS_KDNET_PF_USAGE_TAG.

  • Maksymalna liczba plików PFS: zawiera ULONG z maksymalną liczbą plików PFs, które można dodać do danej usługi BDF.

  • Identyfikator urządzenia: zawiera identyfikator urządzenia skojarzony z danym portem usługi BDF. Jest to wymagane w przypadkach, w których karta sieciowa interfejsu sieciowego przypisuje nowy identyfikator urządzenia do nowego dodanego portu PF sieci KDNET.

• Ten identyfikator OID żąda informacji dotyczących dowolnego przekazanego portu usługi BDF (BDF jest parametrem wejściowym dla tej operacji), dlatego nie jest koniecznie powiązany z bieżącą usługą BDF, z której jest uruchomiony sterownik.

Identyfikatory OID NDIS dla sieci KDNET w systemie 2PF

plik Ntddndis.h definiuje identyfikatory operacyjnego.

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

plik Kdnetpf.h opisuje typ i struktury skojarzone z identyfikatorami 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)

Zobacz też

Konfigurowanie debugowania Kernel-Mode 2PF przy użyciu KDNET

identyfikatory operacyjnego sieci

nagłówka kdnetpf.h