[DefaultInstall] decorated with architecture + OS version

NTFSD
1

According to the "MiniSpy" sample driver project's .inf file:

It is possible to decorate the [DefaultInstall] section with both the architecture and the OS version. This is ostensibly being done to handle how the registry entries for "Instances" needs to be nested under "Parameters" on newer builds of Windows (Windows 11 22H2 & newer), while it is nested directly under the service's registry key in down-level builds of Windows.

These are the operative parts of the .inf file:

[DefaultInstall.NT$ARCH$.10.0...25952]
OptionDesc = %ServiceDescription%
CopyFiles = Minispy.Files,

[DefaultInstall.NT$ARCH$.10.0...25952.Services]
AddService = %ServiceName%,,Minispy.Service

[DefaultInstall.NT$ARCH$]
OptionDesc = %ServiceDescription%
CopyFiles = MinispyDownlevel.CopyDriverFiles

[DefaultInstall.NT$ARCH$.Services]
AddService = %ServiceName%,,MinispyDownlevel.Service

[DefaultUninstall.NT$ARCH$]
LegacyUninstall = 1
DelFiles = MinispyDownlevel.DelDriverFiles

If I use "NT$ARCH$" as the architecture decoration instead of "NTAMD64" and "NTARM64", the .inf file in my driver project doesn't pass the Inf Verify tests during a build in VS2022.

If I do use "NTAMD64" and "NTARM64" with the desired OS version information as the decoration suffix, then it passes the verification during build but when the driver installs, the OS version decoration appears to be ignored and the "downlevel" sections with architecture but without OS version seem to be what's being used based on the registry entries being created. Snippets from my .inf file are as follows:

[DefaultInstall.NTAMD64.10.0...22621]
CopyFiles = MiniFilter.Files

[DefaultInstall.NTAMD64.10.0...22621.Services]
AddService = %Service.Name%,,MiniFilter.Service

[DefaultInstall.NTARM64.10.0...22621]
CopyFiles = MiniFilter.Files

[DefaultInstall.NTARM64.10.0...22621.Services]
AddService = %Service.Name%,,MiniFilter.Service

[DefaultInstall.NTAMD64]
CopyFiles = MiniFilterPre22621.Files

[DefaultUninstall.NTAMD64]
LegacyUninstall = 1

[DefaultInstall.NTAMD64.Services]
AddService = %Service.Name%,,MiniFilterPre22621.Service

[DefaultInstall.NTARM64]
CopyFiles = MiniFilterPre22621.Files

[DefaultUninstall.NTARM64]
LegacyUninstall = 1

[DefaultInstall.NTARM64.Services]
AddService = %Service.Name%,,MiniFilterPre22621.Service

Windows 10.0.22621 is the build number for Windows 11 22H2, which is where the difference in registry key usage is documented by Microsoft, per the following:

Based on that documentation, I have one section which sets up the registry values as follows for 10.0.22621 & newer:

HKR,"Parameters","SupportedFeatures",0x00010001,%Driver.SupportedFeatures%
HKR,"Parameters\Instances","DefaultInstance",0x00000000,"%Driver.DefaultInstance.Name%"
HKR,"Parameters\Instances%Driver.DefaultInstance.Name%","Altitude",0x00000000,"%Driver.DefaultInstance.Altitude%"
HKR,"Parameters\Instances%Driver.DefaultInstance.Name%","Flags",0x00010001,%Driver.DefaultInstance.Flags%

And then for downlevel systems prior to 10.0.22621, I have the following section:

HKR,,"SupportedFeatures",0x00010001,%Driver.SupportedFeatures%
HKR,"Instances","DefaultInstance",0x00000000,"%Driver.DefaultInstance.Name%"
HKR,"Instances%Driver.DefaultInstance.Name%","Altitude",0x00000000,"%Driver.DefaultInstance.Altitude%"
HKR,"Instances%Driver.DefaultInstance.Name%","Flags",0x00010001,%Driver.DefaultInstance.Flags%

I've tested the installation using the .inf file on Windows 11 23H2 & 24H2, and in both cases, despite the OS build being greater than 10.0.22621, the OS version decoration is ignored during installation and the downlevel sections are used. I've verified that all of the relevant "AddReg" directives and the section names they refer to are correct.

