Kernel Mustard

Version 6.6.7.5 of the debugging tools has been released. Get ‘em at http://www.microsoft.com/whdc/devtools/debugging/default.mspx. And, Ken has some extra upgrade advice for remote debugging.

I’ve provided a few code samples in the past, and with any luck, there will be more to come. To that end, I’m taking a page from Raymond and providing a scratch driver and test app for use in our demos. It builds cleanly with 3790.1830 and with the beta 2 WDK; it ought to build with anything else, though, given how simple it is.

The linked zip includes both the driver and the test app. First, here’s the code for the scratch driver itself. Starting with the sources file:

sources
-------

TARGETNAME=sdriver
TARGETTYPE=DRIVER
TARGETPATH=obj

MSC_WARNING_LEVEL=/W4 /WX /Wp64

PRECOMPILED_INCLUDE=pch.h
PRECOMPILED_PCH=pch.pch
PRECOMPILED_obj=pch.obj

SOURCES= sdriver.c

Note that we’re building with /WX /W4 /Wp64. This is pretty strict, but it’s what I would recommend. Next, of course, is the standard one-liner makefile:

makefile
--------

!INCLUDE $(NTMAKEENV)\makefile.def

We’re set up to use precompiled headers, in part so that we can cleanly control the warning level of the system headers without having to copy pragma statements into every file. The PCH file:

pch.h
-----

#ifndef __PCH_H_
#define __PCH_H_

#pragma warning(push,3)
#include 
#pragma warning(pop)

/* 3790.1830 warns on PAGED_CODE */
#pragma warning(disable:4127)

#endif

Finally, the scratch driver’s header and main source file:

sdriver.h
---------

#ifndef __SDRIVER_H_
#define __SDRIVER_H_

NTSTATUS
DriverEntry(
    PDRIVER_OBJECT  DriverObject,
    PUNICODE_STRING RegistryPath);

#endif

---------
sdriver.c
---------

#include "pch.h"
#include "sdriver.h"

#ifdef ALLOC_PRAGMA
#pragma alloc_text(INIT, DriverEntry)
#endif

NTSTATUS DriverEntry(
    PDRIVER_OBJECT  DriverObject,
    PUNICODE_STRING RegistryPath)
{
        UNREFERENCED_PARAMETER(DriverObject);
        UNREFERENCED_PARAMETER(RegistryPath);

        return STATUS_UNSUCCESSFUL;
}

The high warning level means that we have to use UNREFERENCED_PARAMETER macros to disable the unreferenced parameter warnings. We’re using an explicit pragma to let the OS know that DriverEntry is init-time code only, so it can be discarded. Finally, we have broken out the project’s own include file (sdriver.h) from the rest of the pch file; PCH is best used on system headers, as opposed to frequently changing headers that are a part of the project itself.

In addition, I’m including a test app in the ZIP file that we’ll use to exercise the driver. It’ll probably be added to over time, but at the moment, it is a simple shell. We’ll bring along the same build infrastructure from the driver. The makefile is identical; the sources, pch.h, and test.cpp files are listed below:

sources
-------

TARGETNAME=stest
TARGETTYPE=PROGRAM
TARGETPATH=obj

MSC_WARNING_LEVEL=/W4 /WX /Wp64

TARGETLIBS=$(SDK_LIB_PATH)\user32.lib

UMTYPE=console
UMENTRY=wmain
USE_MSVCRT=1
USE_STL=1
STL_VER=60

PRECOMPILED_INCLUDE=pch.h
PRECOMPILED_PCH=pch.pch
PRECOMPILED_obj=pch.obj

SOURCES= stest.cpp

-----
pch.h
-----
#ifndef __PCH_H_
#define __PCH_H_

#define UNICODE

#pragma warning(push,3)
#include 
#pragma warning(pop)

#endif

---------
stest.cpp
---------
#include "pch.h"

int __cdecl wmain(int argc, wchar_t **argv)
{
        UNREFERENCED_PARAMETER(argc);
        UNREFERENCED_PARAMETER(argv);

        MessageBox(0, L"Hello world", L"Hi", MB_OK);
}

Mostly the same story as above. We’re explicitly making this test app UNICODE from the start (I’m tired of win9x), so the sources, pch.h, and stest.cpp files are set up as such. wmain() is explicitly decorated as __cdecl; the DDK environment defaults to __stdcall, but main is __cdecl by definition, so this is necessary. Finally, the test app is going to be C++, so I’m going to go out on a limb and declare that STL is in use in the sources file from the get-go. We also choose to link to the dll version of the CRT.

One thing that is worth pointing out here is that you have to build the drivers for the OS you’re going to run them on. If you build targeting Vista, your test app won’t run on XP.

Please leave a comment with any suggestions or bugs; I just whipped this up this evening, and other than PREfast and (obviously) building it, I haven’t tested this much.

UPDATED: Fixed broken download link.