Windows sürücüsüne WPP yazılım izlemesi ekleme

WPP yazılım izlemeyi bir izleme sağlayıcısında, örneğin bir çekirdek modu sürücüsü veya kullanıcı modu uygulaması içinde kullanmak için, sürücü kaynak dosyalarına kod eklemeniz (veya enstrüman etmeniz) ve sürücü projesini değiştirmeniz gerekir. Bu bölümde bu adımlar açıklanmaktadır.

Uyarı

Sürücünüze WPP izleme eklemenin en kolay yolu, Visual Studio'daki KMDF veya UMDF sürücü şablonlarından birini kullanmaktır. Şablonları kullanıyorsanız, eklemeniz gereken kodun çoğu sizin için zaten yapılmıştır. Visual Studio'da Dosya > Yeni > Proje'yi ve ardından Windows Sürücüsü (kullanıcı modu veya çekirdek modu) WDF projesini seçin. WPP makroları, projenin bir parçası olarak eklenen Trace.h üst bilgi dosyasında tanımlanır. Şablonlardan birini kullanıyorsanız 5. Adıma atlayabilirsiniz.

1. Adım: Denetim GUID'sini ve izleme bayraklarını tanımlama

Her izleme sağlayıcısı (sürücü veya kullanıcı modu uygulaması gibi) benzersiz olarak tanımlanmalıdır. Bunu yapmak için denetim GUID'sini, tanımlayıcıyı ve izleme bayraklarını tanımlayan WPP_CONTROL_GUIDS makroyu eklersiniz. Bu, ne zaman ve ne izlemek istediğinizi belirleyip denetleyebilmeniz için yapılır. Her sürücüde genellikle ayrı bir denetim GUID'si olsa da, bir sürücünün birden çok denetim GUID'si olabilir veya birden çok sürücü bir denetim GUID'sini paylaşabilir.

