Hibakeresési üzenetek olvasása és szűrése

A DbgPrintEx, a vDbgPrintEx, a vDbgPrintExWithPrefix és a KdPrintEx rutinok a megadott feltételek mellett üzenetet küldenek a kernel hibakeresőjének. Ez az eljárás lehetővé teszi az alacsony prioritású üzenetek szűrését.

Megjegyzés:

A Microsoft Windows Server 2003 és a Windows korábbi verzióiban a DbgPrint és a KdPrint rutinok feltétel nélkül küldenek üzeneteket a kernel hibakeresőjének. A Windows Vista és a Windows újabb verzióiban ezek a rutinok feltételesen küldenek üzeneteket, például DbgPrintEx és KdPrintEx. Bármelyik Windows-verziót is használja, a DbgPrintEx, a vDbgPrintEx, a vDbgPrintExWithPrefix és a KdPrintEx verziót kell használnia, mivel ezek a rutinok lehetővé teszik az üzenet elküldésének feltételeinek szabályozását.

Hibakeresési üzenetek szűrése

  1. A hibakeresőnek küldeni kívánt összes üzenethez használja a DbgPrintEx, a vDbgPrintEx, a vDbgPrintExWithPrefix vagy a KdPrintEx elemet az illesztőprogram kódjában. Adja át a megfelelő összetevőnevet a ComponentId paraméternek, és adjon át egy értéket a Level paraméternek, amely az üzenet súlyosságát vagy jellegét tükrözi. Maga az üzenet a Formátum és az argumentum paramétereknek lesz átadva ugyanazzal a szintaxissal, mint a printf.

  2. Adja meg a megfelelő összetevőszűrő maszk értékét. Minden összetevő más maszkot tartalmaz. A maszk értéke azt jelzi, hogy az összetevő üzenetei közül melyik jelenik meg. Az összetevőszűrő maszkot a beállításjegyzékben beállításszerkesztővel vagy a memóriában egy kernel-hibakereső használatával állíthatja be.

  3. Csatoljon egy kernel-hibakeresőt a számítógéphez. Minden alkalommal, amikor az illesztőprogram üzenetet ad át a DbgPrintEx, a vDbgPrintEx, a vDbgPrintExWithPrefix vagy a KdPrintEx számára, a ComponentId és a Level értékeket összehasonlítja a megfelelő összetevőszűrő maszk értékével. Ha ezek az értékek megfelelnek bizonyos feltételeknek, a rendszer elküldi az üzenetet a kernel-hibakeresőnek, és megjelenik. Ellenkező esetben a rendszer nem küld üzenetet.

Megjegyzés:

Ezen a lapon a DbgPrintExre mutató összes hivatkozás egyformán érvényes a KdPrintEx, a vDbgPrintEx és a vDbgPrintExWithPrefix fájlra.

Az összetevő nevének azonosítása

Minden összetevő külön szűrőmaszkot tartalmaz. Ez lehetővé teszi, hogy a hibakereső külön konfigurálja az egyes összetevők szűrőjét.

Az egyes összetevőkre a környezettől függően különböző módokon hivatkozunk. A DbgPrintExComponentId paraméterében az összetevő neve "DPFLTR_" előtaggal és "_ID" utótaggal van ellátva. A beállításjegyzékben az összetevőszűrő maszk neve megegyezik az összetevő nevével. A hibakeresőben az összetevőszűrő maszk előtagja "Kd_" és utótagja "_Mask".

A Microsoft Windows Driver Kit (WDK) fejlécének dpfilter.h fájljában (DPFLTR_XXXX_ID formátumban) megtalálható az összes összetevőnév teljes listája. A legtöbb összetevőnév a Windows és a Microsoft által írt illesztőprogramok számára van fenntartva.

A független hardvergyártók számára hat összetevőnév van fenntartva. Az illesztőprogram kimenetének a Windows-összetevők kimenetével való keveredésének elkerülése érdekében használja az alábbi összetevők egyikét:

Összetevő neve Illesztőprogram típusa
IHVVIDEO Videoillesztő
IHVAUDIO Hangvezérlő
IHVNETWORK Hálózati illesztőprogram
IHVSTREAMING Kernel streamelő illesztőprogramja
IHVBUS Buszvezető
IHVDRIVER Bármilyen más típusú illesztőprogram

