OSRLogoOSRLogoOSRLogo x Seminar Ad

Everything Windows Driver Development

GoToHomePage xLoginx

    Sun, 24 Sep 2017     114895 members


  Online Dump Analyzer
OSR Dev Blog
The NT Insider
ListServer / Forum
Driver Jobs
  Express Links
  · The NT Insider Digital Edition - May-June 2016 Now Available!
  · Windows 8.1 Update: VS Express Now Supported
  · HCK Client install on Windows N versions
  · There's a WDFSTRING?
  · When CAN You Call WdfIoQueueP...ously

ASSERT Yourself - The New NT_ASSERT Macro in the WDK

The ASSERT macro has been around in its current form since the dawn of humankind. You supply an expression to the macro and, if the result is FALSE, the expression is output to the debugger and you're given a few choices on how to proceed:

*** Assertion failed: KeGetCurrentIrql() != PASSIVE_LEVEL
***   Source File: g:\nothing\nothing.c, line 117

Break repeatedly, break Once, Ignore, terminate Process, or terminate Thread (boipt)?

It's simple, clean, and well-worn. Really, who doesn't love that? Well, apparently someone doesn't love it because a brand spanking new ASSERT macro has been added to the WDK: NT_ASSERT.

Not Just a New Name
NT_ASSERT dramatically changes the semantics of how asserts are presented and handled, but in a subtle way. What I mean by this is that the new assert fundamentally works the same way as the old one:

  • The macro is a no-op in free builds.
  • If the supplied statement is FALSE, the system traps into the debugger.
  • If no debugger is attached, the system blue screens.

However, under the covers the implementation of NT_ASSERT is dramatically different to that of ASSERT. Some of the changes NT_ASSERT brings along are good and, inevitably, some are bad.

Breaking Down the New Macro
Let's check out the new NT_ASSERT macro as it is defined in the Beta 2 WDK to see what we're in for (shown in Figure 1).

