WDK Build Environment Refactoring

Outline Header Reorganization Hierarchical Headers Header Versioning IFS Kit Content (headers, libs, docs) General review of INC dir structure Documentation redesign Integrated DDK + Test (aka HCT) + IFS New Table of Contents Index Improvements Build Environment Changes and Tips WDF Side-by-Side Install DbgPrint changes in Longhorn Deprecated function checking Changes to Driver Verifier Call Usage Verifier

WDK Header Reorganization Overall Goal: Support drivers for Windows 2000 and forward with one set of headers Initiatives: Create a “header hierarchy” WDM.H  NTDDK.H  NTIFS.H Add version support to the DDK and IFS kit headers Enable creation of binaries for multiple platforms using single set of headers

WDK Header Hierarchy Core headers utilize a superset/subset model Higher level headers #include lower headers Result: Definitions moved to lowest common header Higher headers only have definitions specific to them Enables versioning WDM.H NTDDK.H NTIFS.H # include

WDK Header Versioning ONE set of headers can produce binaries for multiple O/S versions Applies to both Kernel and User mode headers Human readable collection of version constants created #if statements in headers compare target with version constants This feature is planned for Windows codenamed “Longhorn” Beta 1

Using WDK Header Versioning New Rtl functions to check O/S versions at run time RtlIsNtDdiVersionAvailable RtlIsServicePackVersionInstalled These functions have been ported to all down-level environments Target O/S determined by WDK build environment Function prototypes for target version are exposed All versions of structures are exposed

Structure Example // // Windows 2000 IRP structure // typedef struct _IRP_WIN2K { PVOID irpstuff; } IRP_WIN2K; // // Windows XP IRP structure // typedef struct _IRP_WINXP { PVOID irpstuff; PVOID newstuff; } IRP_WINXP; // // Choose the default IRP // structure // #if (NTDDI_VERSION >= NTDDI_WINXP) typedef IRP_WINXP IRP; #elif (NTDDI_VERSION >= NTDDI_WIN2K) typedef IRP_WIN2K IRP; #endif typedef IRP *PIRP; // // Windows 2000 IRP structure // typedef struct _IRP { PVOID irpstuff; } IRP; // // Windows XP IRP structure // typedef struct _IRP { PVOID irpstuff; PVOID newstuff; } IRP;

Function Example // // Windows XP version // #if (NTDDI_VERSION >= NTDDI_WINXP) NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name ); // // Windows 2000 version // #elif (NTDDI_VERSION >= NTDDI_WIN2K) NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved ); #endif // // Windows 2000 version // NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved ); // // Windows XP version // NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name );

Deprecated Function Example // Windows Server 2003 version // #if (NTDDI_VERSION >= NTDDI_WS03) NTKERNELAPI DECLSPEC_DEPRECATED_DDK_WS03 NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar ); // // Windows XP version // #elif (NTDDI_VERSION >= NTDDI_WINXP) NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name ); // // Windows 2000 version // #elif (NTDDI_VERSION >= NTDDI_WIN2K) NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved ); #endif // // Windows 2000 version // NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved ); // // Windows XP version // NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name ); // // Windows Server 2003 version // NTKERNELAPI DECLSPEC_DEPRECATED_DDK_WS03 NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar );

WDK Header Versioning Scenarios Driver targeted to single O/S version Nothing special or extra to do Use only functions and definitions for that version Driver targeted to multiple O/S versions – restricted to only using down-level functionality Use build environment for oldest O/S version Use only functions and definitions available for that version Driver targeted to multiple O/S versions – using new features when running on newer O/S versions Use build environment for oldest O/S version Directly use functions and definitions available for oldest O/S version Use new Rtl functions to check O/S version at run time Use MmGetSystemRoutineAddress or QueryInterface to get pointers to functions available in newer versions you wish to use

