WDK Build Environment Refactoring. Outline Header Reorganization Hierarchical Headers Header...
-
Upload
kyle-larsen -
Category
Documents
-
view
219 -
download
2
Transcript of WDK Build Environment Refactoring. Outline Header Reorganization Hierarchical Headers Header...
WDK Build Environment RefactoringWDK Build Environment Refactoring
OutlineOutline
Header ReorganizationHierarchical HeadersHeader Versioning IFS Kit Content (headers, libs, docs)General review of INC dir structure
Documentation redesignIntegrated DDK + Test (aka HCT) + IFSNew Table of ContentsIndex Improvements
Build Environment Changes and TipsWDF Side-by-Side Install DbgPrint changes in LonghornDeprecated function checkingChanges to Driver VerifierCall Usage Verifier
WDK Header ReorganizationWDK 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 headersEnable creation of binaries for multiple platformsusing single set of headers
WDK Header HierarchyWDK 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
WDM.H
NTDDK.H
NTIFS.H
##includeinclude
##includeinclude
WDK Header VersioningWDK 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 VersioningUsing 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 ExampleStructure 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;#endiftypedef 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 ExampleFunction Example
// // Windows XP version//#if (NTDDI_VERSION >= NTDDI_WINXP) NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name );
//// Windows 2000 version//#elif (NTDDI_VERSION >= NTDDI_WIN2K) NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved );#endif
//// Windows 2000 version//NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved );
// // Windows XP version//NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name );
DeprecatedDeprecatedFunction ExampleFunction Example
// Windows Server 2003 version//#if (NTDDI_VERSION >= NTDDI_WS03) NTKERNELAPIDECLSPEC_DEPRECATED_DDK_WS03 NTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar );
// // Windows XP version//#elif (NTDDI_VERSION >= NTDDI_WINXP) NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name );
//// Windows 2000 version//#elif (NTDDI_VERSION >= NTDDI_WIN2K) NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved );#endif
//// Windows 2000 version//NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PVOID Reserved );
// // Windows XP version//NTKERNELAPINTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar // New type and name );
//// Windows Server 2003 version//NTKERNELAPI
DECLSPEC_DEPRECATED_DDK_WS03 NTSTATUSIoQueueFoo( IN PFOO_QUEUE FooQueue, IN PFOO Foo, IN PBAR Bar );
WDK Header Versioning ScenariosWDK 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.HExample: 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 directlyDrivers built to run on Windows 2000 that want to use this function when available… see next slide.
Example: Driver Runs on Windows 2000 or LaterExample: Driver Runs on Windows 2000 or LaterUses New Function When Available 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 MergeIFS 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 StructureThe New INC Directory StructureC:\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
WDK Documentation Improvements
What You Asked ForWhat 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 DoingWhat 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 ContentIntegrated 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 ContentsImproved 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 TOCImprove TOC
Old TOC:
New TOC:
Improve TOCImprove TOC
Redesign IndexRedesign Index
Added keywords
Retained DDI names
Removed titles
Add Sample ReadmesAdd 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 ReadmesAdd Sample Readmes
Build Environment Changes and Tips
Using and Installing WDFUsing and Installing WDF
WDF will be added-to existing DDK installations
Building WDF DriversOpen a DDK build environment Window
Set WDF_ROOT to base WDF install directory
Build as usual!
WDF Build ProcedureWDF Build Procedure
Example of using the Windows Server 2003 DDK and Build Environment with WDF:
Driver Debug Output in LonghornDriver Debug Output in Longhorn
Use of Ordinary DbgPrint DiscouragedToo much spew!!
Slow
Shouldn’t be in free version of driver
WPP Tracing EncouragedUse standard levels
Integrates well with WDF-based tracing
TraceView V2.1 now available
If You Must DbgPrint in LonghornIf You Must DbgPrint in Longhorn
DbgPrints Automatically Become DbgPrintExDPFLTR_DEFAULT_ID ComponentDPFLTR_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
orEnable DPFLTR_INFO_LEVEL output for DPFLTR_DEFAULT_ID (see next slide)
Enabling DbgPrint Output in LonghornEnabling DbgPrint Output in Longhorn
From WinDbg or KDSet the appropriate mask in Kd_DPFLTR_MASK
Using the RegistryCreate 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 CheckingDeprecated Function Checking
What Is It?Flags calls to obsolete functions and macros
Suggests replacements
Enabled By Default In Longhorn Checked Build EnvironmentTo Enable In Other Build Environments Define Environment Variable: DEPRECATE_DDK_FUNCTIONSErrors 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 LonghornDDI 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 LonghornDriver 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)Call Usage Verifier (CUV)
Run-time analysis tool
Tracks driver use of data structures in DDI callsEnsures use is correct and consistent over time
Best Used With Driver VerifierDriver Verifier provides required points
CUV provides recommendations, some items are speculative
Classes of Errors CUV FindsClasses of Errors CUV Finds
Initialization Errors (spin locks, lists, etc)No initialization prior to use
Multiple initializations
IRP Stack ErrorsNo next stack location
No current stack location
Consistency ErrorsSpin Locks
NO KeAcquireSpinLock for the ISR spin lock
NO KeAcquireSpinLock for in-stack queued spinlock
Interlocked listsSame 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 DriverHow 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 ErrorsHow 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)?
Changes to CUV For LonghornChanges 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 ActionCall to ActionStart preparing for the WDK nowSign 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 1Immediately report any problems you find to wdkfb @ microsoft.comProvide feedback on the WDK documentation collection to ddksurv1 @ microsoft.comUse WPP Tracing in your driversIf you must DbgPrint, change Those DbgPrint’s to DbgPrintEx’sUse the New TraceView and tell us what you think
wdkfb @ microsoft.comEnable deprecated function checking in all your buildsUpdate those calls to deprecated DDIsUse the latest Call Usage Verifier and tell us what you think
wdkfb @ microsoft.com
Additional ResourcesAdditional 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 WDKOSR Online (http:/www.osronline.com)
Articles, informationPeer help: NTDEV newsgroup
© 2004 Microsoft Corporation. All rights reserved.© 2004 Microsoft Corporation. All rights reserved.This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.