Kolaylık olması için WPP_CONTROL_GUIDS makrosu genellikle ortak bir üst bilgi dosyasında tanımlanır. İzleme amacıyla kullanmayı planladığınız herhangi bir kaynak dosyaya başlık dosyası (#include) eklenmelidir.

Sürücünüze WPP_CONTROL_GUIDS makro eklemek için:

  1. Visual Studio projenize WPP izleme makrolarını tanımlamak için kullanabileceğiniz yeni bir C++ üst bilgi dosyası ekleyin. Örneğin, Çözüm Gezgini'nde sürücüyü seçip basılı tutun (veya sağ tıklayın) ve Yeni Öğe Ekle'yi >seçin. Dosyayı kaydedin (örneğin Trace.h olarak).

  2. İzleme sağlayıcısı için kolay ad belirtmek, bir denetim GUID'i tanımlamak ve belirli izleme iletilerini nitelerken kullanabileceğiniz izleme bayraklarını tanımlamak için bir WPP_CONTROL_GUIDS makro ekleyin.

    WPP_CONTROL_GUIDS makrosunun söz dizimi aşağıdaki gibidir:

    WPP_CONTROL_GUIDS söz dizimi

    #define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID(GUIDFriendlyName, (ControlGUID),  \
        WPP_DEFINE_BIT(NameOfTraceFlag1)  \
        WPP_DEFINE_BIT(NameOfTraceFlag2)  \
        .............................   \
        .............................   \
        WPP_DEFINE_BIT(NameOfTraceFlag31) \
        )

    Örneğin, aşağıdaki kod GUIDFriendlyName olarak myDriverTraceGuid kullanır. ControlGUID'nin 32 basamaklı onaltılık GUID'nin standart biçiminden biraz farklı bir biçimi olduğuna dikkat edin. ControlGUID'de beş alan vardır, ancak bunlar virgülle ayrılır ve normal kısa çizgiler ve küme ayraçları yerine parantez içine alınır. Örneğin, {84bdb2e9-829e-41b3,b891,02f454bc2bd7) yerine {84bdb2e9-829e-41b3-b891-02f454bc2bd7} değerini belirtirsiniz.

    WPP_CONTROL_GUIDS deyimi örneği

    #define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(                                           \
        myDriverTraceGuid, (84bdb2e9,829e,41b3,b891,02f454bc2bd7), \
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        )

    Uyarı

    Bu kod parçacığını bir üst bilgi dosyasına kopyalayabilirsiniz. Denetim GUID'sini ve kolay anlaşılır ismi değiştirdiğinizden emin olun. denetim GUID'sini oluşturmak için GUIDgen.exe kullanabilirsiniz. Guidgen.exe, Visual Studio'ya dahildir (Araçlar > GUID Oluştur). Visual Studio Komut istemi penceresinden kullanılabilen Uuidgen.exe aracını da kullanabilirsiniz (daha fazla bilgi için uuidgen.exe /? yazın).

  3. İzleme sağlayıcınız için İzleme Bayraklarını tanımlayın.

    WPP_CONTROL_GUIDS makrosunun WPP_DEFINE_BIT öğeleri, izleme sağlayıcısı için izleme bayraklarını tanımlar. Genellikle, bayraklar giderek daha ayrıntılı raporlama düzeylerini temsil eder, ancak izleme iletileri oluşturma koşulları olarak istediğiniz şekilde bayrakları kullanabilirsiniz. WPP_CONTROL_GUIDS örnekte, WPP_DEFINE_BIT dört izleme bayrağı tanımlar (MYDRIVER_ALL_INFO, TRACE_DRIVER, TRACE_DEVICE ve TRACE_QUEUE).

    En fazla 31 izleme bayrağı tanımlayabilirsiniz. WPP, öğelere göründükleri sırayla bit değerleri atar; örneğin, bit 0 (0x1), bit 1 (0x2), bit 2 (0x4), bit 3 (0x8) vb. Kaynak kodunuza izleme iletisi işlevleri eklediğinizde izleme bayraklarını kullanırsınız (5. Adım: Uygun noktalarda izleme iletileri oluşturmak için sürücü kodunu yapılandırma bölümünde açıklandığı gibi).

    Uyarı

    İzleme bayraklarını kullanarak belirli bileşenlerin (örneğin, belirli G/Ç istekleri veya cihaz ya da sürücü nesnelerinin etkinlikleri) ne zaman izleyebileceğinizi denetleyebilirsiniz. İzleme mesajı ifadenize izleme bayrağı eklersiniz (örneğin, DoTraceMessage (TRACE_DRIVER, "Hello World!\n")). tracelog gibi bir izleme denetleyicisiyle izleme oturumu oluşturduğunuzda, bu oturumdaki izleme sağlayıcısı için kullanılacak -flag seçeneğini belirtirsiniz; bu durumda bayrak, TRACE_DRIVER bayrağına karşılık gelen bit 1 (0x1) olur. İzleme oturumunu başlattığınızda, izleme bayrağını belirten tüm izleme iletileri günlüğe yazılır.

2. Adım: Kullanmak istediğiniz izleme iletisi işlevlerini seçin ve bu işlevler için WPP makrolarını tanımlayın

Hata ayıklama yazdırma işlevi gibi, izleme iletisi işlevi de izleme iletileri yazmak için kodunuza eklediğiniz bir işlevdir (veya makrodur).

İzleme iletisi işlevi seçme

  • Varsayılan izleme iletisi işlevi DoTraceMessage makrosdur. Varsayılan işlevi kullanırsanız, sağlayıcınız için İzleme Bayrağı değerlerini kullanarak iletilerin ne zaman oluşturulabileceğini denetleyebilirsiniz. İzleme Bayrakları değerleri, 1. Adımda denetim GUID'sini oluştururken tanımladığınız bayraklardır. DoTraceMessage kullanıyorsanız, varsayılan WPP makroları sizin için zaten tanımlanmıştır (WPP_LEVEL_ENABLED ve WPP_LEVEL_LOGGER), böylece bu adımın geri kalanını atlayabilir ve 5. Adım'a gidebilirsiniz.

  • KMDF veya UMDF şablonlarından birini kullanıyorsanız , TraceEvents işlevi ve gerekli WPP makroları bu işlevi etkinleştirmek için zaten tanımlanmıştır, böylece 5. Adıma geçebilirsiniz.

  • Kendi izleme iletisi işlevinizi oluşturuyorsanız veya var olan hata ayıklama yazdırma işlevini dönüştürüyorsanız, bu adımın geri kalanıyla devam edin.

