A Hole In My Head : Coding Thoughts

What should you change in a sample before you ship it?

doronh — Wed, 23 Apr 2008 21:41:19 GMT

I was going to write about how to do this, but the awesome folks at WHDC got to it before I did. I did get to review it before it was published, so I did have some influence in what is in the tip ;). So on this one my job is easy, just go read the tip!

one of the books that started it all...

doronh — Wed, 12 Mar 2008 18:38:00 GMT

During my sophomore year at Cal Poly, I decided that I wanted to learn about threads, synchronization techniques and other topics associated modern operating systems. Windows 95 had made its debut (yes, it is not a modern OS, but I didn't know that at the time!) and I had heard about Windows NT, but had never seen or used it. Since I had Win95 on my machine at home, I decided that I would go to the bookstore and buy a book on threading.

Well, needless to say there was not a book that was dedicated to threading, but I found a couple of books on Windows programming that included threading as topics. It came down to 2 books, Jeffrey Richter's "Advanced Windows for Win95 and NT" (with Napoleon on the cover) and some other book. I obviously picked Richter's book ;), although now it is called "Windows via C/C++."

This book was, and still is, awesome. I have both the original and new editions. Great detail, very easy to read and met it my needs perfectly (unlike "Inside OLE" by Kraig Brockschmidt which was full of information, I just could not stay awake reading it :) ). IMHO, it successfully started me down the road to becoming a well rounded developer and I think it helped in getting my foot in the door at Microsoft. I have even had the pleasure of letting Jeff know personally what a great book it is and how it shaped me for years to com.

User empathy is a weird thing

doronh — Mon, 25 Jun 2007 18:14:00 GMT

I figured that I had a good deal of empathy for a developer who had to write a driver. I have spent nearly 5 years creating and supporting WDF, learning from the community and drawing on my own experience in how drivers are written. Two of the most common questions is "what IDE should I use" and "can I write and build a driver in Visual Studio (VS)"? In terms of an IDE purely for writing code, no one can tell you what to use. Everybody's style and workflow is different. Sometimes you can't even pick, your employer will dictate that you must use program X. In this case, you are still using the WDK build window to build your driver. I understood this type of user pretty well, I am one of them. I use Visual SlickEdit as my editor (in vi mode so my hands never leave the keyboard ;) ) and use razzle (essentially the internal version of the WDK build window) to compile my code.

