Dukungan Debugger 2PF KDNET

Topik ini menjelaskan cara mengaktifkan driver NDIS miniport Anda untuk dukungan debugger 2PF untuk memungkinkan peningkatan performa untuk adaptor kecepatan tinggi, sering digunakan di pusat data. Fitur ini tersedia di Windows 11 dan yang lebih baru.

Saat mengaktifkan debugging kernel pada NIC, dukungan debugging kernel mengambil alih kendali perangkat fisik untuk menyediakan debugging kernel dan koneksi jaringan pada sistem. Ini berfungsi dengan baik pada NIC bandwidth rendah konsumen (1–10 Gbps). Namun, pada perangkat throughput tinggi yang mendukung 10–40+ Gbps, modul ekstensibilitas debugging kernel tidak dapat mengikuti lalu lintas dari tumpukan jaringan Windows. Akibatnya, performa sistem secara keseluruhan terdegradasi.

Menggunakan fitur PCI multiple Physical Function (PF) untuk KDNET memungkinkan debugging diaktifkan dengan dampak performa yang hampir tidak ada.

Fungsi Fisik (PF) adalah fungsi PCI Express (PCIe) dari adaptor jaringan yang mendukung antarmuka virtualisasi I/O root tunggal (SR-IOV). PF mencakup Kemampuan Ekstensi SR-IOV dalam ruang Konfigurasi PCIe. Kemampuan ini digunakan untuk mengonfigurasi dan mengelola fungsionalitas SR-IOV adaptor jaringan, seperti mengaktifkan virtualisasi dan mengekspos Fungsi Virtual PCIe (VF).

PF mendukung struktur SR-IOV Extended Capability di ruang konfigurasi PCIe-nya. Struktur ini didefinisikan dalam spesifikasi Virtualisasi Akar Tunggal I/O dan Berbagi 1.1 PCI-SIG.

Transportasi debugger memanfaatkan beberapa atau driver Miniport berkemampuan 2PF. Untuk memungkinkan penelusuran kesalahan sistem server berkecepatan tinggi, disarankan agar vendor NIC mengaktifkan 2PF di semua NIC yang mendukung beberapa PF di firmware kartu jaringan.

Untuk informasi tentang mengonfigurasi dukungan 2PF untuk menguji koneksi, lihat Menyiapkan 2PF Kernel-Mode Debugging menggunakan KDNET.

Beberapa gambaran umum arsitektur PF KDNET

• Fungsionalitas Multiple PF (2PF) adalah menambahkan/menetapkan PF baru ke port jaringan PCI asli (misalnya, Bus.dev.fun0.0).

• PF baru yang ditambahkan (misalnya, bus.dev.fun0.1) hanya digunakan oleh KDNET untuk merutekan paket Debugger ke/dari target.

• Driver NIC kotak masuk Windows menggunakan PF asli untuk merutekan paket jaringan Windows (TCP/IP).

• Menggunakan pendekatan ini kedua pengendali dapat bekerja secara paralel tanpa mengganggu pekerjaan satu sama lain.

• Kedua driver berjalan di atas ruang konfigurasi PCI yang dipartisi

  • Driver Windows Inbox kehabisan port jaringan asli pada bus.dev. fun0.0

  • KDNET-KDNET-Ext. modul kehabisan PF yang ditambahkan pada bus.dev. fun0.1, Cara ini memastikan bahwa driver NIC kotak masuk Windows tidak terpengaruh dengan berbagi NIC dengan KDNET.

• Alat mode pengguna kdnet.exe mengonfigurasi fitur 2PF menggunakan driver kotak masuk Windows dengan menambahkan kode IOCTL tertentu untuk menambahkan/menghapus KDNET PF.

Persyaratan desain untuk beberapa PF

1. Fitur KDNET 2PF perlu berfungsi untuk semua skenario KD saat ini apakah itu OS pra-NT (misalnya, Boot Manager, pemuat OS, WinResume, Hyper-V, SK, dll.), NT OS, atau Windows Desktop.

2. Reboot sistem diperlukan jika menambahkan PF baru untuk perangkat mengubah konfigurasi BCD untuk pengaturan penelusuran kesalahan. Persyaratan ini berarti bahwa konfigurasi untuk PF tambahan harus persisten di seluruh boot.

3. Gunakan KDNET 2PF hanya untuk penelusuran kesalahan. Ini memastikan bahwa tidak ada driver Windows atau UEFI Ethernet yang mengakses lokasi PCI 2PF ketika debugger memiliki perangkat. Lokasi 2PF dikonfigurasi dengan menggunakan dbgsettings::busparams.

