WDK Build Environment Refactoring Outline Header Reorganization Hierarchical

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 Dbg. Print 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 usingle set of headers

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

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 Rtl. Is. Nt. Ddi. Version. Available Rtl. Is. Service. Pack. Version. Installed 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 { PVOID irpstuff; } IRP; // // Windows XP IRP structure // typedef struct _IRP { PVOID irpstuff; PVOID newstuff; } IRP; // // Windows 2000 IRP structure // typedef struct _IRP_WIN 2 K { PVOID irpstuff; } IRP_WIN 2 K; // // 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_WIN 2 K) typedef IRP_WIN 2 K IRP; #endif typedef IRP *PIRP;

Function Example // // Windows 2000 version // NTKERNELAPI NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PVOID Reserved ); // // Windows XP version // NTKERNELAPI NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PBAR Bar // New type and name ); // // Windows XP version // #if (NTDDI_VERSION >= NTDDI_WINXP) NTKERNELAPI NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PBAR Bar // New type and name ); // // Windows 2000 version // #elif (NTDDI_VERSION >= NTDDI_WIN 2 K) NTKERNELAPI NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PVOID Reserved ); #endif

Deprecated Function Example // // Windows 2000 version // NTKERNELAPI NTSTATUS Io. Queue. Foo( // PFOO_QUEUE // IN Windows Server. Foo. Queue, 2003 version // IN PFOO Foo, IN PVOID Reserved NTKERNELAPI ); DECLSPEC_DEPRECATED_DDK_WS 03 NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, // IN PFOO // Windows XP Foo, version IN PBAR Bar // ); NTKERNELAPI NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PBAR Bar // New type and name ); // Windows Server 2003 version // #if (NTDDI_VERSION >= NTDDI_WS 03) NTKERNELAPI DECLSPEC_DEPRECATED_DDK_WS 03 NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PBAR Bar ); // // Windows XP version // #elif (NTDDI_VERSION >= NTDDI_WINXP) NTKERNELAPI NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PBAR Bar // New type and name ); // // Windows 2000 version // #elif (NTDDI_VERSION >= NTDDI_WIN 2 K) NTKERNELAPI NTSTATUS Io. Queue. Foo( IN PFOO_QUEUE Foo. Queue, IN PFOO Foo, IN PVOID Reserved ); #endif

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 Mm. Get. System. Routine. Address or Query. Interface 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 Ke. Acquire. In. Stack. Queued. Spin. Lock ( IN PKSPIN_LOCK Spin. Lock, IN PKLOCK_QUEUE_HANDLE Lock. Handle ); #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 Acquire. In. Stack. Queued = NULL; if ( Rtl. Is. Nt. Dd. IVersion. Available(NTDDI_WINXP) ) { // We’re running on XP or later Rtl. Init. Unicode. String(&func. Name, L"Ke. Acquire. In. Stack. Queued. Spin. Lock"); Acquire. In. Stack. Queued = (PACQUIREINSTACKQUEUED) Mm. Get. System. Routine. Address(&func. Name); } if ( NULL != Acquire. In. Stackqueued ) { (Acquire. In. Stack. Queued)(&Spinlock, &lock. Handle); } else { Ke. Acquire. Spin. Lock(&Spin. Lock, &old. Irql); }

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: WINDDK37905018inc ├───atl 21 ├───atl 30 ├───atl 70 ├───crt │ ├───gl │ └───sys ├───ddk <- 14 subdirs under “ddk” and “ifs” flattened to one ├───inc 16 │ └───sys ├───mfc 42 ├───mfc 70 └───user <- 4 subdirs “wxp” “wnet” “wlh” “w 2 k” 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 SP 1

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:

Improve TOC New 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 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 Dbg. Print 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 Trace. View V 2. 1 now available

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

Enabling Dbg. Print Output in Longhorn From Win. Dbg or KD Set the appropriate mask in Kd_DPFLTR_MASK Using the Registry Create a value named “DPFLTR” under HKLMSYSTEMCurrent. Control. SetControlSession 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 0 x. F

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: testmydriver. c(1785) : error C 4996: 'Rtl. Extended. Integer. Multiply‘ was declared deprecated winddk5053incddklhntddk. h(3106) : error see declaration of 'Rtl. Extendednteger. Multiply

DDI Changes in Longhorn More functions are being deprecated in Longhorn Some functions will be unnecessary when running on Longhorn and later Po. Call. Driver(…) Po. Start. Next. Power. Irp(…)

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 Io. Call. Driver 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 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 Ke. Acquire. Spin. Lock for the ISR spin lock NO Ke. Acquire. Spin. Lock 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 Initialize. Spin. Lock(. . . ) at File c: projectslinklist. c, Line 225 The Spin lock specified as parameter 1 [0 x 811 abe 78] 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 – http: //www. microsoft. com/whdc/driver/wdk Compile your drivers using the refactored headers in Windows Longhorn Beta 1 Immediately report any problems you find to wdkfb @ microsoft. com Provide feedback on the WDK documentation collection to ddksurv 1 @ microsoft. com Use WPP Tracing in your drivers If you must Dbg. Print, change Those Dbg. Print’s to Dbg. Print. Ex’s Use the New Trace. View and tell us what you think wdkfb @ 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 wdkfb @ microsoft. com

Additional Resources Web Resources: Windows Driver and Hardware Central – http: //www. microsoft. com/whdc Windows Driver Kit Page – http: //www. microsoft. com/whdc/driver/wdk Email wdkfb @ microsoft. com for feedback and questions on the WDK OSR Online (http: /www. osronline. com) 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.