I'm at a loss to explain why this isn't working as expected/documented, but I suspect there may be something very subtle missing/wrong. Also, the apparent "macro" substitution of "$ARCH$" doesn't appear to be working, either, and documentation regarding it is minimal.

2

The $ARCH$ token is resolved by running stampinf. This should be a default WDK build step but if it's disabled or not there for some reason (or maybe you're not building against a specific architecture?) then the tokens won't be resolved.

I think you misread, the registry key usage change is for 24H2. We don't support the build number forking prior to that for [DefaultInstall*] sections. I believe I checked in the support in build 25952 and that's why the samples reflect that, but 26100 is probably a better one to use.

3

Thanks for the response. Yes, you're correct, I misread the build "24H2" as "22H2" for some reason, so that explains why I came up with build 10.0.22621 instead of 10.0.26100. I suspect that the 10.0.25952 build number comes from an interim build number that was only present on pre-release builds available through the various update channels that are part of the Windows Insiders program. I'll update my .inf file accordingly and use 10.0.26100.

What's not clear, though, is even with using build 10.0.22621 (Windows 11 22H2) in the OS version decoration, and installing the driver on Windows 11 23H2 (10.0.22631), the "Instances" key is getting created directly under HKR, instead of the "Parameters" subkey under HKR. Is there some possibility that the registry keys are in some way being filtered during driver installation on Windows 11 23H2 & earlier so that HKR,"Parameters\Instances" becomes HKR,"Instances"? I understand that using the 24H2 registry key structure on a 23H2 system would cause the mini-filter driver to not load properly, but what's concerning is that keys are not being created as specified in the .inf file for the build of Windows that the driver is being installed on.

I double-checked the "StampInfo -> General" settings, and "Enable Architecture" is set to "Yes" and "Architecture" is set to "$(InfArch)".

image
image538×283 9.77 KB

It's not an issue for me to keep the explicit architecture decorations present until I work out why "$ARCH$" isn't being replaced with the actual architecture value.

4

I checked in the code that read those OS version decorations right around build 25952, so if you're running a build prior to that there's no code in the OS that is attempting to read those sections at all - it will only look at the sections without the build number in that case, which is what you're seeing

5

You explanation of what's going on definitely makes sense, and I think it's calling out a problem with Microsoft's documentation which leads to an incorrect conclusion being reached.

Regarding the registry entries related to the "Parameters" subkey under HKR for the driver service for a mini-filter on Windows 11 (and Windows Server 2025) 24H2:

"The following values should be under the Parameters subkey starting with Windows 11 version 24H2."

That lead me to look for device driver sample projects where the .inf file includes OS version decoration for the [DefaultInstall] section. Thus, I was looking at MiniSpy and several other of its siblings, all of which had an identical OS version decoration.

Further investigation of OS version decoration, including a mandatory OS architecture decoration, lead me to the following:

And, in that topic, although it's for the INF Manufacturer Section, it leads to the following text:

"As indicated on Creating INF Files for Multiple Platforms and Operating Systems, platform extension decorations are required for INF Models sections, but there are other sections where they are optional. Whether or not platform extension decorations are used on these sections where it is optional generally depends on if the INF is attempting to support different platforms or not and if the installation instructions (including the exact files to copy) are the same on each platform."

From that point, lacking access to the source code for SetupAPI.dll (or whatever other functions it calls in other DLLs), what is now an obviously wrong inference is made regarding how OS version decorations will be applied to the [DefaultInstall] section. There is absolutely nothing in the documentation to make a clear delineation between the manufacturer's section and the default install section as it relates to how OS version decoration is observed by the program code which processes the .inf file and performs the driver installation.

I'll continue with updating my .inf file to target 10.0.26100 for the default install section which addresses the change specific to Windows 11 24H2, and then leave the other OS version unqualified sections to handle down-level systems.

Of course, this begs another question. What happens if a down-level installation of a file system mini-filter driver performed on Windows 11 23H2 or older is made and then that system is upgraded to Windows 11 24H2 (or newer)? Will the feature update being applied also modify the registry entries for existing mini-filter drivers? Or, will the Filter Manager look for "Parameters\Instances", and finding is missing, fall back to looking for "Instances", all of which are relative to HKR from the device driver's point of view? I don't want to speculate on the train wreck that follows if Microsoft hasn't already implemented a graceful fallback for handling the upgrade scenario.