Example: Function Definition in WDM.H Function defined as available in Windows XP and later: #if (NTDDI_VERSION >= NTDDI_WINXP) _DECL_HAL_KE_IMPORT VOID FASTCALL KeAcquireInStackQueuedSpinLock ( IN PKSPIN_LOCK SpinLock, IN PKLOCK_QUEUE_HANDLE LockHandle ); #endif Drivers built to run only on Windows XP or later call this function directly Drivers built to run on Windows 2000 that want to use this function when available… see next slide.

Example: Driver Runs on Windows 2000 or Later Uses New Function When Available AcquireInStackQueued = NULL; if ( RtlIsNtDdIVersionAvailable(NTDDI_WINXP) ) { // We’re running on XP or later RtlInitUnicodeString(&funcName, L"KeAcquireInStackQueuedSpinLock"); AcquireInStackQueued = (PACQUIREINSTACKQUEUED) MmGetSystemRoutineAddress(&funcName); } if ( NULL != AcquireInStackqueued ) { (AcquireInStackQueued)(&Spinlock, &lockHandle); } else { KeAcquireSpinLock(&SpinLock, &oldIrql); }

IFS Kit Merge The Installable File System is planned to be distributed as part of WDK starting at Beta 1 This includes: Libraries Headers Samples Documentation

The New INC Directory Structure C:\WINDDK\ \inc ├───atl21 ├───atl30 ├───atl70 ├───crt │ ├───gl │ └───sys ├───ddk<- 14 subdirs under “ddk” and “ifs” flattened to one ├───inc16 │ └───sys ├───mfc42 ├───mfc70 └───user <- 4 subdirs “wxp” “wnet” “wlh” “w2k” flattened to one

WDK Documentation Improvements

What You Asked For Conducted documentation survey in Summer 2004 Results: Make it easier to find Content: Improve Table of Contents Improve Index Improve Search and Navigation

What We’re Doing Integrating Content from prior kits Improve Table of Contents: more hierarchical, improve grouping Improve Index: remove titles, add more keywords: more “index-like” Add Samples and Tools “readme” information to documentation collection – available in TOC and during Search – improves Search by making collection more comprehensive Add subsets to filter information based on device technology Some improvements are in DDK for Windows Server 2003 SP1

Integrated Content WDK Documentation collection will integrate all the kit information DDK docs: Design Guides and DDI Ref Pages IFS Kit docs Driver Test Manager and WDK logo tests DCT tests All Device specific information will be together Design Reference Samples Tests

Improved Table of Contents Old TOC: Top Level too flat Little grouping of related content Order of material not intuitive New TOC: Simplified Top Level: easier to understand, put general information at top, created tier for device specific information, including samples and tests Driving standardized Device categories Alphabetize Device categories Eliminated “catch-all” Appendix – moved information appropriate location

Improve TOC Old TOC:

New TOC: Improve TOC

Redesign Index Added keywords Retained DDI names Removed titles

Add Sample Readmes Old: Information about Samples was not available in the documentation collection Search did not return information about Samples New: Sample information discoverable by Search

Add Sample Readmes

Build Environment Changes and Tips

Using and Installing WDF WDF will be added-to existing DDK installations Building WDF Drivers Open a DDK build environment Window Set WDF_ROOT to base WDF install directory Build as usual!

WDF Build Procedure Example of using the Windows Server 2003 DDK and Build Environment with WDF:

Driver Debug Output in Longhorn Use of Ordinary DbgPrint Discouraged Too much spew!! Slow Shouldn’t be in free version of driver WPP Tracing Encouraged Use standard levels Integrates well with WDF-based tracing TraceView V2.1 now available

If You Must DbgPrint in Longhorn DbgPrints Automatically Become DbgPrintEx DPFLTR_DEFAULT_ID Component DPFLTR_INFO_LEVEL Level All xxx_INFO_LEVEL Output Is Disabled By Default Problem? On Longhorn by default your DbgPrint output will not be visible! To See Your Output, either: Use DbgPrintEx with DPFLTR_ERROR_LEVEL in your code or Enable DPFLTR_INFO_LEVEL output for DPFLTR_DEFAULT_ID (see next slide)

Enabling DbgPrint Output in Longhorn From WinDbg or KD Set the appropriate mask in Kd_DPFLTR_MASK Using the Registry Create a value named “DPFLTR” under \HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\ Debug Print Filter Set value equal to appropriate mask What Mask Value Is “Appropriate”? From NTDDK.H: #define DPFLTR_ERROR_LEVEL 0 #define DPFLTR_WARNING_LEVEL 1 #define DPFLTR_TRACE_LEVEL 2 #define DPFLTR_INFO_LEVEL 3 To Enable All Output, Use Mask Value of 0xF

Deprecated Function Checking What Is It? Flags calls to obsolete functions and macros Suggests replacements Enabled By Default In Longhorn Checked Build Environment To Enable In Other Build Environments Define Environment Variable: DEPRECATE_DDK_FUNCTIONS Errors Flagged at Compile Time: \test\mydriver.c(1785) : error C4996: 'RtlExtendedIntegerMultiply‘ was declared deprecated \winddk\5053\inc\ddk\lh\ntddk.h(3106) : error see declaration of 'RtlExtendedntegerMultiply

DDI Changes in Longhorn More functions are being deprecated in Longhorn Some functions will be unnecessary when running on Longhorn and later PoCallDriver(…) PoStartNextPowerIrp(…)

Driver Verifier Changes for Longhorn With Each Release, Driver Verifier Gets Smarter For Longhorn (already done): Log of IRPs that take too long to complete New category of miscellaneous checks More Changes Anticipated (not guaranteed) – Examples: Force STATUS_PENDING return from IoCallDriver Detect long DPCs/ISRs

Call Usage Verifier (CUV) Run-time analysis tool Tracks driver use of data structures in DDI calls Ensures use is correct and consistent over time Best Used With Driver Verifier Driver Verifier provides required points CUV provides recommendations, some items are speculative

Classes of Errors CUV Finds Initialization Errors (spin locks, lists, etc) No initialization prior to use Multiple initializations IRP Stack Errors No next stack location No current stack location Consistency Errors Spin Locks NO KeAcquireSpinLock for the ISR spin lock NO KeAcquireSpinLock for in-stack queued spinlock Interlocked lists Same spin lock used with list every time Once a listhead is used with an “interlocked” function it must always be

How to Use CUV With Your Driver Define VERIFIER_DDK_EXTENSIONS Your Build Environment (Server 2003 or Later) Build Your Driver Using “Build” This automatically: Includes DDK_EXT.H Links With DDK_EXT.LIB

How CUV Reports Errors Run Driver with Debugger Enabled If Error Detected, Output to Debugger is Similar to Driver Verifier: CUV Driver Error: Calling InitializeSpinLock(...) at File c:\projects\linklist.c, Line 225 The Spin lock specified as parameter 1 [0x811abe78] has been previously initialized and used as a Listhead for Interlocked operations by this driver. Break, Ignore, Zap, Remove, Disable all (bizrd)?

Changes to CUV For Longhorn Already Done: Significantly Less Prone to “False Positives” Better Performance Displays Errors Using: DPFLTR_VERIFIER_ID DPFLTR_ERROR_LEVEL More Changes Anticipated (but not guaranteed) – Examples: More driver types supported Better integration with Driver Verifier

Call to Action Start preparing for the WDK now Sign up for the WDK Beta and actively participate Visit the Windows Driver Kit Page – Compile your drivers using the refactored headers in Windows Longhorn Beta 1 Immediately report any problems you find to microsoft.com Provide feedback on the WDK documentation collection to microsoft.com Use WPP Tracing in your drivers If you must DbgPrint, change Those DbgPrint’s to DbgPrintEx’s Use the New TraceView and tell us what you think microsoft.com Enable deprecated function checking in all your builds Update those calls to deprecated DDIs Use the latest Call Usage Verifier and tell us what you think microsoft.com

Additional Resources Web Resources: Windows Driver and Hardware Central – Windows Driver Kit Page – microsoft.com for feedback and questions on the WDK OSR Online ( Articles, information Peer help: NTDEV newsgroup

© 2004 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.