Writing and compiling my driver in VS is something I didn't fully grok until recently. I thought I understood the appeal of the integrated compilation results within the editor, that you could double click on an error and have that line be brought up in the editor, etc etc. What I didn't fully understand the appeal of was the actual writing of code in VS. The last time I used VS full time was in 1997 as a college undergrad working on a kiosk software project in C++ (no C# at the time ;) ). There was some rudimentary intellisense there, but not much to write home about. I just started using VS 2005 for another project and I am very impressed with the intellisense, automatching, refactoring and other features in the product. It is pretty frackin' awesome in terms of productivity and discovery of features. So I now get why a lot of you want to be able to write and build a driver in VS ;), it is a very compelling work environment.

I hope that we wil get WDK integration into VS in the future, but I think that is just the first step. There are so many things that we as Microsoft can integrate with other then getting intellisense and auto completion working. If we are to take the time to integrate into VS, it should be deep and appropriate for the entire development cycle(s), not just the writing of code.

Better control over /GS stack checking in your driver

doronh — Tue, 10 Apr 2007 19:02:00 GMT

Michael Howard has a great posting on improvements made in the compiler with respect to the /GS flag (stack checking using a "canary" on function exit). Before these changes, #pragmas to explicitly turn the functionality on or off, the compiler itself decided where it was appropriate to add the stack checks based on internal heuristics. The improvements were made to the VS2005 SP1 version of the compiler, but I just checked and the compiler in the WDK includes these changes. Use this functionality as another tool in the tool belt for writing secure drivers!

Creating your own InterlockedXxx operation

doronh — Thu, 07 Dec 2006 01:49:00 GMT

Sometimes your design requires an Interlocked operation that is not currently supported by the OS, runtime libraries, or the compiler (as an intrinsic). You then have a choice to make. Either remove all Interlocked operations for that particular field and use a lock or roll you own Interlocked function. Roll your own Interlocked function? Sounded scary to me the first time it was suggested, but in reality it is a rather easy thing to do. Here is the basic algorithm (which I did not invent, it is a well tested and known algorithm) and a couple of concrete examples

    LONG
    InterlockedYyy(
        __inout LONG  volatile *Target,
        [Additional parameters as needed for operation Yyy]
        )
    {
        LONG prevValue, prevCopy;
    
        prevValue = *Target;
    
        do {
            [Optional comparison]
    
            prevCopy = prevValue;
    
            //
            // prevValue will be the value that used to be Target if the exchange was made
            // or its current value if the exchange was not made.
            //
            prevValue = InterlockedCompareExchange(Target, Yyy operation on prevCopy, prevValue);
    
            //
            // If prevCopy == prevValue, then no one updated Target in between the deref at the top
            // and the InterlockecCompareExchange afterward and we are done
            //
        } while (prevCopy != prevValue);
    
        //
        // [value] can be anything you want, but it is typically either
        // a) The new value stored in Target.  This is the type of return value that 
        //    InterlockedIncrement returns
        // or
        // b) The new value is the previous value that was in Target.  This si the 
        //     type of return value that InterlockedOr or InterlockedExchange return
        //
        return [value];
    }

From this algorithm you can implement nearly anything you want. For instance, let's say that you want to increment Target if and only if it's current value is greater then zero. This allows you to never go from zero to one, a common problem when you implement a reference count. Since this Interlocked operation can "fail," we need a way to convey failure. In this case I chose to return the Floor value since it is an not a value that could ever be returned in the success path. Algorithm specific modifications to the generic algorithm are in red

    LONG
    MyInterlockedIncrementWithFloor(
        __inout LONG  volatile *Target,
        LONG Floor
        )
    {
        LONG prevValue, prevCopy;
    
        prevValue = *Target;
    
        do {
            if (prevValue <= Floor) {
                return Floor;
            }
    
            prevCopy = prevValue;
    
            //
            // prevValue will be the value that used to be Target if the exchange was made
            // or its current value if the exchange was not made.
            //
            prevValue = InterlockedCompareExchange(Target, prevCopy+1, prevValue);
    
            //
            // If prevCopy == prevValue, then no one updated Target in between the deref at the top
            // and the InterlockecCompareExchange afterward and we are done
            //
        } while (prevCopy != prevValue);
    
        //
        // prevCopy is the old value of Target. Since InterlockedIncrement returns the new
        // incremented value of Target, we should do the same here.
        //
        return prevCopy+1;
    }

Let's say you wanted to XOR in a value in the high word of the Target and clear the low word, you could implement it this way

    LONG
    MyInterlockedXorHighClearLowWord(
        __inout LONG  volatile *Target,
        SHORT HighWord
        )
    {
        LONG prevValue, prevCopy;
    
        prevValue = *Target;
    
        do {
            // No conditional check like the previous example

            prevCopy = prevValue;
    
            //
            // prevValue will be the value that used to be Target if the exchange was made
            // or its current value if the exchange was not made.
            //
            prevValue = InterlockedCompareExchange(
                Target, 
                (prevCopy ^ (HighWord << 16) & (~0xFFFF),
                prevValue);
    
            //
            // If prevCopy == prevValue, then no one updated Target in between the deref at the top
            // and the InterlockecCompareExchange afterward and we are done
            //
        } while (prevCopy != prevValue);
    
        //
        // prevCopy is the old value of Target. Returns the old value of Target
        // (just to demonstrate the 2nd pattern for which return type you can use)     
        //
        return prevCopy;
    }

Weird side affect of the day: #defines can be used in your .def file

doronh — Fri, 03 Nov 2006 00:58:00 GMT

I found this one out the hard way today. I was experimenting with the KMDF loader driver (wdfldr.sys). I added the following #define to my sources file so that I could share code between wdfldr and another component and control some functionality based on who was including the file

sources:
    TARGETNAME=wdfldr
    TARGETTYPE=EXPORT_DRIVER

    C_DEFINES=$(C_DEFINES) -DWDFLDR=1

    [...]

I then compiled my test driver (wdfrawbusenumtest.sys), but it failed to load! I was getting a code 39 (which meant Windows could not load my driver). I previously wrote on how to debug a missing export at runtime, and I tried to use that technique. It told me that "KeGetCurrentIrql" was unresolved, but that is not possible since hal.dll has exported this function since NT 3.1. It finally occurred to me look at the imports for my test driver to see if there was anything weird. Here is what I saw:

    link /dump /imports WdfRawBusEnumTest.sys

    [...]
        HAL.dll
                     18014 Import Address Table
                     1C290 Import Name Table
                         0 time date stamp
                         0 Index of first forwarder reference

                       4C KeGetCurrentIrql

        1.SYS
                     18000 Import Address Table
                     1C27C Import Name Table
                         0 time date stamp
                         0 Index of first forwarder reference

                        7 WdfVersionBind
                        9 WdfVersionUnbind

Huh? 1.sys? Where did that come from? I went back and checked the src file (which when compiled becomes the def file) and there were no changes there. This is what the def file looks like:

wdfldr.src:
    NAME WDFLDR.SYS

    EXPORTS
        WdfVersionBind
        WdfVersionUnbind
        [...]

Since I didn't change the def file, what was making the compiler think that the exports should resolve to 1.sys? I finally realized that my C_DEFINE of -DWDFDLR=1 was the culprit. When wdfldr.src was being built into wdfldr.def, my define changed NAME WDFLDR.SYS into NAME 1.SYS. Little did I know that the C preprocessor was used when compiling the src file. To fix the problem, all I needed to do was change the define to something else, C_DEFINES=$(C_DEFINES) -D_WDFLDR_=1, and then update my shared headers to use the new define.

The override keyword can be used in C++ afterall (redux on refactoring virtual functions)

doronh — Fri, 27 Oct 2006 23:48:00 GMT

Yesterday I wrote about the two methods I use to refactor a virtual function and make sure that I find all of the derived implementations. In the entry I lamented that I would like to have the C# keyword override implemented in C++. Well, apparently it is (at least in the Microsoft compiler)! Check it out for yourself on MSDN. Now since it was not a part of the language from the start, you cannot assume that when you change the super class's virtual function signature that the derived classes will not compile, but if you use the override ~~keyboard~~ keyword during development when you initially implement the derived classes, it will flag the mistake where you are creating a new virtual function instead of overriding an existing one.

So, let's take yesterday's classes and use the override keyword

    class Base { public: virtual void Foo() {}; };

    class Derived : public Base { public: virtual void Foo() override {}; };

Now when we change void Base::Foo() to void Foo(Bar* PBar), we get the following compiler error

    main.cpp(6) : error C3668: 'Derived::Foo' : method with override specifier 'override' did not override any base class methods

This is much better then the previous situation, although it is not as good as in the C# environment. If you forget to add the override keyword, you can still encounter the mistake of creating a new virtual function instead, but this is better then nothing!

How I refactor virtual functions

doronh — Fri, 27 Oct 2006 01:16:00 GMT

As with many development projects, I had to refactor some code in KMDF. This refactor involved changing the signature of a virtual function to take additional parameters. The problem I faced is that C++ makes no distinction between declaring a new virtual function and a virtual function which overrides a base class (C# does not have this problem because you are required to use the override keyword when overriding a base class virtual). The problem for me was finding all of the derivations across the entire code base.Before I explain into how I found all of the derivations, I want to explain the issue in more detail. Let's take the following classes:

    class Base { public: virtual void Foo(); }

    class Derived : public Base { public: virtual void Foo(); }

Derived::Foo() is a override of Base::Foo() and will be invoked correctly if using a Derived object pointer as a Base object pointer. The debugger confirms this

    0:000> dt der
    Local var @ 0xcfe60 Type Derived
       +0x000 __VFN_table : 0x008e10cc 

    0:000> dps  0x008e10cc  l1
    008e10cc  008e11f0 testsize!Derived::Foo

But let's say I want to change the signature of Foo to take a Bar* and forgot to change Derived

    class Base { public: virtual void Foo(Bar* PBar); }

    class Derived : public Base { public: virtual void Foo(); }

Now Derived::Foo() is not a derivation of Base::Foo, but it's new and very own virtual function (e.g. the vtable for the Derived object will have 2 slots instead of just one) as we can see from the debuggerA

    0:000> dt der
    Local var @ 0x13fd38 Type Derived
       +0x000 __VFN_table : 0x001810cc

    Exact matches:
    0:000> dps 0x001810cc  l2
    001810cc  00181250 testsize!Base::Foo
    001810d0  00181200 testsize!Derived::Foo

As you can see, the vtable accidentally grew when I changed Base::Foo's signature and unfortunately the compiler doesn't care. Even worse, the program will run and probably limp along with the error showing up as odd or unexplainable behavior. So, the challenge is to make the compiler find all of the derivations for you so you can fix them up. I use two techniques to make the compiler do the work for me.

The first technique is to change the return type of the function to refactor without changing the parameters themselves and then recompiling the project. This works because the rules for C++ name overloading allow for differences in the function's parameters, but if the parameters are the same, you cannot differentiate on return type. The error will be emitted in the class's implementation. So if you change Base::Foo to ULONG Foo();, the compiler will give you an error like this for every derived class which overrides Base::Foo()

    main.cpp(7) : error C2555: 'Derived::Foo': overriding virtual function return type differs and is not covariant from 'Base::Foo'."

After flagging each derived class, you can change the change the return type back and then change the parameters.

The second technique is to change the Base::Foo() to a pure virtual fuction in addition to changing the parameters. So, now Base::Foo() is declared as void Foo(Bar* PBar) =0;. Now for every class which is not an abstract base class itself, the compiler will emit an error wherever you try to instantiate the class, getting an error like this

    main.cpp(11) : error C2259: 'Derived' : cannot instantiate abstract class

The advantage of this technique is that you don't have to make 2 passes over the code to find and then alter the derived classes. A problem with this technique is that you are only notified of the problem where you try to instantiate the class instead of wheree you implement or declare the class. Another problem is that if you are implementing a derivation in a class which itself is still an abstract base class, you push the compiler error into the second derived class, obscuring where the real error is occurring.

I personally prefer the first method because it is less error prone and I like to see compiler errors at the site of the implementation and not at the site of its use.

Hindsight is 20/20, EvtDriverUnload should have not been in KMDF

doronh — Tue, 24 Oct 2006 01:38:00 GMT

The KMDF model evolved over the entire development cycle. It was refined and refactored multiple times. A lot of WDM abstractions leak through the to the KMDF model. These leaks usually forced their way into the model because without them, KMDF cannot function properly. Other abstraction leaks were just design decisions that were not updated or removed as KMDF evolved through its v1.0 development cycle.

One abstraction that should have been refactored away but was not is the EvtDriverUnload routine. Our initial thought was that since the KMDF driver must implement a DriverEntry routine, an optional driver unload routine should also be a part of the model. The problem is that if DriverEntry() returns !NT_SUCCESS, the WDM DriverUnload (and hence EvtDriverUnload) is not called. If you created global resources in DriverEntry and cleaned them up in (Evt)DriverUnload, they would not be cleaned up becuase the unload routine would never be called. Normally drivers do not create such global data, so we (the KMDF team) didn't realize that this design issue was a problem.

There is an easy fix though that we have been advocating. Instead of putting your cleanup code in EvtDriverUnload, put all cleanup code in the EvtObjectCleanup routine in the object attributes for the WDFDRIVER you create when calling WdfDriverCreate(). The cleanup routine is guaranteed to be called in both cases (DriverEntry() returning NT_SUCCESS() or !NT_SUCCESS()) once the WDFDRIVER has been created successfully. Note that important restriction, WdfDriverCreate() must return success for this pattern to work! That means that the allocation and initialization of all global resources should occur after WdfDriverCreate() has been called.

In hindsight we should have never had a EvtDriverUnload and should have had the WDFDRIVER's cleanup routine be the driver unload equivalent. Two things affected our decision to not make this change. First, we didn't realize the pattern was busted until late in the development process. By the time we did realize it, there were too many drivers in the wild and under developement to make such a significant change. Second, while EvtDriverUnload was created when KMDF development was first started, the standardized cleanup routine for each object was not introduced until much later. If both concepts were implemented at the same time in the development cycle, the unload routine would have been eliminated

Annotating fall through case statements in a switch

doronh — Fri, 20 Oct 2006 19:00:00 GMT

Accidental fall throughs in a switch statement can lead to some nasty bugs. I have used the following banner for quite a long time to indicate that the fall through is intentional and not an oversite (this banner is also a part of the KMDF coding guidelines). It has definitely helped me debug coding mistakes over the years.

    case IRP_MJ_DEVICE_CONTROL:
    case IRP_MJ_INTERNAL_DEVICE_CONTROL:
        //    ||  ||  Fall through  ||   ||
        //    \/  \/                \/   \/
    default:
        return NULL;
    }

While the banner is certainly human readable, it is not apparent to static analysis tools that the fall through was intentional. Today I discovered that there is a SAL annotation, __fallthrough, which can indicate the intentional fall through. This means you can annotate the code and tools like PreFAST and PreFAST for Drivers can better understand and analyze the code. I have not yet decided if I want to use the annotation by itself without the current banner or addition to my current banner. I am leaning towards just using the annotation though.

Using ntintsafe.h is a great idea, but I don't know how readable the results are

doronh — Fri, 20 Oct 2006 03:24:00 GMT

The addition of ntintsafe.h for detecting integer overflow/underflow is a great addition to the WDK. It unifies how everyone detects these math errors, leading to common code that anyone can pickup and see what it does...BUT, I have found it does have a "tax." What is actually being computed can be become unclear! For instance, let's take this sample before we convert it to detect any math errors:

    USHORT cbImageNameLength;

    cbImageNameLength = ((USHORT) wcslen(wsImageName)) * sizeof(WCHAR) + sizeof(UNICODE_NULL);

It is relatively straightforward and clear (depends on the viewer I guess) that we are computing the number of bytes to wsImageName requires. Here is the safe (and longer!) version of the unsafe computation:

    USHORT cbImageNameLength;
    NTSTATUS status;

    do {
        status = RtlSizeTToUShort(wcslen(wsImageName), &cbImageNameLength);
        if (!NT_SUCCESS(status)) {
            break;
        }

        status = RtlUShortMult(cbImageNameLength, sizeof(WCHAR), &cbImageNameLength);
        if (!NT_SUCCESS(status)) {
            break;
        }

        status = RtlUShortAdd(cbImageNameLength, sizeof(UNICODE_NULL), &cbImageNameLength);
        if (!NT_SUCCESS(status)) {
            break;
        }

        // cbImageNameLength has now been computed...
    } while (FALSE);

Needless to say, that is not the most transparent code I have read or written. I certainly would not go back to the unsafe vesion and I cannot use safeint object which throws execptions on error because this code runs in the kernel. The only remedy I could think of is to create a comment at the top of the block which contains the plain version. (This rule is in the KMDF coding style guidelines.) As a result, the final source would look like this:

        //
        // cbImageNameLength = ((USHORT) wcslen(wsImageName)) * sizeof(WCHAR) + sizeof(UNICODE_NULL);
        //
        status = RtlSizeTToUShort(wcslen(wsImageName), &cbImageNameLength);
        [...]

I think this is a decent tradeoff between correctness and readability. Another change you could make is to add begin/end comments around the entire computation block to further clarify the scope of which calls belong to which overall computation.

Apple's Secure Coding Guide

doronh — Mon, 24 Jul 2006 18:01:00 GMT

While I don't write apps or drivers for the Macintosh, some of you out there probably do. If you have not already seen it, they posted a Secure Coding Guide (PDF) which is focused on OS X, but has generic recommendations as well. I just started reading it, so I don't have much of an opinion about it yet.

Not a big fan of #ifdef or #ifndef

doronh — Fri, 02 Jun 2006 07:25:00 GMT

I am not a big fan of the C/C++ preprocessor directives #ifdef or #ifndef. I am not denying that they certainly have their place and usage in the language. I'll first write about where I think they are useful and then about the situations where I feel they are not. #ifndef is very useful for preventing multiple inclusions of a header which will cause redefinition errors.

#ifndef __FOO_H__ // only proceed if the token is not yet defined
#define __FOO_H__ // define the token so that subsequent includes have it defined

[...contents of the header...]

#endif // __FOO_H__, end for #ifndef statement

Of course, you can use #pragma once to do the same thing, but that is a Microsoft specific extension to the language so not everyone will use it. This usage is error prone though. I can't count the number of times that I copied one header to create another header in the same project and forgot to change the #ifndef token to a new token and couldn't figure out why my new header wasn't being evaluated properly.

#ifdef is useful in a header to switch between ANSI and wide versions of the function, such as this example from winbase.h:

#ifdef UNICODE
#define CreateFile  CreateFileW
#else
#define CreateFile  CreateFileA
#endif // !UNICODE

Now, the reason I don't like these 2 directives is that they behave differently then #if token or #if !token. #if token evaluates the value of token. If token is not defined, it defaults to zero and the #if token phrases evaluates to zero. On the other hand, #ifdef token evaluates to token to see if it is defined, regardless of the value of token. That means that the following code

#define FOO 0x0

#ifdef FOO
printf("FOO!");
#else
printf("NOT FOO!");
#endif

will print out "FOO!" even though FOO evaluates to zero. As I have written previously in my blog and in the newsgroups, I am big on maintainance of the code I write because the code I write will have to be maintained for years and its connection to me will eventually be lost by the developer who inherits it. What I don't like about #ifdef/ifndef in a source file (vs the header file examples above) is that at first glance, I mentally evaluate a #ifdef as a #if and more often then not, pick the wrong result when reviewing the code. Furthermore, everytime I see #ifndef I need to spend a minute or two staring at the entire statement to figure out what is going on, it is not immediately apparent to me what it is doing. Anytime I have to stare at something to figure out what it does, it is an indicator to me that others will probably do the same and it will eventually be a problem spot in the code in the future.

A lot of you may not agree with me and I am fine with that ;). Please let me know why though.

How to break in at the call site that invokes the break point

doronh — Tue, 09 May 2006 01:25:00 GMT

I think everyone at some point in time wants to embed a break point in there code, whether it be for debugging purposes, path tracing, or detecting edge conditions that have not yet been tested. When I hit a break point, I would prefer that the debugger break in at the call frame which needs the break point and not another function which implements the break point. I have seen two different patterns over the years.

The first pattern is to call DbgBreakPoint(). This works well enough. It is portable across different processor architectures so you don't have to worry about new platforms, but it has one major problem. When you break into the debugger, you are in the wrong call site! You end up in the middle of DbgBreakPoint() itself and not the caller. You can use the gu command, but that requires typing ;).

The second pattern is to create a #define for some inline assembly, something akin to:

#define TRAP __asm { int 3 }

This satisfies my requirement that the point of execution when we stop is in the function of interest, but this solution is platform specific. You would need enough knowledge per supported platform for this to work and that platform must support inline assembly (which x64 does not for our compilers). You could compromise and #define TRAP to DbgBreakPoint() for those platforms, but then you have a satisfactory solution on a subset of platforms.

Enter the __debugbreak() intrinsic that I just learned about this weekend from the OSR WinDBG mailing list (courtesy of Pavel A.) Yes, it is a Microsoft specific extension, but generating a break point is inheritly platform specific already. __debugbreak() is the best of both patterns. You get platform independence and when you break in to the debugger, you are sitting at the right call frame and not inside a system routine. That rocks in my book!

PS: I don't know which version of the compiler this intrinsic was introduced, but it is used in the Server 2003 SP1 DDK, so I know it has been implemented for awhile.

PPS: I never call __debugbreak() in production code, and IMHO, neither should you. To control this in a DDK build environment, I do the following

#if DBG
  #define TRAP() __debugbreak()
#else  // DBG
  #define TRAP()
#endif // DBG

Avoiding #defines for constant data and using enums instead

doronh — Tue, 28 Mar 2006 03:03:00 GMT

I think that the C preprocessor is a very powerful tool, but I like to limit my use of #defines. I have already touched on this when i talked about why I liked FORCEINLINE and I want to talk about it some more. I realize I can't eliminate the use of #defines throughout all of my code for various reasons, among them being:

They can have unintended side affects. The classic example of this is #define MAX(a, b) (a >= b ? a : b) and invoking it with MAX(foo++, bar) such that foo++ is evaluated twice leading to a double increment.
Other headers use them to enable/disable certain pieces of functionality or functions.
They are the only way to wrap up other preprocessor macros like __FILE__ and __LINE__ to allow for easier logging without more pushing more typing onto the caller.
They are the only way you can generate code on the fly in C (a poor man's C++ template if you will)
They are the only way you can use the quotify (#) or concat (##) functions within the preprocessor

The main reason I try to limit my usage of the preprocessor is that because it is a pure substitution, you generally don't have type information available to you when debugging the application or driver. A great example of this is constant numeric values within your application. You could do this to define values in a bit field:

#define OPTION_ONE   (0x00000001)
#define OPTION_TWO   (0x00000002)
#define OPTION_THREE (0x00000004)

but you will not be able to evaluate OPTION_ONE in the debugger because there is no OPTION_ONE symbol in the PDB. The preprocessor substituted OPTION_ONE with 0x0000001 before the linker was ever involved. To look up the value of OPTION_ONE you would have to open up a source file. Instead, I do the following when I have bit field values that I want to define and use within my app/driver:

#include <windows.h>

typedef enum _OPTION_FLAGS {
    OptionOne =   0x00000001,
    OptionTwo =   0x00000002,
    OptionThree = 0x00000004,
} OPTION_FLAGS;

typedef union _OPTIONS {
    ULONG Bits;

    // NOTE:  this is for debugging only, *always* use Bits in code
    struct {
        ULONG One : 1;   // OptionOne
        ULONG Two : 1;   // OptionTwo
        ULONG Three: 1;  // OptionThree
    } BitsByName;
} OPTIONS;

int _cdecl main(int argc, char *argv[])
{
    OPTIONS o;

    o.Bits = OptionTwo;

    return 0;
}

For now, let's ignore the fact that I can use protected or public to abstract how the values are set and read and that I am using an unnamed union. (Some folks feel that unnamed unions are unholy, but I find them very practical in this pattern.) There are 2 key concepts to what I am doing here:

The enumeration remains in the symbols so you can dump it within the debugger [1]. Now you don't have to look up the value in a source file.
By creating a union of the true value (Bits) [3] and a bit field of the value (BitsByName) [4] I can see what each bit means without having to look at the enum at all! This means that you can see the value without digging into the structure at all if you don't need to [2].

I have broken into the debugger right before returning.

[1] 0:000> dt OptionsFlags
   OptionOne = 1
   OptionTwo = 2
   OptionThree= 4

[2] 0:000> dt o Bits
Local var @ 0x6ff78 Type Options
   +0x000 Bits : 2

[3] 0:000> dt o BitsByName.
Local var @ 0x6ff78 Type Options
   +0x000 BitsByName  :
      +0x000 One         : 0y0
      +0x000 Two         : 0y1
      +0x000 Three       : 0y0

[4] 0:000> dt o
Local var @ 0x6ff78 Type Options
   +0x000 Bits             : 2
   +0x000 BitsByName       : Options::<unnamed-tag>

March 28, 2006: Updated the enum and union definitions to be C compliant and match my style guidelines.