İzleme iletisi işlevi oluşturma veya özelleştirme

  1. Özel izleme iletisi işlevleri kullanıyorsanız veya izleme iletileri oluşturmak için hata ayıklama yazdırma işlevlerini (örneğin , KdPrint) dönüştürmek istiyorsanız, izleme sağlayıcınızda izleme iletisi işlevlerini tanımlayan ve etkinleştiren WPP makroları tanımlamanız gerekir. Bu makroları projenize eklediğiniz Trace.h üst bilgi dosyasına yerleştirin.

  2. İzleme işlevini etkinleştirmek için WPP makrolarını tanımlayın.

    Kullandığınız her izleme iletisi işlevinin karşılık gelen bir makro çifti olmalıdır. Bu makrolar izleme sağlayıcısını tanımlar ve iletileri oluşturan koşulları belirtir. Genellikle, varsayılan WPP_LEVEL_ENABLED ve WPP_LEVEL_LOGGER makroları açısından WPP_<condition>_LOGGER ve WPP_<condition>_ENABLED makro çiftini tanımlarsınız.

Süre Açıklama
WPP_CONDITIONS_LOGGER Sağlayıcıyla ilişkili izleme oturumunu bulmak için kullanılır ve oturum tanıtıcısını döndürür.
WPP_CONDITIONS_ENABLED Günlüğe kaydetmenin belirtilen koşulla etkinleştirilip etkinleştirilmediğini belirlemek için kullanılır.

Tanımladığınız WPP makroları için KOŞULLAR , izleme iletisi işlevinin desteklediği koşulları işlevin parametre listesinde alt çizgilerle ayrılmış olarak göründükleri sırayla temsil eder. Örneğin, DoTraceMessage varsayılan izleme iletisi işlevi koşul olarak yalnızca İzleme Bayrağı'nı destekler, bu nedenle makro adlarında yalnızca bir parametre vardır (WPP_LEVEL_ENABLED).

Uyarı

Ne yazık ki, varsayılan makroların (WPP_LEVEL_ENABLED ve WPP_LEVEL_LOGGER) adları İzleme Düzeyi parametresini gösteriyor gibi görünse de, aslında İzleme Bayrağı'na başvurur.

Özel izleme iletisi işlevi kullanıyorsanız, İzleme Düzeyi gibi ek niteleyiciler ayarlayabilirsiniz. İzleme Düzeyi Evntrace.h dosyasında tanımlanır ve izleme düzeyleri izleme iletilerini hata, uyarı ve bilgilendirme iletileri olarak sınıflandırmanın kullanışlı bir yolunu sağlar.