4. Driver Windows atau UEFI Ethernet tidak dapat kehabisan KDNET 2PF yang ditambahkan bahkan ketika KDNET tidak diaktifkan dalam sistem.

5. Fitur 2PF harus mendukung mekanisme dinamis untuk menambahkan/mengaktifkan dan menghapus/menonaktifkan fungsionalitas pada NIC saat ini.

6. Driver Windows Miniport mengimplementasikan fitur 2PF melalui layanan OID NDIS berikut.

Nama OID	Deskripsi
OID_KDNET_ENUMERATE_PFS	Mendaftar PF pada bus.dev.fun (BDF) saat ini, tempat driver miniport berjalan.
OID_KDNET_ADD_PF	Menambahkan PF ke BDF saat ini, tempat driver miniport berjalan.
OID_KDNET_REMOVE_PF	Menghapus PF yang ditambahkan dari BDF yang diberikan.
OID_KDNET_QUERY_PF_INFORMATION	Mengkueri data informasi PF dari yang diteruskan di BDF.

OID dan strukturnya didefinisikan dalam file ntddndis.h dan kdnetpf.h yang dirilis dengan WDK publik.

Lihat detail berikut tentang parameter Input/Output untuk setiap OID dan informasi yang disediakan dalam file header kdnetpf.h.

7. Konfigurasikan KDNET dengan menggunakan fitur KDNET 2PF pada NIC yang mendukung beberapa PDF. Pastikan bahwa NIC memenuhi semua persyaratan yang dijelaskan di bagian ini untuk mengaktifkan fungsionalitas 2PF.

Antarmuka PF Ganda KDNET untuk Driver NIC Windows

Untuk mendukung Antarmuka Beberapa PF KDNET, driver Miniport perlu menerapkan penanganan empat OID NDIS berikut.

• OID_KDNET_ENUMERATE_PFS

• OID_KDNET_ADD_PF

• OID_KDNET_REMOVE_PF

• OID_KDNET_QUERY_PF_INFORMATION

OID dan struktur ini diisi dalam file ntddndis.h dan kdnetpf.h dalam rilis WDK publik pada jalur ini:

<WDK root directory>\ddk\inc\ndis

File-file ini juga tersedia di Windows SDK, dan dapat ditemukan di direktori ini.

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

Alat klien (kdnet.exe) menggunakan IOCTL NDIS privat untuk merutekan OID NDIS KDNET 2PF ke driver miniport.

Fitur Multiple PF OID NDIS

Fitur Multiple PF dioperasikan dengan menggunakan keempat OID NDIS ini.

1. Hitung PDF pada port utama miniport BDF menggunakan OID: OID_KDNET_ENUMERATE_PFS, lihat definisi berikut.

• OID_KDNET_ENUMERATE_PFS mengembalikan daftar semua BDF yang terkait dengan port utama yang diberikan dari tempat driver miniport berjalan. bus.dev.fun (BDF) mewakili port. Operasi ini mencantumkan PDF yang hanya terkait dengan bus.dev.fun (port BDF) tempat driver miniport berjalan. Setiap driver miniport dapat menentukan lokasi BDF-nya.

• Daftar PDF dikembalikan ke klien melalui operasi Kueri NDIS.

• OID OID_KDNET_ENUMERATE_PFS terkait dengan struktur NDIS_KDNET_ENUMERATE_PFS.

• Handler driver OID_KDNET_ENUMERATE_PFS mengembalikan buffer yang berisi daftar PDF dengan setiap elemen PF yang dijelaskan oleh jenis NDIS_KDNET_PF_ENUM_ELEMENT.

  Bidang PfNumber berisi Nomor Fungsi PF, (misalnya, bus.dev.menyenangkan)

  Bidang PfState berisi nilai status PF yang mungkin- setiap jenis elemen yang dijelaskan oleh enum NDIS_KDNET_PF_STATE.

  NDIS_KDNET_PF_STATE::NdisKdNetPfStatePrimary - Ini adalah PF utama dan biasanya hanya digunakan oleh driver miniport.

  NDIS_KDNET_PF_STATE::NdisKdnetPfStateEnabled - Ini adalah PF sekunder tambahan yang digunakan oleh KDNET.

  NDIS_KDNET_PF_STATE::NdisKdnetPfStateConfigured - Ini adalah PF tambahan, tetapi hanya ditambahkan/dikonfigurasi dan tidak digunakan.

