Building a Multiversion Driver Using Version-Dependent Features

Misha_Karpin · March 1, 2006, 10:36am

On WDK “Building a Multiversion Driver Using Version-Dependent Features”
section, I read:

"Conditionally Calling DDIs Based on Windows Version
After a driver determines that a given DDI version is available on the
computer that it is running on, that driver can dynamically locate the
routine and call it through a pointer by using the MmGetSystemRoutineAddress
function. This function was introduced in Windows 2000 and is available on
all Windows computers that the WDK supports.

Note To help preserve type checking and prevent unintentional errors, you
should create a typedef that mirrors the original function type.

…

typedef (* PAISQSL) (KeAcquireInStackQueuedSpinLock);
PAISQSL AcquireInStackQueued = NULL;

Note that the C language syntax that the preceding typedef shows is a new,
simplified, form of the following, more traditional, syntax.

typedef void (FASTCALL * PAISQSL)(IN PKSPIN_LOCK Spinlock,
IN PKLOCK_QUEUE_HANDLE LockHandle);
PAISQSL AcquireInStackQueued = NULL;
…

The new syntax enables you to declare a pointer to a function without having
to restate the calling convention or parameters of the function. This new
syntax is supported by the compiler that is supplied with the Windows Server
2003 DDK."

Now the question. This multiversion driver with version-dependent features
must be builded using
the build environment for oldest O/S version, so how is possible to use this
new syntax for this purpose when function prototypes are not exposed NEVER
for the oldest target version in this scenario?.

Thanks,
mK

Express yourself instantly with MSN Messenger! Download today it’s FREE!
http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/

Don_Burn_1 · March 1, 2006, 10:42am

Actually, you do not have to build for the oldest in this case, but you have
to be careful. For instance the WDK’s file system filter examples are built
for Windowx XP but run on 2000.

–
Don Burn (MVP, Windows DDK)
Windows 2k/XP/2k3 Filesystem and Driver Consulting
Remove StopSpam from the email to reply

“Misha Karpin” wrote in message
news:xxxxx@ntdev…
> On WDK “Building a Multiversion Driver Using Version-Dependent Features”
> section, I read:
>
> “Conditionally Calling DDIs Based on Windows Version
> After a driver determines that a given DDI version is available on the
> computer that it is running on, that driver can dynamically locate the
> routine and call it through a pointer by using the
> MmGetSystemRoutineAddress function. This function was introduced in
> Windows 2000 and is available on all Windows computers that the WDK
> supports.
>
> Note To help preserve type checking and prevent unintentional errors, you
> should create a typedef that mirrors the original function type.
>
> …
>
> typedef (* PAISQSL) (KeAcquireInStackQueuedSpinLock);
> PAISQSL AcquireInStackQueued = NULL;
>
> Note that the C language syntax that the preceding typedef shows is a new,
> simplified, form of the following, more traditional, syntax.
>
> typedef void (FASTCALL * PAISQSL)(IN PKSPIN_LOCK Spinlock,
> IN PKLOCK_QUEUE_HANDLE LockHandle);
> PAISQSL AcquireInStackQueued = NULL;
> …
>
>
> The new syntax enables you to declare a pointer to a function without
> having to restate the calling convention or parameters of the function.
> This new syntax is supported by the compiler that is supplied with the
> Windows Server 2003 DDK.”
>
> Now the question. This multiversion driver with version-dependent features
> must be builded using
> the build environment for oldest O/S version, so how is possible to use
> this new syntax for this purpose when function prototypes are not exposed
> NEVER for the oldest target version in this scenario?.
>
> Thanks,
> mK
>
> _________________________________________________________________
> Express yourself instantly with MSN Messenger! Download today it’s FREE!
> http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/
>
>
>

Doron_Holan · March 1, 2006, 10:45am

You have to use the newest build env to make this work, otherwise, the
types are not present in the headers. By using the newest build env,
you must be extremely diligent to not include downlevel imports (types
are OK b/c they are self contained in your driver). This is how KMDF is
built btw.

d

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Misha Karpin
Sent: Wednesday, March 01, 2006 7:36 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] Building a Multiversion Driver Using Version-Dependent
Features

On WDK “Building a Multiversion Driver Using Version-Dependent Features”

section, I read:

"Conditionally Calling DDIs Based on Windows Version
After a driver determines that a given DDI version is available on the
computer that it is running on, that driver can dynamically locate the
routine and call it through a pointer by using the
MmGetSystemRoutineAddress
function. This function was introduced in Windows 2000 and is available
on
all Windows computers that the WDK supports.