Örneğin, projenize eklediğiniz üst bilgi dosyasına aşağıdaki kod parçacığını ekleyebilirsiniz. Aşağıdaki kod, izleme iletileri oluşturma koşulları olarak hem İzleme Düzeyi hem de İzleme Bayrağı parametrelerini destekleyen bir izleme iletisi işlevi için özel WPP makrolarını tanımlar. WPP_LEVEL_FLAGS_ENABLED makrosu, belirtilen FLAGS değeri için günlük kaydı etkinleştirildiyse ve etkinleştirilen DÜZEY değeri izleme iletisi işlev çağrısında kullanılan düzey bağımsız değişkenine eşit veya ondan büyükse TRUE döndürür.

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
           WPP_LEVEL_LOGGER(flags)

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
           (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

Ardından, WPP yapılandırma bloğunda özel izleme işlevlerini belirtmeniz gerekir (begin_wpp yapılandırma ve end_wpp) Örneğin, Visual Studio'da UMDF veya KMDF Sürücüsü projeleri için şablonu kullanırsanız, şablon TraceEvents adlı özel bir izleme iletisi işlevi için WPP makrolarını tanımlar. TraceEvents makro işlevi, ileti oluşturma koşulları olarak İzleme Düzeyi ve İzleme Bayrağı'nı kullanır. trace.h üst bilgi dosyanızda WPP_LEVEL_FLAGS_ENABLED makro tanımladıysanız, aşağıdaki makro tanımını ekleyebilirsiniz.

//
// This comment block is scanned by the trace preprocessor to define the 
// TraceEvents function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

WPP yapılandırma bloğuna benzer bir FUNC bildirimi ekleyerek mevcut hata ayıklama yazdırma deyimlerini izleme iletileri deyimlerine de dönüştürebilirsiniz. Örneğin, aşağıdaki örnek var olan KdPrint deyimlerini dönüştürmek için kodu ekler. FUNC bildirimi ayrıca belirtilen izleme düzeyini kullanmak için KdPrint'i genel olarak tanımlar ve {LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER} bayrağını kullanır. Çıktıyı hata ayıklayıcıya göndermek yerine, hata ayıklama yazdırma deyimleri izleme günlüğüne gönderilir.

//
// This comment block is scanned by the trace preprocessor to define the
// TraceEvents function and conversion for KdPrint. Note the double parentheses for the KdPrint message, for compatibility with the KdPrint function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// FUNC KdPrint{LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}((MSG, ...));
// end_wpp
//

Uyarı

KdPrintEx'i bir izleme iletisi işlevine dönüştürmek istiyorsanız, birkaç ek adım uygulamanız gerekir. KdPrint ile karşılaştırıldığında, KdPrintEx işlevi iki ek bağımsız değişken alır. KdPrintEx işlevini dönüştürmek için ComponentID için bir WPP_DEFINE_BIT tanımlamanız ve özel WPP_<condition>_LOGGER ve WPP_<condition>_ENABLED makroları tanımlamanız gerekir. KdPrintEx için ikinci parametre, düzeyinin İzleme Düzeyi değerlerine benzer olduğunu belirtir, bu nedenle bunları yeniden tanımlamanız gerekmez.


#define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(\
    myDriverTraceGuid, (11C3AAE4, 0D88, 41b3, 43BD, AC38BF747E19), \    /* change GUID for your provider */
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        WPP_DEFINE_BIT(DPFLTR_IHVDRIVER_ID)      /* bit  4 = 0x00000010 */\         /* Added for the ComponentID param of KdPrintEx */
    )

#define WPP_Flags_LEVEL_LOGGER(Flags, level)                                  \
    WPP_LEVEL_LOGGER(Flags)