Ha például egy videoillesztőt ír, a DPFLTR_IHVVIDEO_ID-et használná mint a ComponentId paramétert a DbgPrintEx-ben, az IHVVIDEO értéknevet használná a beállításjegyzékben, és a hibakeresőben a Kd_IHVVIDEO_Mask-ra hivatkozna.

A DbgPrint és a KdPrint által küldött összes üzenet az ALAPÉRTELMEZETT összetevőhöz van társítva.

A megfelelő szint kiválasztása

A DbgPrintEx rutin Level paramétere DWORD típusú. A fontossági bit mező meghatározására szolgál. A Szint paraméter és a bitmező közötti kapcsolat a Szint méretétől függ:

  • Ha a szint 0 és 31 közötti számmal egyenlő, akkor a rendszer biteltolódásként értelmezi. A fontossági bitmező értéke 1 <<Level. A Szint értékének 0 és 31 közötti kiválasztása egy bitmezőt eredményez pontosan egy bitkészlettel. Ha a szint 0, a bitmező egyenértékű a 0x00000001; ha a szint 31, akkor a bitmező egyenértékű a 0x80000000.

  • Ha a Szint 32 és 0xFFFFFFFF közötti szám, akkor a fontossági bit mezője maga a Szint értékre van állítva.

Így ha a bitmezőt 0x00004000 szeretné beállítani, akkor a Szint 0x00004000 vagy egyszerűen 14 értékként is megadható. Vegye figyelembe, hogy ebben a rendszerben bizonyos bitmező-értékek nem fordulhatnak elő: beleértve a teljes egészében nulla bitmezőt is.

Az alábbi állandók hasznosak lehetnek a Szint értékének beállításához. Ezek meghatározása a Microsoft Windows Driver Kit (WDK) fejléc dpfilter.h és a Windows SDK fejléc ntrtl.h:

#define   DPFLTR_ERROR_LEVEL     0
#define   DPFLTR_WARNING_LEVEL   1
#define   DPFLTR_TRACE_LEVEL     2
#define   DPFLTR_INFO_LEVEL      3
#define   DPFLTR_MASK   0x80000000

A Level paraméter használatának egyik egyszerű módja, ha mindig a 0 és 31 közötti értékeket használja – a 0, 1, 2, 3 bitet használva a DPFLTR_XXXX_LEVEL által megadott jelentéssel, a többi bittel pedig azt jelenti, amit választ.

Egy másik egyszerű módja a Level paraméter használatának az, ha mindig explicit bitmezőket alkalmazunk. Ha ezt a metódust választja, és össze akarja adni az értéket a DPFLTR_MASK-kal a bitmezőben, ez garantálja, hogy véletlenül ne használjon 32-nél kisebb értéket.

Annak érdekében, hogy az illesztőprogram kompatibilis legyen a Windows üzenetszintjeivel, csak akkor állítsa be a fontos bit mezőjének legalacsonyabb bitjét (0x1), ha súlyos hiba történik. Ha 32-nél kisebb szintértékeket használ, ez a DPFLTR_ERROR_LEVEL-nek felel meg. Ha ez a bit be van állítva, az üzenet bármikor meg fog jelenni, amikor valaki kernel-hibakeresőt csatol egy olyan számítógéphez, amelyen az illesztőprogram fut.

A figyelmeztetési, nyomkövetési és információs szinteket a megfelelő helyzetekben kell használni. A többi bit szabadon használható bármilyen hasznos célra. Ez lehetővé teszi, hogy számos különféle üzenettípussal rendelkezzen, amelyek szelektíven láthatók vagy elrejthetők.

Az összes üzenet, amelyet a DbgPrint és KdPrint küld, ugyanúgy viselkedik, mint a DbgPrintEx és KdPrintEx üzenetek, amelyeknél a Level megegyezik a DPFLTR_INFO_LEVEL szinttel. Más szóval ezek az üzenetek a fontossági bitmező harmadik bitjével rendelkeznek.

Az Összetevőszűrő maszk beállítása

