Getting Started with the Windows Research Kernel (WRK)
Version 1.23 – Thursday April 23, 2009
Marty Humphrey, Associate Professor, Department of Computer Science, University of Virginia
Brian Burns, Program Manager, Microsoft
Serge Lidin, Software Design Engineer, Microsoft
The purpose of this document is to illustrate how to compile, modify, and use the Windows Research
Kernel (WRK). The basic idea is that you will edit and recompile the WRK on a Windows computer, and
then run it on a virtual machine running Windows Server 2003. The virtual machine will run in the
Virtual PC 2007 environment, which in turn runs under the host Windows OS. The host OS may be
Windows Server 2003 or later, or Windows XP or later. This document contains the steps you can take to
install everything you need to edit, compile, and run the WRK. The final section of this document
describes how to modify the WRK source code, recompile your kernel, and confirm that your changes are
executed by attaching a kernel debugger to the virtual machine. Throughout this document, there are nine
self-study questions.
The intended audience of this document are new users to the WRK with limited knowledge of the
Windows operating system. No special knowledge of operating system design and/or implementation is
necessary to perform the steps in this document. Editing the WRK can be accomplished by any text editor,
and compilation of the WRK utilizes the nmake utility that is installed with the WRK sources.
General Information
1. You will need to work rather extensively with the console (Windows Command Prompt)
windows. To start a fresh console window, use selections (Start  All Programs  Accessories
 Command Prompt) OR (Start  Run), then type “cmd” and click OK or press Enter.
