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.