Az összetevőszűrő maszk beállításának két módja van:

  • Az összetevőszűrő maszk a beállításkulcs HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Debug Print Filterérhető el. Egy beállításszerkesztő segítségével hozzon létre vagy nyisson meg egy kulcsot. Ebben a kulcsban hozzon létre egy értéket a kívánt összetevő nevével nagybetűvel. Állítsa be az összetevőszűrő maszkként használni kívánt DWORD értékkel megegyező értéket.

  • Ha egy kernel-hibakereső aktív, az összetevőszűrő maszkjának értékét úgy érheti el, hogy elhalasztja a Kd_XXXX_Mask szimbólumban tárolt címet, ahol a XXXX az összetevő kívánt neve. A maszk értékét megjelenítheti WinDbg-ben vagy KD-ben a dd (DWORD megjelenítése) paranccsal, vagy beírhat egy új összetevőszűrő maszkot az ed (Enter DWORD) paranccsal. Ha fennáll a szimbólum kétértelműségének veszélye, ezt a szimbólumot ntként kell megadnia! Kd_XXXX_Mask.

A beállításjegyzékben tárolt szűrőmaszkok a rendszerindítás során lépnek érvénybe. A hibakereső által létrehozott szűrőmaszkok azonnal érvénybe lépnek, és a Windows újraindításáig megmaradnak. A beállításjegyzékben beállított értékeket felül tudja bírálni a hibakereső, de az összetevőszűrő maszk visszaáll a beállításjegyzékben megadott értékre, ha a rendszer újraindul.

Létezik egy WIN2000 nevű, rendszerszintű maszk is. Ez alapértelmezés szerint megegyezik a 0x1, de a beállításjegyzéken vagy a hibakeresőn keresztül is módosítható, mint minden más összetevő. A szűrés végrehajtásakor az egyes összetevőszűrő maszkok elsőként az WIN2000 maszkkal együtt jelennek meg. Ez különösen azt jelenti, hogy azon összetevők, amelyek maszkjait soha nem adták meg, alapértelmezetten az értékük 0x1.

Az üzenet megjelenítésének feltételei

Amikor a DbgPrintEx kernel módú kódban van meghívva, a Windows összehasonlítja a Level által megadott üzenet-fontossági bitmezőt a ComponentId által megadott összetevő szűrőmaszkjával.

Megjegyzés:

Ne feledje, hogy ha a Szint paraméter 0 és 31 között van, a fontos bitmező értéke 1 <<szint. Ha azonban a Szint paraméter 32 vagy magasabb, a fontos bitmező egyszerűen egyenlő a Level paraméterével.

A Windows egy AND műveletet hajt végre a fontos bitmezőn és az összetevőszűrő maszkon. Ha az eredmény nem nulla, küldi az üzenetet a hibakeresőnek.

Példa hibakeresési szűrőre

Tegyük fel, hogy az utolsó rendszerindítás előtt a következő értékeket hozta létre a Hibakeresési szűrőkulcsban :

  • IHVVIDEO, értéke DWORD 0x2

  • IHVBUS, egyenlő a DWORD 0x7FF

Most a következő parancsokat adja ki a kernel hibakeresőjében:

kd> ed Kd_IHVVIDEO_Mask 0x8 
kd> ed Kd_IHVAUDIO_Mask 0x7

Ezen a ponton az IHVVIDEO összetevő 0x8 szűrőmaszkot, az IHVAUDIO összetevő 0x7 szűrőmaszkot, az IHVBUS összetevő pedig 0x7FF szűrőmaszkot tartalmaz.

Mivel azonban ezek a maszkok automatikusan OR-ral kombinálva vannak a WIN2000 rendszerszintű maszkkal (amely általában szokott lenni egyenlő 0x1-el), az IHVVIDEO maszk gyakorlatilag egyenlő 0x9-cel. Azoknak az összetevőknek, amelyek szűrőmaszkjai egyáltalán nem lettek beállítva (például IHVSTREAMING vagy DEFAULT), 0x1 szűrőmaszkot fognak használni.

Tegyük fel, hogy a következő függvényhívások különböző illesztőprogramokban fordulnak elő:

DbgPrintEx( DPFLTR_IHVVIDEO_ID,  DPFLTR_INFO_LEVEL,   "First message.\n");
DbgPrintEx( DPFLTR_IHVAUDIO_ID,  7,                   "Second message.\n");
DbgPrintEx( DPFLTR_IHVBUS_ID,    DPFLTR_MASK | 0x10,  "Third message.\n");
DbgPrint( "Fourth message.\n");