2. To execute a command in the console window, type this command and press Enter.
3. There are four components you need to have installed on your machine: Windows Debugger,
Virtual PC 2007, virtual machine image of Windows Server 2003 SP1 (with virtual hard drive
image), and the WRK itself including source code, tools and binaries. Installation of virtual
machine with its hard drive image and of WRK boils down to simple copying them to specified
directories.
4. You can install all the components separately from respective entries on the DVD or you can
install everything using file WRKCompleteInstall.bat residing in the root of the DVD.
Working with WRKCompleteInstall.bat
The WRKCompleteInstall.bat takes four parameters specifying destination directories of the
components being installed:
/i <virtual_machine_directory>
/w <WRK_directory>
/d <debugger_directory>
/v <Virtual_PC_directory>
1
The default destination directories are as follows:
WRK:
C:\WRK-v1.2\
Virtual machine:
C:\WRK-v1.2\Win2k3SP1 Image\
Debugger:
C:\Program Files\Debugging Tools for Windows\
Virtual PC:
C:\Program Files\Microsoft Virtual PC\
If you don’t mind the components to be installed to their default destinations, invoke
WRKCompleteInstall.bat without parameters by opening Windows Explorer (double-click on
“Computer” icon on your desktop), selecting the DVD drive, and double-clicking on
WRKCompleteInstall.bat entry.
Alternatively, you can run WRKCompleteInstall.bat from a console window, with or without
parameters:
1. Open Windows Explorer and find out what is the letter of your DVD drive (let it be, say, F).
2. Open console window, type F: and press Enter; you have switched to your DVD drive.
3. Now type WRKCompleteInstall and press Enter to install the components to default
destinations
4. OR specify the destinations, for example:
WRKCompleteInstall /i C:\WRK_VM /w C:\WRK /d C:\WinDbg /v C:\VPC
If the full name (path) of a destination directory contains space symbol, the whole path should be
enclosed in double quotes, for example: /d “C:\Program Files\WinDbg”
The destination directories should not yet exist on your drive. If the batch file detects that a destination
directory already exists, it skips installation of respective component.
This is done to enable the batch file to perform partial installations. For example, if you already have
Virtual PC 2007 installed on your computer, specify its installation directory in /v parameter, and
installation of Virtual PC 2007 will be skipped.
Copying WRK Separately
To copy the WRK (presuming you have the other three components already installed) to your machine,
follow these steps:
- open a console window;
- switch to DVD drive;
- execute command cd \Resources\Windows_Research_Kernel\Get_WRK
- execute command WRKCopy /w <destination_directory>
(if you run WRKCopy.bat without parameters, WRK will be copied to C:\WRK-v1.2\);
ALTERNATIVELY
- open Windows Explorer;
- create the destination directory on your hard drive;
- switch to DVD drive;
- navigate to \Resources\Windows_Research_Kernel\Get_WRK\WRK-v1.2\;
- select all files and subdirectories, drag and drop them to the destination directory.
2
Exercise #1: Building the WRK
Windows Research Kernel can be built from Visual Studio 2008 environment or from a console window.
To build WRK from command line:
- open console window;
- switch to the directory WRK was copied to (for example, cd \WRK-v1.2);
- execute Build <arch> (or Rebuild <arch> or Clean <arch>), see note about <arch>
below;
OR
- open console window;
- switch to the directory WRK was copied to;
- execute WRKEnv <arch>, see note about <arch> below;
- execute cd base\ntos
- execute nmake %wrkarch%=
To build WRK in VS2008 environment:
- start VS2008;
- open solution <WRK_DIR>\WRK.sln, where <WRK_DIR> is the directory WRK was copied to;
- make sure the Configuration is amd64/Win32 or x86/Win32, as is appropriate;
- select Build/Build Solution (or Rebuild Solution, or Clean Solution).
NOTE: don’t start the build before looking at question #Q-1, below!
The built kernel is located in c:\WRK-v1.2\base\ntos\BUILD\EXE as wrkx86.exe .
NOTE ABOUT <arch>
Batch files Build.bat, Rebuild.bat, Clean.bat, WRKEnv.bat and WRKDebug.bat take one
parameter – target architecture, which is x86 or amd64.
For the first use of either of these batch files, default target architecture is x86.
Once the target architecture was defined (explicitly or by default), it cannot be changed for current
console window, and <arch> parameter of the batch files is ignored.
The title of the window where the WRK environment has been set to some target architecture changes to
“WRK x86” or “WRK amd64”.
To work with different target architecture, open another console window.
Questions for this exercise:
Q-1. How long did it take to compile your kernel the first time? If you run the same command a
second time (step #5, above), how long does it take? (It is sufficient in this case to “eye-ball” it –
‘seconds’ resolution is fine).
3
Exercise #2: Running Windows Server 2003 inside Virtual PC 2007
1. A fully configured Virtual PC 2007 virtual machine has been provided on this DVD for you to run the
WRK. If the default installation options were used, it is located in the directory
C:\WRK-v1.2\Win2k3SP1 Image\
2. Start Virtual PC 2007 (Start  All Programs  Microsoft Virtual PC). This will start the “New
Virtual Machine Wizard”:
a. “Add an existing virtual machine”
b. Browse to c:\WRK-v1.2\Win2k3SP1 Image\ (or whatever directory you chose with
WRKCompleteInstall.bat) and choose the file “Win2k3 SP1 WRK.vmc”
c. Click Next  Finish, making sure the “When I click Finish, open Settings” box is checked.
3. The settings windows for “Win2k3 SP1 WRK” should now be open. Please note the following:
a. “Undo Disks” is disabled. Any changes you make to the virtual machine will be written to the
hard disk. If you want the option of throwing out any changes you make when you turn off
the virtual machine, enable this option.
b. The named pipe \\.\pipe\debug is configured on COM1. This allows WinDbg to connect to
the WRK within the Virtual PC 2007 environment.
c. “Virtual Machine Additions” are installed, enabling “pointer integration”. “Virtual Machine
Additions” allow a tighter connection between the host machine and the Virtual Machine (for
example, the performance of the virtual machine will be better, you can resize the Virtual
Machine window, and you will be able to drag-and-drop from the physical machine to the
virtual machine).
i. Note: upon rebooting the Virtual Machine, the way to get “Ctrl-Alt-Delete” to the
Virtual Machine is via the Virtual Machine’s “Action” menu.
d. The “Shared Folder” c:\  z:\ is enabled. This option maps the c:\ root directory on the host
machine to the z:\ drive on the virtual machine for easy file sharing between the systems.
4. Start the “Win2k3 SP1 WRK” virtual machine from within the Virtual PC Console window.
5. At the boot prompt, select “Windows Server 2003, Standard”. This option boots the original
Windows Server 2003 SP1 kernel. The other options boot the WRK with and without debugging
enabled.
a. Note: To help people keep track of kernel versions being run, the virtual machine desktop
wallpaper has been preconfigured to show the kernel build number.
6. The virtual machine has been preconfigured to automatically login to the administrator account
without user interaction. If you prefer to use another account or require user login, please use the
information provided in SetAutoAdministratorLogon.zip on the virtual machine desktop to modify
this behavior.
7. Give your physical machine a name unique to you to prevent any domain naming conflicts.
a. Right click on My Computer  Properties Computer Name Change
b. You can also add the virtual machine to a domain if you wish. It is preconfigured to be part of
the generic workgroup “WORKGROUP”
8. Note: Windows update is turned “off” to prevent SP2 from being installed in the virtual machine. SP2
is not compatible with the WRK at this time and installing SP2 into the virtual machine can only be
reversed if the “Undo Disks” setting is enabled.
Questions for this exercise:
Q-2. How big is the physical file that contains your virtual disk? (Right click on the .vhd file and get
“Properties” – not the .vmc file)
4
Exercise #3: Monitor the invocation of “QuerySystemInformation”
In this portion of the lab you will modify the WRK kernel to print out some debugging information to
keep track of the number of times “QuerySystemInformation” is invoked (sometimes a developer may
wish the kernel is “instrumented” this way for performance purposes – for example, if we find that this
function is invoked A LOT, then this function is a reasonable candidate for performance optimization,
right?)
1. In this first step, we’ll confirm that you can attach a debugger to the kernel (we won’t actually modify
the kernel until the next step). Follow the instructions at http://support.microsoft.com/kb/871171/ to
attach the kernel debugger to your Virtual Machine (Note that this works for Virtual PC 2007 as well
– follow the instructions for Virtual PC 2004). Here is some additional information:
a. Start your WRK Virtual Machine if it’s not already running and at the boot prompt, chose the
“Windows Server 2003 SP1, WRK [debugger enabled]” option.
b. Your virtual machine should sit idle while it waits for the Windows Debugger (WinDbg) to
connect.
c. Open a console window on the host machine and start the Windows Debugger:
- switch to the directory WRK was copied to;
- execute WRKDebug <arch> (see note about <arch> in Exercise #1);
OR
- switch to the directory WRK was copied to;
- execute WRKEnv <arch> (see note about <arch> in Exercise #1);
- execute WinDbg %windbgargs%
d. During the booting activity, you should see a few lines of text on your “WinDbg” window
(probably beginning with “Connected to Windows Server 2003 3790 x86 compatible target,
ptr64 FALSE”). If not, then re-try, making sure that you selected the debugging kernel to be
booted.
i. Note: In order to connect to the kernel from WinDbg, you may have to click Debug
 Break in the WinDbg window.
e. Once this works, go onto the next step without shutting down your Virtual Machine or your
windbdg.exe window. You’ll know it works if you see this info in the debugging window and
you’re able to log onto your WRK Virtual Machine.
2. Now we will modify the kernel, install it on the Virtual Machine, boot the modified kernel, and see
the output on the debugging window. We’ll start by modifying and recompiling our kernel on the
physical machine:
a. Open a text editor of your choice and edit C:/WRK-v1.2/base/ntos/ex/sysinfo.c
b. Get to line 1721 and insert the following line:
static int NumTimesCalled = 0;
c. Shortly after this (immediately before the line “Status = STATUS_SUCCESS”), add the
following line:
DbgPrint( “WRK %d: Entering NTQuerySystemInformation!!!\n”,++NumTimesCalled );
d. Save the file and recompile the kernel as above (Exercise #2) 1
3. Drag-and-drop your new kernel onto the Virtual Machine’s Administrator’s “My Documents” folder
(the new kernel will be on the physical machine in C:\WRK-v1.2\base\ntos\BUILD\EXE, with the
1
We recommend you make a backup copy of this file before saving the modified version.
5
name wrkx86.exe). Once you have moved it to the Virtual Machine, copy this file on the Virtual
Machine to C:\WINDOWS\system32\
a. The virtual machine has been preconfigured to boot the WRK and already contains the file
wrkx86.exe in C:\WINDOWS\System32. We recommend you back up this file before
copying over it with the modified kernel. When this file is copied over, the WRK boot
options in the virtual machine will both point to the new kernel.
4. Reboot the Virtual Machine via Start  Shutdown  Restart. Select the “Windows Server 2003 SP1,
WRK [debugger enabled]” boot option and watch the output on the debugging window.
a. Note: you’ll probably have to select the debugger window, which may be hidden, and select
“no” to the question “Save information for workspace?”)
5. If everything is working, you should start seeing something like:
WRK 82: Entering NTQuerySystemInformation!!!
WRK 83: Entering NTQuerySystemInformation!!!
WRK 84: Entering NTQuerySystemInformation!!!
If you’re not seeing this, then go back through the instructions to see if you’ve missed something.
Note: if your new kernel does not boot, then you can reboot into the “Windows Server 2003,
Standard” boot kernel.
Questions for this exercise:
Q-3. How many times is this function invoked up until right before the Windows login banner appears,
right after the WRK Virtual Machine has fully booted?
Q-4. Show a small section of the output of the invocation of your debugging statement. To do this, first
select the Debugging window and then hit Alt-PrtSc (“print screen”). This will put a copy of the
window into the edit buffer, which you can then get at (say in Microsoft Office) via Edit  paste.
Q-5. Once you’ve completed that, and closed your Virtual Machine and debugging window, how big is
the physical file that contains your virtual disk now? Why is this? (I.e., why is it the same, or why has
it changed?)
That’s it! You have successfully modified the Windows Research Kernel and observed your change in
action. By following this basic procedure, you are now able to explore all kinds of kernel modifications
and subsequently test the effect of such changes. Our general advice: Always keep a “safe” copy of a
kernel bootable via C:\boot.ini – this will allow you to easily revert to a known safe state. Have fun!
6