Note To help preserve type checking and prevent unintentional errors,
you
should create a typedef that mirrors the original function type.

…

typedef (* PAISQSL) (KeAcquireInStackQueuedSpinLock);
PAISQSL AcquireInStackQueued = NULL;

Note that the C language syntax that the preceding typedef shows is a
new,
simplified, form of the following, more traditional, syntax.

typedef void (FASTCALL * PAISQSL)(IN PKSPIN_LOCK Spinlock,
IN PKLOCK_QUEUE_HANDLE LockHandle);
PAISQSL AcquireInStackQueued = NULL;
…

The new syntax enables you to declare a pointer to a function without
having
to restate the calling convention or parameters of the function. This
new
syntax is supported by the compiler that is supplied with the Windows
Server
2003 DDK."

Now the question. This multiversion driver with version-dependent
features
must be builded using
the build environment for oldest O/S version, so how is possible to use
this
new syntax for this purpose when function prototypes are not exposed
NEVER
for the oldest target version in this scenario?.

Thanks,
mK

Express yourself instantly with MSN Messenger! Download today it’s FREE!

http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/

Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

Misha_Karpin · March 1, 2006, 12:24pm

Using the newest build environment implies:

This Microsoft document is wrong:

http://download.microsoft.com/download/f/0/5/f05a42ce-575b-4c60-82d6-208d3754b2d6/WDK_BE-Refactoring.ppt

"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 "
Deprecated function warnings will be common for this type of drivers.
A very diligent work must be done in some situations. For example when a
driver is built using the Windows Vista Environment and it needs an older
structure definition like _FILE_OBJECT_WIN2K. This issue increments driver
complexity due to run time windows version checking, different code paths,
etc.
Magic and Spells is required: _WIN2K_COMPAT_SLIST_USAGE for example.

A new question. Is safe to use KeNumberProcessors variable in Windows 2000
when the driver is builded in XP or later environment?. I think the
environment “try to adapt legacy code”, so the output binary is different
using same code on different build environments.

Finally, let´s return to the last WDK, “Best Practices” about " Using
Versioned Header Files in Your Driver"

“Build drivers that you want to run on multiple Windows versions, but use
only a subset of available features, in the oldest Windows version build
environment (in the latest released version of the Driver Development Kit
[DDK] or WDK). For example, if your driver will run on all Windows versions
starting with Windows XP and it will use only features that are provided on
Windows XP, build your driver in the Windows XP build environment of the
WDK.”

“Build drivers that you want to run on multiple versions of Windows and
dynamically determine which features available for the driver to use in the
most recent operating system build environment. For example, if your driver
is designed to support all Windows versions starting with Windows 2000 but
you want the driver to use certain features that were first made available
in Windows XP when your driver is running on Windows XP or later operating
systems, build your driver in the Windows Vista build environment of the
WDK.”

That is, I have a driver that I want to run on multiple versions of Windows
starting from Windows 2000 and dynamically determine additional features to
use on Windows 2003. Then, I build the driver using the Windows Vista
environment. If I forget to use these WS03 additional features, then I have
the opposite to the DDK established rule: use always the oldest build
environment…

Thanks,
mK

Express yourself instantly with MSN Messenger! Download today it’s FREE!
http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/

Doron_Holan · March 1, 2006, 1:33pm

I forwarded your very good feedback to the WDK folks, hopefully they can resolve some of the issues you bring up.

d

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of Misha Karpin
Sent: Wednesday, March 01, 2006 9:24 AM
To: Windows System Software Devs Interest List
Subject: RE: [ntdev] Building a Multiversion Driver Using Version-Dependent Features

Using the newest build environment implies:

This Microsoft document is wrong:

http://download.microsoft.com/download/f/0/5/f05a42ce-575b-4c60-82d6-208d3754b2d6/WDK_BE-Refactoring.ppt

"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 "
Deprecated function warnings will be common for this type of drivers.
A very diligent work must be done in some situations. For example when a
driver is built using the Windows Vista Environment and it needs an older
structure definition like _FILE_OBJECT_WIN2K. This issue increments driver
complexity due to run time windows version checking, different code paths,
etc.
Magic and Spells is required: _WIN2K_COMPAT_SLIST_USAGE for example.

A new question. Is safe to use KeNumberProcessors variable in Windows 2000
when the driver is builded in XP or later environment?. I think the
environment “try to adapt legacy code”, so the output binary is different
using same code on different build environments.