Az első üzenet Level paramétere DPFLTR_INFO_LEVEL, ami 3. Mivel ez kisebb, mint 32, a program biteltolásként kezeli, ami egy 0x8 értékű fontossági bitmezőt eredményez. Ez az érték ezután egy logikai ÉS művelethez (AND) van társítva a hatékony IHVVIDEO összetevő 0x9 szűrőmaszkjával, így nullától különböző eredményt ad. Az első üzenet tehát a hibakeresőnek lesz továbbítva.

A második üzenet level paramétere 7. Ismét, ezt a program biteltolásként kezeli, így egy jelentőségi bitsor lesz 0x80 értékkel. Ezután az IHVAUDIO összetevőszűrőt és a 0x7-es maszkot ÉS művelettel kombinálva nullát eredményez. Így a második üzenet nem lesz továbbítva.

A harmadik üzenet Level paramétere DPFLTR_MASK | 0x10. Ez nagyobb, mint 31, ezért a fontos bit mező értéke megegyezik a Szint értékével – vagyis 0x80000010. Ezt követően AND művelettel kombinálják az 0x7FF IHVBUS-összetevő szűrőmaszkkal, ami nem nulla eredményt ad. A harmadik üzenet tehát a hibakeresőnek lesz továbbítva.

A negyedik üzenet a DbgPrintEx helyett a DbgPrintnek lett átadva. A Windows Server 2003-ban és a Windows korábbi verzióiban a rendszer mindig továbbítja a rutinnak átadott üzeneteket. A Windows Vista és a Windows újabb verzióiban a rutinnak átadott üzenetek mindig alapértelmezett szűrőt kapnak. A fontossági bit mező értéke 1 << DPFLTR_INFO_LEVEL, ami 0x00000008. Ennek a rutinnak az összetevője az alapértelmezett. Mivel nem állította be az ALAPÉRTELMEZETT összetevőszűrő maszkot, a maszk értéke 0x1. Ha ezt a fontossági bit mezővel együtt anD-ként adja meg, az eredmény nulla. Így a negyedik üzenet nem lesz továbbítva.

DbgPrint puffer és a hibakereső

Amikor a DbgPrint, a DbgPrintEx, a vDbgPrintEx, a vDbgPrintExWithPrefix, a KdPrint vagy a KdPrintEx rutin üzenetet küld a hibakeresőnek, a rendszer elküldi a formázott sztringet a DbgPrint pufferbe. A puffer tartalma azonnal megjelenik a Hibakereső parancsablakban, kivéve, ha letiltotta ezt a megjelenítést a GFlags Buffer DbgPrint Output beállításával.

A helyi kernel hibakeresése során, és bármikor, amikor ez a megjelenítés le lett tiltva, a DbgPrint puffer tartalma csak a !dbgprint bővítmény parancs használatával tekinthető meg.

A DbgPrint, a DbgPrintEx, a vDbgPrintEx, a vDbgPrintExWithPrefix, a KdPrint vagy a KdPrintEx egyetlen hívása csak 512 bájtnyi információt továbbít. Az 512 bájtnál hosszabb kimenet elveszik. Maga a DbgPrint-puffer legfeljebb 4 KB adatot tárolhat egy ingyenes Windows-builden, és legfeljebb 32 KB adatot egy ellenőrzött Windows-builden. A Windows Server 2003 és újabb verzióiban a KDbgCtrl eszközzel módosíthatja a DbgPrint puffer méretét. Ez az eszköz a Windows hibakeresési eszközeinek része.

Megjegyzés:

Az ellenőrzött buildek a Windows régebbi verzióiban voltak elérhetők, a Windows 10 1803-es verziója előtt. A Windows későbbi verzióiban az illesztőprogram kódjának ellenőrzéséhez használjon olyan eszközöket, mint az Illesztőprogram-ellenőrző és a GFlags.

Ha egy üzenet ki van szűrve a ComponentId és a Level értékek miatt, a rendszer nem továbbítja azt a hibakeresési kapcsolaton keresztül. Ezért ezt az üzenetet nem lehet megjeleníteni a hibakeresőben.

  • Last updated on