#define WPP_Flags_LEVEL_ENABLED(Flags, level)                                 \
    (WPP_LEVEL_ENABLED(Flags) && \
    WPP_CONTROL(WPP_BIT_ ## Flags).Level >= level)



//
// This comment block is scanned by the trace preprocessor to convert the KdPrintEx function.
// Note the double parentheses for the KdPrint message, for compatiblility with the KdPrintEx function.
//
// begin_wpp config
// FUNC KdPrintEx((Flags, LEVEL, MSG, ...));   
// end_wpp
//

3. Adım: C veya C++ kaynak dosyalarınıza ilişkili izleme üst bilgisi dosyalarını (.h ve .tmh) ekleyin

Sürücünüz için denetim GUID'sini ve izleme bayraklarını bir üst bilgi dosyasında (örneğin, trace.h) tanımladıysanız, wpp'yi başlatıp kaldıracağınız (4. Adım) veya izleme iletisi işlevlerini çağıracağınız kaynak dosyalara üst bilgi dosyasını eklemeniz gerekir.

Ayrıca, bir #include deyimini İzleme İletisi Üst Bilgi Dosyası (.tmh) için eklemeniz gerekir. Sürücüyü veya uygulamayı oluşturduğunuzda, WPP ön işlemcisi izleme iletisi işlevleri içeren her kaynak dosya için izleme iletisi üst bilgi dosyalarını (.tmh) oluşturur.

/* -- driver.c  - include the *.tmh file that is generated by WPP --*/

#include "trace.h"     /* file that defines WPP_CONFIG_GUIDS and trace flags */
#include "driver.tmh"  /* this file is auto-generated */

4. Adım: WPP'yi başlatmak ve temizlemek için uygun geri çağırma işlevlerine makro ekleme

Sürücü giriş noktasında WPP'yi başlatmak için

  • WPP_INIT_TRACING makrosunu bir çekirdek modu sürücüsünün veya UMDF 2.0 sürücüsünün DriverEntry yordamına veya kullanıcı modu sürücüsünün (UMDF 1.x) veya uygulamanın DLLMain yordamına ekleyin.

Sürücü çıkışında WPP kaynaklarını temizlemek için

  • WPP_CLEANUP makroyu çekirdek modu sürücüsünün veya UMDF 2.0 sürücüsünün sürücü kaldırma yordamına (örneğin, DriverContextCleanup veya DriverUnload) ekleyin.

    Kullanıcı modu sürücüsü (UMDF 1.x) veya uygulama için WPP_CLEANUP makrosunu DLLMain yordamına ekleyin.

    DriverEntry'nin başarısız olması durumunda WPP_CLEANUP makroyu DriverEntry yordamına da eklemeniz gerekir. Örneğin, DriverEntry başarısız olursa, sürücü kaldırma rutini çağrılmaz. Aşağıdaki örnekte WdfDriverCreate çağrısına bakın.

DriverEntry'de WPP_INIT_TRACING ve WPP_CLEANUP kullanan çekirdek modu sürücüsü örneği


NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    )
{  

          //  ... 

                //
    // Initialize WPP Tracing in DriverEntry
    //
    WPP_INIT_TRACING( DriverObject, RegistryPath );

                //  ...


 //
    // Create a framework driver object to represent our driver.
    //
    status = WdfDriverCreate(
        DriverObject,
        RegistryPath,
        &attributes, // Driver Object Attributes
        &config,          // Driver Config Info
        WDF_NO_HANDLE // hDriver
        );

    if (!NT_SUCCESS(status)) {

        TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
                "WdfDriverCreate failed with status 0x%x\n", status);
        //
        // Cleanup tracing here because DriverContextCleanup will not be called
        // as we have failed to create WDFDRIVER object itself.
        // Please note that if you return failure from DriverEntry after the
        // WDFDRIVER object is created successfully, you don't have to
        // call WPP cleanup because in those cases DriverContextCleanup
        // will be executed when the framework deletes the DriverObject.
        //
        WPP_CLEANUP(DriverObject);

    }

                return status;

}

DriverContextCleanup'ta WPP_CLEANUP kullanan çekirdek modu sürücüsü örneği



VOID
DriverContextCleanup(
       PDRIVER_OBJECT DriverObject
       )
{
    // ...

    // Clean up WPP resources on unload
    //
    WPP_CLEANUP(DriverObject);

   // ...

}

DriverEntry'de WPP_INIT_TRACING kullanan UMDF 2.0 sürücüsü örneği


/
// Driver specific #defines in trace header file (trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF2.0\\UMDF2_0Driver1 V1.0"


 // Initialize WPP Tracing in the DriverEntry routine
 //
    WPP_INIT_TRACING( MYDRIVER_TRACING_ID );

DLLMain'de WPP_INIT_TRACING ve WPP_CLEANUP makrolarının UMDF 1.0 sürücü kullanımı örneği

/
// Driver specific #defines in trace header file (for example, trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF1.X\\UMDF1_XDriver1"


//
// DLL Entry Point - UMDF 1.0 example in the source file where you implement the DLL exports.
// 