Finally, let?s return to the last WDK, “Best Practices” about " Using
Versioned Header Files in Your Driver"

“Build drivers that you want to run on multiple Windows versions, but use
only a subset of available features, in the oldest Windows version build
environment (in the latest released version of the Driver Development Kit
[DDK] or WDK). For example, if your driver will run on all Windows versions
starting with Windows XP and it will use only features that are provided on
Windows XP, build your driver in the Windows XP build environment of the
WDK.”

“Build drivers that you want to run on multiple versions of Windows and
dynamically determine which features available for the driver to use in the
most recent operating system build environment. For example, if your driver
is designed to support all Windows versions starting with Windows 2000 but
you want the driver to use certain features that were first made available
in Windows XP when your driver is running on Windows XP or later operating
systems, build your driver in the Windows Vista build environment of the
WDK.”

That is, I have a driver that I want to run on multiple versions of Windows
starting from Windows 2000 and dynamically determine additional features to
use on Windows 2003. Then, I build the driver using the Windows Vista
environment. If I forget to use these WS03 additional features, then I have
the opposite to the DDK established rule: use always the oldest build
environment…

Thanks,
mK

Express yourself instantly with MSN Messenger! Download today it’s FREE!
http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/

Questions? First check the Kernel Driver FAQ at http://www.osronline.com/article.cfm?id=256

To unsubscribe, visit the List Server section of OSR Online at http://www.osronline.com/page.cfm?name=ListServer

OSR_Community_User · March 4, 2006, 7:41pm

“Misha Karpin” wrote in message news:xxxxx@ntdev…
…
> That is, I have a driver that I want to run on multiple versions of Windows starting from Windows 2000 and dynamically
> determine additional features to use on Windows 2003. Then, I build the driver using the Windows Vista environment. If I
> forget to use these WS03 additional features, then I have the opposite to the DDK established rule: use always the oldest
> build environment…

Having one binary for multiple OS versions has IMHO too little value to bother.
Though single binary drivers are possible, often they are not worth the effort,
but instead increase cost of support.
Sometimes marketing insists on a single binary, and developers
have to surrender to brute force

Consider the following:
- Single binary does not improve user experience - because users are not
supposed to look at driver files. A properly made setup package automatically
installs the correct binary.
- The effort needed to design runtime version checking code can be better put into testing.
- You don’t want a driver ro run on a future OS versions because you haven’t tested there yet.
Hoping that this will just happen by itself, is wishful thinking.
- After you change a single binary driver to support a new OS, you must retest everywhere.
- And if all above isn’t convincing enough… ask them to imagine a single binary for x86 and x64.

Regards,
–PA

Misha_Karpin · March 5, 2006, 6:59am

Actually I do not need to build a multi-version driver. I need to clarify
which is the Microsoft recommendation to do that, as IMHO the WDK
documentation is not right at this point.

On the other hand, you are right in all those points except that I do not
know why any developer would not want to run on future OS versions without
an explicit reason. It is a desirable feature to support OS upgrade scenario
without product reinstallation/upgrade. Other case of course is when the
driver performs actions that are risky in an untested OS, like for example a
defragmenter.

Thanks,
mK

Express yourself instantly with MSN Messenger! Download today it’s FREE!
http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/

OSR_Community_User · March 5, 2006, 11:32pm

I’ve been thinking about this and I think that maybe the term “build
environment” is being used for two different things. I think what is
needed is to use the latest version of the DDK/WDK (currently the newest
release version is for w2k3 sp1) but use the build environment for the
earliest version you need to support (win2k for example) from that
newest version of the DDK.

Beverly

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Misha Karpin
Sent: Sunday, March 05, 2006 6:59 AM
To: Windows System Software Devs Interest List
Subject: RE: [ntdev] Building a Multiversion Driver Using
Version-Dependent Features

Actually I do not need to build a multi-version driver. I need to
clarify
which is the Microsoft recommendation to do that, as IMHO the WDK
documentation is not right at this point.

On the other hand, you are right in all those points except that I do
not
know why any developer would not want to run on future OS versions
without
an explicit reason. It is a desirable feature to support OS upgrade
scenario
without product reinstallation/upgrade. Other case of course is when the

driver performs actions that are risky in an untested OS, like for
example a
defragmenter.

Thanks,
mK

Express yourself instantly with MSN Messenger! Download today it’s FREE!

http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/

Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer