.kdfiles (Set Driver Replacement Map)

Article
10/25/2023

The .kdfiles command reads a file and uses its contents as the driver replacement map.

.kdfiles MapFile
.kdfiles -m OldDriver NewDriver
.kdfiles -s SaveFile
.kdfiles -c
.kdfiles

Parameters

MapFile
Specifies the driver replacement map file to read.

-m
Adds a driver replacement association to the current association list.

OldDriver
Specifies the path and file name of the previous driver on the target computer. The syntax for OldDriver is the same as that of the first line after map in a driver replacement file. For more information about this syntax, see Mapping Driver Files.

NewDriver
Specifies the path and file name of the new driver. This driver can be on the host computer or at some other network location. The syntax for NewDriver is the same as that of the second line after map in a driver replacement file. For more information about this syntax, see Mapping Driver Files.

-s
Creates a file and writes the current driver replacement associations to that file.

SaveFile
Specifies the name of the file to create.

-c
Deletes the existing driver replacement map. (This option does not alter the map file itself. Instead, this option clears the debugger's current map settings.)

Environment

Modes	Kernel mode only
Targets	Live debugging only
Platforms	x86-based processors

Additional Information

For more information about and examples of driver replacement and the replacement of other kernel-mode modules, a description of the format for driver replacement map files, and restrictions for using this feature, see Mapping Driver Files.

Remarks

If you use the .kdfiles command without parameters, the debugger displays the path and name of the current driver replacement map file and the current set of replacement associations.

When you run this command, the specified MapFilefile is read. If the file is not found or if it does not contain text in the proper format, the debugger displays a message that states, "Unable to load file associations".

If the specified file is in the correct driver replacement map file format, the debugger loads the file's contents and uses them as the driver replacement map. This map remains until you exit the debugger, or until you issue another .kdfiles command.

After the file has been read, the driver replacement map is not affected by subsequent changes to the file (unless these changes are followed by another .kdfiles command).

User Mode File Replacement

User Mode File Replacement was added in version 2004 of Windows. This support enables the following user mode files to be replaced with .kdfiles.

User mode DLLs (also including NTDLL and KnownDlls)
User mode EXEs that are a main process image for CreateProcess

To use user mode .kdfiles support, you need to first enable kernel symbol loading using the !gflag +ksl debugger command or configure the ksl global flags in the registry. For more information about gflag, see !gflag.

The following examples illustrate common usage.

.kdfiles -m system32\userdll C:\myfiles\my_native_userdll.dll
.kdfiles -m system32\userdll \\server\share\my_native_userdll.dll
.kdfiles -m syswow64\ntdll.dll \\server\share\my_x86_wow64_ntdll.dll
.kdfiles -m system32\userbase.dll \\server\share\my_native_userbase.dll

User mode .kdfiles ignores any failures to match a file and does not display an error message when a failure occurs.

Be careful to appropriately qualify the .kdfiles paths for user mode .kdfiles. It is a bad idea to just match ntdll.dll (instead of system32\ntdll.dll) as otherwise the Wow64 NTDLL will get replaced with the native one. Similar situations can arise with other ambiguous substring matches.

After build 20172, the user mode .kdfiles mechanism will attempt to pull files from the debugger until one attempt fails; then, the file name that failed to be pulled will not be tried again for the boot session, without manual intervention from the debugger to modify the target system state. On earlier builds, the user mode .kdfiles mechanism will make one attempt (whether successful or not) to pull a given file name per boot session. These policies reduce the overhead of communicating with the debugger for files that are not in the kdfiles list, or that are inaccessible for replacement, such as due to sharing violations from processes that may have already loaded a given file. Because of this behavior, it is generally advisable to configure any files to pull in the .kdfiles list up front, before they would first be referenced.

Be aware of limitations with being unable to replace already in use disk files, etc. As many system DLLs are won’t be easily hot swappable after they have been loaded up initially, preset the gflags +ksl option and use .kdfiles to replace any user mode binaries right at boot.

For more information about enabling boot debugging, see BCDEdit /bootdebug.

The use of the high speed/low latency KD transport KDNET is recommended to minimize system performance impacts.

Requirements

Version

Supported in Windows XP and later versions of the Windows operating system.

Share via