extern "C"
BOOL
WINAPI
DllMain(
    HINSTANCE hInstance,
    DWORD dwReason,
    LPVOID lpReserved
    )
{
    if (dwReason == DLL_PROCESS_ATTACH) {
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);              // Initialize WPP tracing

        g_hInstance = hInstance;
        DisableThreadLibraryCalls(hInstance);

    } else if (dwReason == DLL_PROCESS_DETACH) {
        WPP_CLEANUP();                                                                                                              // Deactivate and cleanup WPP tracing
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

5. Adım: Uygun noktalarda izleme iletileri oluşturmak için sürücü kodunu enstrümante etme

İzleme iletisi işlevi, izleme bayrakları ve düzeyler uygun şekilde tanımlanmışsa, seçtiğiniz herhangi bir izleme iletisi işlevini kullanabilirsiniz. Varsayılan izleme iletisi işlevi DoTraceMessage makrosdur. Günlük dosyasına ileti yazmak için bu makroyu kodunuza ekleyebilirsiniz. Aşağıdaki tabloda, önceden tanımlanmış izleme iletisi işlevlerinden bazıları ve izleme iletileri oluşturmak için kullanabileceğiniz hata ayıklama yazdırma işlevleri listelenmektedir.

Örnek izleme iletisi işlevleri Ne zaman kullanılır?
DoTraceMessage Bu, varsayılan izleme iletisi işlevidir. DoTraceMessage kullanmanın avantajı, işlevin sizin için zaten tanımlanmış olmasıdır. WPP_CONFIG_GUIDS makroda belirttiğiniz izleme bayraklarını kullanabilirsiniz. DoTraceMessage kullanmanın dezavantajı, işlevin yalnızca bir koşullu parametre, yani izleme bayrakları almasıdır. İzleme düzeylerini kullanmak istiyorsanız, yalnızca hata veya uyarı iletilerini günlüğe kaydetmek için DoDebugTrace makrolarını veya hem izleme bayraklarını hem de izleme düzeylerini kullanan TraceEvents'i kullanabilirsiniz.
TraceEvents Visual Studio'da WDF şablonlarını kullanarak bir sürücü oluşturursanız, bu varsayılan izleme iletisi işlevidir. TraceEvents kullanmanın avantajı, izleme iletisi işlevinin, izleme bayraklarının ve İzleme Düzeyi'nin sizin için zaten tanımlanmış olmasıdır. Ayrıca şablonlar, işlev girişi ve çıkışında günlük dosyasına ileti yazan araçlar da içerir.
KdPrint, KdPrintEx, DbgPrint, DbgPrintEx Hata ayıklama yazdırma işlevlerini kullanmanın avantajı, var olan hata ayıklama yazdırma deyimlerinizi değiştirmeniz gerekmemesidir. Hata ayıklayıcıda iletileri görüntülemekten bir dosyada izleme iletilerini kaydetmeye kolayca geçiş yapabilirsiniz. İzleme iletisi işlevini hata ayıklama yazdırma işlevlerinden birini içerecek şekilde özelleştirdiyseniz, daha fazla çalışma yapmanız gerekmez. Logman, Tracelog veya başka bir izleme denetleyicisiyle izleme oturumu oluşturduğunuzda, yalnızca sağlayıcınız için bayrakları ve düzeyleri belirtirsiniz. Belirttiğiniz koşulları karşılayan tüm hata ayıklama çıktıları günlüğe yazdırılır.

DoTraceMessage ifadelerini kullanma

  1. DoTraceMessage makroyu, yazdırma yordamında hata ayıklamak gibi kodunuza ekleyin. DoTraceMessage makro 3 parametre alır: izleme iletisi yazıldığında koşulu tanımlayan bayrak düzeyi (TraceFlagName), İleti dizesi ve isteğe bağlı değişken listesi.

    DoTraceMessage(TraceFlagName, Message, [VariableList... ])

    Örneğin, aşağıdaki DoTraceMessage deyimi, WPP_CONTROL_GUIDS'de tanımlanan TRACE_DRIVER bayrağı izleme oturumu için etkinleştirildiğinde DoTraceMessage deyimini içeren işlevin adını yazar.

         DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

    Örnekte, o anda yürütülen işlev (%FUNC!) için önceden tanımlanmış bir dize kullanılır. WPP tanımlı biçim belirtimi dizeleri hakkında daha fazla bilgi için bkz. WPP genişletilmiş biçim belirtimi dizeleri nelerdir?

  2. İzleme iletisini oluşturmak için Logman veya Tracelog kullanarak izleme sağlayıcınız için bir izleme oturumu oluşturun ve TRACE_DRIVER bayrağını (bit 1, 0x2) ayarlayan bir izleme bayrağı belirtin.

//
//  DoTraceMessage examples
// 

     ...

// writes the name of the function that contains the trace statement when the flag, TRACE_DRIVER (bit 1, 0x2), 
// as defined in WPP_CONTROL_GUIDS, is enabled for the trace session.

     DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

     ...

// writes the name of the function, the line number, and the error code 

      DoTraceMessage(
            TRACE_DRIVER,
            "[%s] Failed at %d (error code= %d)\n",
            __FUNCTION__,
            __LINE__,
            dwLastError);

TraceEvents deyimlerini kullanma

Visual Studio'da Windows sürücü şablonlarını kullanıyorsanız TraceEvents makro, Trace.h üst bilgi dosyasında sizin için tanımlanır.

  1. TraceEvents makroyu, yazdırma yordamında hata ayıklamak gibi kodunuza ekleyin. TraceEvents makro aşağıdaki parametreleri alır: izleme iletisi yazıldığında koşulu tanımlayan izleme düzeyi (Düzey) ve izleme bayrağı (Bayraklar), İleti dizesi ve isteğe bağlı değişken listesi.

    TraceEvents(Level, Flags, Message, [VariableList... ])

    Örneğin, aşağıdaki TraceEvents deyimi, İzleme Düzeyi ve İzleme Bayrağı parametrelerinde belirtilen koşullar karşılandığında TraceEvents deyimini içeren işlevin adını yazar. İzleme Düzeyi bir tamsayı değeridir; bu izleme oturumu için belirtilen İzleme Düzeyi'ndeki veya altındaki her şey izlenir. TRACE_LEVEL_INFORMATION Evntrace.h içinde tanımlanır ve 4 değerine sahiptir. TRACE_DRIVER bayrağı (bit 1, 0x2) WPP_CONTROL_GUIDS içinde belirlenmiştir. bu TRACE_DRIVER biti izleme oturumu için ayarlanmışsa ve İzleme Düzeyi 4 veya daha büyükse TraceEvents izleme iletisini yazar.

            TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

    Örnekte, o anda yürütülen işlev (%FUNC!) için önceden tanımlanmış bir dize kullanılır. WPP tanımlı biçim belirtimi dizeleri hakkında daha fazla bilgi için bkz. WPP genişletilmiş biçim belirtimi dizeleri nelerdir?

  2. İzleme iletisini oluşturmak için Logman veya Tracelog kullanarak izleme sağlayıcınız için bir izleme oturumu oluşturun. TRACE_LEVEL_INFORMATION (4) veya üzeri bir izleme düzeyi belirtin ve TRACE_DRIVER bitini (bit 1, 0x2) ayarlayan bir izleme düzeyi belirtin.

//
//  TraceEvents examples
// 


    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

//


    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                       "OSRUSBFX2 Driver Sample - Driver Framework Edition.\n");

    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                "Built %s %s\n", __DATE__, __TIME__);