#define NT_ASSERT(_exp) \
    ((!(_exp)) ? \
        (__annotation(L"Debug", L"AssertFail", L#_exp), \
         DbgRaiseAssertionFailure(), FALSE) : \

Figure 1 - NT_ASSERT

I must admit, when I first saw this I was thrown for a bit of a loop. I mean, this is quite a departure from the old ASSERT macro. Also, I couldn't say that I was an expert in the "annotation" intrinsic or that I had ever even heard of DbgRaiseAssertionFailure. So, a bit of digging was in order.

Note: The reader should assume that all information provided is based on definitions and output received from the x86 platform, YMMV on other architectures. Also, the __annotations intrinsic is entirely undocumented. Therefore, all information provided in this article is based on observation of the current implementation.

Believe it or not, the __annotation intrinsic has been around for quite some time now. While it looks fairly ominous, its job is simple. When you provide an __annotation directive, you're telling the compiler to store the provided string(s) in the PDB file and not in the image itself. Once the annotations are in the PDB, they can be extracted using something called the Debug Interface Access (DIA) SDK based on relative image address. If you're having a hard time imagining how on Earth this is useful, note that WPP tracing relies heavily on the __annotation intrinsic.

Let's add an annotation to our "Nothing" driver and check out the result (See Figure 2) using DIA2Dump, which is the sample provided in the DIA SDK (we were going to write our own sample, but quickly came to our senses).

    NTSTATUS            code;
    PDEVICE_OBJECT      devObj;
    UNICODE_STRING      devName, linkName;

    DbgPrint("\nOSR NT4 DO NOTHING Driver -- Compiled %s %s\n",
        __DATE__, __TIME__);

    __annotation(L"Annotatin' like a mother.");


Figure 2 - Adding Annotation to "Nothing" Driver

DIA2Dump displays an impressive amount of information when run against a PDB file, but we're looking explicitly for annotation information. Global annotations are not currently allowed, so all annotations are associated with the functions in which they reside.

Knowing that, if you grep the output for "annotation," you shouldn't be surprised to find where our annotation is listed, as shown in Figure 3.

** Module: g:\projects\nothing\driver\objchk_wlh_x86\i386\nothing.obj

CompilandEnv   : obj = "g:\projects\nothing\driver\objchk_wlh_x86\i386\nothing.obj"
       Language: C
       Target Processor: Pentium III
       Compiled for EnC: No
       Compiler Version: FE 14.0.50727 BE 14.0.50727

CompilandEnv   : src = ".\nothing.c"

Function       :   static, [0x00004010]..., len = 00000123, _DriverEntry@8
FuncDebugStart :   static, [0x00004018]...
FuncDebugEnd   :   static, [0x0000412d]...
Annotation     :   static, [0x0000402f]...
       Data :     constant "Annotatin' like a mother...", Constant, (none)

Data :   ..., Param, Type: struct _DRIVER_OBJECT *, DriverObj
Data :   ..., Param, Type: struct _UNICODE_STRING *, RegistryPath
Data :   ..., Local, Type: struct _DEVICE_OBJECT *, devObj
Data :   ..., Local, Type: struct _UNICODE_STRING, devName
Function      : static, [0x00001010]..., len = 00000044, NothingCreateClose@8
** Module: f:\nt.obj.x86fre\base\tools\gs_support\kmode\objfre\i386\gs_support.obj

Figure 3 - Our Annotation in the Output

So, not much of a surprise, our annotation is listed under DriverEntry and is in the same section as parameter and locals information. You can also see in the above output that the relative virtual address (RVA) of the __annotation intrinsic is stored along with the annotation information - 0x0000402f, in our case.

Now that we've been introduced to annotations, let's check out the other piece of the new NT_ASSERT macro. Once we've done that we can move on to putting the two together and talk about the good and not so good of the new macro.

is either implemented as a compiler intrinsic or an inline function. Let's check out the inline function shown below.

DbgRaiseAssertionFailure (

    __asm int 0x2c

Ah yes, so it calls the old INT 2C handler... OK, so maybe I've never heard of using INT 2C for anything other than some perverted NT4 thing, but that's neither here nor there.
If you dump the IDT on your Vista system, you'll notice that the handler for the 2C interrupt is KiRaiseAssertion. If you continue to dig further, you'll notice that the execution of this routine results in a STATUS_ASSERTION_FAILURE exception being raised (we'll leave that digging as an exercise to the reader).

Let's see what we get in the debugger (below) by adding a call to this inline to the Nothing driver (shown in Figure 4):

Assertion failure - code c0000420 (first chance)
8d2e602f cd2c            int     2Ch

    NTSTATUS            code;
    PDEVICE_OBJECT      devObj;
    UNICODE_STRING      devName, linkName;

    DbgPrint("\nOSR NT4 DO NOTHING Driver -- Compiled %s %s\n",
        __DATE__, __TIME__);


Figure 4 - Adding DbgRaiseAssertionFailure to Driver

Nothing too shocking here. The inline function embedded an INT 2C in our code, which resulted in an assert exception being raised. However, hitting GO at this point reveals an interesting set of commands that were added to the debugger for handling the new assertions (see below).

kd> g
Continuing an assertion failure can result in the
debuggee being terminated (bugchecking for kernel
If you want to ignore this assertion, use 'ahi'.
If you want to force continuation, use 'gh' or 'gn'.

So, one advantage to using DbgRaiseAssertionFailure over DbgBreakPoint (or __debugbreak) is that the debugger has built-in support for ignoring the asserts it generates. Anyone who has been stuck having to NOP out a bogus ASSERT knows what a rockin' feature this is.

It turns out that there are several options available to the 'ah' command for dealing with individual asserts. There's even a new option to the 'sx' command for global assert handling. The WinDBG docs have all the details, so we won't bother duplicating that information here.

The Result
Now that we know the players involved, let's look again at the part of the NT_ASSERT macro that does the work:

_annotation(L"Debug", L"AssertFail", L#_exp), \

The comma means this is going to expand out into a single line. Therefore, the code above is adding an annotation for this instruction address with the assert information and then emitting an inline INT 2C.

At this point the astute reader will realize an important side effect - the expression string that indicates the reason of the assert is not in the driver image. Because the expression is added as an annotation, the only way to find the reason for this assert is through querying the PDB for any annotation information available for the location of the INT 2C instruction.

Let's check out what the new assert looks like in the debugger. Look at the assembly around this breakpoint (Figure 5) and notice that the expression string is nowhere to be found.

Assertion g:\nothing\nothing.c(117): KeGetCurrentIrql() != PASSIVE_LEVEL
8d2ec03c cd2c            int     2Ch


call    dword ptr [NOTHING!_imp__KeGetCurrentIrql (8d2ea000)]
movzx   eax,al
test    eax,eax
jne     NOTHING!DriverEntry+0x37 (8d2ec047)
int     2Ch
mov     dword ptr [ebp-20h],0
jmp     NOTHING!DriverEntry+0x3e (8d2ec04e)

Figure 5 - Where's Our Assert?

Thus, the debugger is clearly aware of the new assert semantics and is querying the PDB for annotation information in order to display the reason for the assert.

What About the "Not So Good?"
Earlier, I alluded to the fact that there was something not so good about the new assert and, no, I haven't forgotten. Remember when we saw the location of the annotation information in the PDB? At that point I noted it was in the same location as the parameter and locals information. This should be a slight tip-off to anyone who is familiar with the public symbols provided by Microsoft.

That's right folks, annotations are not present in public PDB files. If you're used to running the checked build of Windows to get extra assert information, I hope your assembly skills are up to snuff because you will be tracking down the reason for the assert yourself. For example, let's check out the previous assert again, but this time we'll use symbols generated with the /PDBSTRIPPED linker option:

Assertion failure - code c0000420 (first chance)
8d2f203c cd2c            int     2Ch

Not so good, eh?

You Take the Good, You Take the Bad...
Even though it's entirely depressing that the checked build of Windows is now full of mysterious asserts, the built-in debugger support is convenient if you're not in the habit of using stripped PDBs in your development. Just remember that support for this new assert is not available in the down level platforms.

Related Articles
Enabling Debugging on the Local Machine for Windows XP®
You're Testing Me - Testing WDM/Win2K Drivers
Analyze This - Analyzing a Crash Dump
More on Kernel Debugging - KMODE_EXCEPTION_NOT_HANDLED
Making WinDbg Your Friend - Creating Debugger Extensions
Life Support for WinDbg - New Windows NT Support Tools
Life After Death? - Understanding Blue Screens
All About Lint - PC Lint and Windows Drivers
Bagging Bugs — Avoidance and Detection Tips to Consider
Choose Your Weapon: Kernel Mode Debuggers - a Choice at Last

User Comments
Rate this article and give us feedback. Do you find anything missing? Share your opinion with the community!
Post Your Comment

Post Your Comments.
Print this article.
Email this article.

Writing WDF Drivers I: Core Concepts

Nashua (Amherst), NH
15-19 May 2017

Writing WDF Drivers II: Advanced Implementation Techniques

Nashua (Amherst), NH
23-26 May 2017

Kernel Debugging and Crash Analysis

Dulles (Sterling), VA
26-30 Jun 2017

Windows Internals and Software Driver Development

Nashua (Amherst), NH
24-28 Jul 2017


Need to develop a Windows file system solution?

We've got a kit for that.

Need Windows internals or kernel driver expertise?

Bring us your most challenging project - we can help!

System hangs/crashes?

We've got a special diagnostic team that's standing by.

Visit the OSR Corporate Web site for more information about how OSR can help!

bottom nav links