• Jika ukuran buffer output daftar PF tidak cukup besar untuk mengalokasikan daftar PDF aktual, maka handler OID perlu mengembalikan E_NOT_SUFFICIENT_BUFFER nilai pengembalian kesalahan, bersama dengan ukuran buffer yang diperlukan, sehingga alat klien dapat mengalokasikan buffer ukuran yang diperlukan, dan kemudian klien dapat melakukan panggilan lain dengan ukuran buffer yang benar yang dialokasikan. Selain itu, bidang status permintaan OID (dijelaskan oleh NDIS_IOCTL_OID_REQUEST_INFO.status) harus diatur ke sama dengan NDIS_STATUS_BUFFER_TOO_SHORT.

2. Tambahkan PCI PF ke port utama BDF miniport (OID: OID_KDNET_ADD_PF, lihat definisi berikut)

• Tambahkan PF ke port utama miniport. bus.dev.fun (BDF) mewakili port.

• PF yang baru ditambahkan dikembalikan ke klien melalui operasi Kueri NDIS.

• OID OID_KDNET_ADD_PF dikaitkan dengan struktur NDIS_KDNET_ADD_PF.

• Handler driver OID_KDNET_ADD_PF mengembalikan ULONG yang berisi nomor fungsi PF yang ditambahkan .

• Permintaan OID ini hanya memiliki satu parameter Output: AddedFunctionNumber. AddedFunctionNumber menunjukkan nilai nomor Fungsi yang ditambahkan pada lokasi PCI miniport (BDF miniport). Utilitas kdnet.exe menerima nilai ini dan menyiapkan dbgsettings::busparams untuk menunjuk ke PF yang ditambahkan.

Nota

KDNET dapat menggunakan PF yang ditambahkan secara eksklusif. Driver Windows NIC dicurangi untuk secara tegas *NOT* berjalan pada PF yang ditambahkan. Ini juga berlaku ketika KDNET *NOT* diaktifkan pada sistem dan PF ditambahkan ke port.

3. Hapus PCI PF (OID: OID_KDNET_REMOVE_PF, lihat definisi berikut )

• Hapus PF dari port yang telah ditentukan. bus.dev.fun (BDF) mewakili port.

• OID OID_KDNET_REMOVE_PF terkait dengan struktur NDIS_KDNET_REMOVE_PF.

• OID OID_KDNET_REMOVE_PF memiliki port BDF input dan mengembalikan ULONG yang berisi dihapus nomor fungsi PF melalui operasi Metode NDIS.

• Fungsi ini hanya berhasil pada PDF yang ditambahkan menggunakan OID_KDNET_ADD_PF OID.

• Permintaan OID ini memiliki port BDF input dari mana perlu dihapus BDF. Fungsi ini memiliki parameter Output FunctionNumber. Output FunctionNumber berisi nilai angka Fungsi yang dihapus.

4. Mengkueri informasi PF PCI (OID: OID_KDNET_QUERY_PF_INFORMATION, lihat definisi berikut)

• Kode OID ini memungkinkan pengambilan data PF tertentu pada port yang ditentukan. bus.dev.fun (BDF) mewakili port.

• Informasi PF yang diminta dikembalikan ke klien melalui operasi Metode NDIS.

• OID OID_KDNET_QUERY_PF_INFORMATION dikaitkan dengan struktur NDIS_KDNET_QUERY_PF_INFORMATION.

• OID OID_KDNET_QUERY_PF_INFORMATION memiliki port BDF input dan mengembalikan buffer yang berisi data berikut:

  • Alamat MAC: Alamat jaringan PF KDNET baru yang ditetapkan jika ada.

  • Tag Penggunaan: Menjelaskan entitas yang memiliki port PF. Ini berisi nilai konstan yang dijelaskan oleh enum NDIS_KDNET_PF_USAGE_TAG.

  • Jumlah Maksimum PF: Berisi ULONG dengan jumlah maksimum PF yang dapat ditambahkan ke BDF yang diberikan.

  • ID Perangkat: Berisi ID perangkat yang terkait dengan port BDF yang diberikan. Ini diperlukan untuk kasus di mana NIC FW menetapkan ID perangkat baru ke port PF KDNET baru yang ditambahkan.

• OID ini meminta informasi untuk setiap yang diteruskan di port BDF (BDF adalah parameter input untuk operasi ini). Ini belum tentu terkait dengan BDF saat ini dari tempat driver berjalan.

OID NDIS untuk KDNET di 2PF

file Ntddndis.h mendefinisikan 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)

file Kdnetpf.h menjelaskan jenis dan struktur yang terkait dengan 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 (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)

Lihat juga

Menyiapkan 2PF Kernel-Mode Debugging menggunakan KDNET

OID Jaringan

header kdnetpf.h