6. Adım: WPP ön işlemcisini çalıştırmak ve çözümü oluşturmak için Visual Studio projesini değiştirme

WDK, Visual Studio ve MSBuild ortamını kullanarak ön işlemciyi çalıştırabilmeniz için WPP Ön İşlemcisi için destek sağlar.

WPP ön işlemcisini çalıştırmak için

  1. Çözüm Gezgini'nde sürücü projesini seçip basılı tutun (veya sağ tıklayın) ve Özellikler'i seçin.
  2. Proje özelliği sayfasında Yapılandırma Özellikleri'ni ve WPP İzleme'yi seçin.
  3. Genel'in altında WPP'yi Çalıştır seçeneğini Evet olarak ayarlayın.
  4. Komut Satırı'nın altında, izleme davranışını özelleştirmek için ek seçenekler ekleyin. Neler ekleyebileceğiniz hakkında bilgi için bkz. WPP Önişlemcisi.
  5. Hedef yapılandırmanız ve platformunuz için projeyi veya çözümü oluşturun. Bkz. WDK ile Sürücü Oluşturma.

Derleme işlemi hakkında bilgi için bkz. TraceWPP görevi , WDK ve Visual Studio derleme ortamı.

TraceWPP aracını (TraceWPP.exe) kullanarak ön işlemciyi derleme ortamından ayrı olarak da çalıştırabilirsiniz. Bu araç, WDK'nin bin/x86 ve bin/x64 alt dizininde bulunur.

