1 / 41

WDK Build Environment Refactoring

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

durin
Download Presentation

WDK Build Environment Refactoring

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. WDK Build Environment Refactoring

  2. 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

  3. 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 platformsusing single set of headers

  4. 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 havedefinitions specific to them • Enables versioning NTIFS.H #include NTDDK.H #include WDM.H

  5. 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

  6. 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

  7. 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;

  8. 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 );

  9. DeprecatedFunction Example // Windows Server 2003 version // #if (NTDDI_VERSION >= NTDDI_WS03) NTKERNELAPI DECLSPEC_DEPRECATED_DDK_WS03NTSTATUS 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 Server 2003 version // NTKERNELAPI DECLSPEC_DEPRECATED_DDK_WS03NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar ); // // Windows XP version // NTKERNELAPI NTSTATUS IoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name );

  10. 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

  11. Example: Function Definition in WDM.H • Function defined as available in Windows XP and later: #if (NTDDI_VERSION >= NTDDI_WINXP)_DECL_HAL_KE_IMPORTVOIDFASTCALLKeAcquireInStackQueuedSpinLock ( 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.

  12. Example: Driver Runs on Windows 2000 or LaterUses 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); }

  13. 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

  14. The New INC Directory Structure C:\WINDDK\37905018\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

  15. WDK Documentation Improvements

  16. 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

  17. 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

  18. 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

  19. 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

  20. Improve TOC Old TOC:

  21. Improve TOC New TOC:

  22. Redesign Index • Added keywords • Retained DDI names • Removed titles

  23. 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

  24. Add Sample Readmes

  25. Build Environment Changes and Tips

  26. 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!

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

  28. 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

  29. 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)

  30. 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

  31. 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

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

  33. 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

  34. 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

  35. 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

  36. 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

  37. 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 aListhead for Interlocked operations by this driver. Break, Ignore, Zap, Remove, Disable all (bizrd)?

  38. 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

  39. 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 ddksurv1 @ 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 • 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

  40. 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

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

More Related