7. Adım: İzleme iletilerinizi yakalamak ve doğrulamak için bir izleme oturumu başlatın

WPP izlemeyi doğru ayarladığınızı doğrulamak için sürücünüzü veya uygulamanızı bir test bilgisayarına yüklemeniz ve ardından izleme iletilerini yakalamak için bir izleme oturumu oluşturmanız gerekir. Logman, Tracelog veya TraceView gibi herhangi bir izleme denetleyicisini kullanarak izleme sağlayıcınız için bir izleme oturumu oluşturabilirsiniz. İletileri bir günlük dosyasına yazabilir veya bir çekirdek hata ayıklayıcısına gönderebilirsiniz. Kullandığınız izleme iletisi işlevlerine bağlı olarak, iletileri oluşturacak izleme bayraklarını ve izleme düzeylerini belirttiğinizden emin olmanız gerekir.

Örneğin, Evntrace.h içinde tanımlanan izleme düzeylerini kullanıyorsanız ve TRACE_LEVEL_INFORMATION (4) veya üzerini yakalamak istiyorsanız, düzeyi 4 olarak ayarlamanız gerekir. İzleme oturumu için düzeyi 4 olarak ayarladığınızda, izleme bayrakları gibi diğer koşulların da karşılandığı varsayılarak tüm bilgilendirme (4), uyarı (3), hata (2) ve kritik (1) iletiler de yakalanır.

Tüm iletilerinizin oluşturulduğunu doğrulamak için, tüm iletilerin oluşturulması için izleme düzeyini ve izleme bayraklarını en yüksek değerlere ayarlayabilirsiniz. İzleme bayrakları bit maskesi (ULONG) kullanır, böylece tüm bitleri (örneğin, 0xFFFFFFFF) ayarlayabilirsiniz. İzleme düzeyleri bir bayt değeriyle temsil edilir. Örneğin Logman kullanıyorsanız tüm düzeyleri kapsayacak şekilde 0xFF belirtebilirsiniz.

(Örnek) Logman kullanarak izleme oturumu başlatma

logman create trace "myWPP_session" -p {11C3AAE4-0D88-41b3-43BD-AC38BF747E19} 0xffffffff 0xff -o c:\DriverTest\TraceFile.etl 

logman start "myWPP_session"

logman stop "myWPP_session"

(Örnek) TraceLog kullanarak izleme oturumu başlatma

tracelog -start MyTrace -guid  MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF

Tracelog komutu, olay izleme günlük dosyasının adını ve konumunu belirtmek için -f parametresini içerir. Bayrak kümesini belirtmek için -flag parametresini ve düzey ayarını belirtmek için -level parametresini içerir. Bu parametreleri atlayabilirsiniz, ancak bayrağı veya düzeyi ayarlamadığınız sürece bazı izleme sağlayıcıları herhangi bir izleme iletisi oluşturmaz. İzleme Düzeyi Evntrace.h dosyasında tanımlanır ve izleme düzeyleri izleme iletilerini kritik, hata, uyarı ve bilgilendirme iletileri olarak sınıflandırmanın kullanışlı bir yolunu sağlar.

  • Last updated on