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 hostWindows 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 thesteps 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
- 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.
- To execute a command in the console window, type this command and press Enter.
- 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.
- 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>
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.batentry.
Alternatively, you can run WRKCompleteInstall.batfrom a console window, with or without parameters:
- Open Windows Explorer and find out what is the letter of your DVD drive (let it be, say, F).
- Open console window, type F: and press Enter; you have switched to your DVD drive.
- Now type WRKCompleteInstall and press Enter to install the components to default destinations
- 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 commandWRKCopy /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.
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);
- executeBuild <arch> (or Rebuild <arch> or Clean <arch>), see note about <arch> below;
OR
- open console window;
- switch to the directory WRK was copied to;
- executeWRKEnv <arch>, see note about <arch> below;
- execute cdbase\ntos
- executenmake %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).
Exercise #2: Running Windows Server 2003 inside Virtual PC 2007
- 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\ - Start Virtual PC 2007 (Start All Programs Microsoft Virtual PC). This will start the “New Virtual Machine Wizard”:
- “Add an existing virtual machine”
- Browse to c:\WRK-v1.2\Win2k3SP1 Image\ (or whatever directory you chose with WRKCompleteInstall.bat) and choose the file “Win2k3 SP1 WRK.vmc”
- Click Next Finish, making sure the “When I click Finish, open Settings” box is checked.
- The settings windows for “Win2k3 SP1 WRK” should now be open. Please note the following:
- “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.
- The named pipe \\.\pipe\debug is configured on COM1. This allows WinDbg to connect to the WRK within the Virtual PC 2007 environment.
- “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).
- 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.
- 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.
- Start the “Win2k3 SP1 WRK” virtual machine from within the Virtual PC Console window.
- 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.
- 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.
- 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.
- Give your physical machine a name unique to you to prevent any domain naming conflicts.
- Right click on My Computer Properties Computer Name Change
- You can also add the virtual machine to a domain if you wish. It is preconfigured to be part of the generic workgroup “WORKGROUP”
- 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” – notthe .vmc file)
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?)
- 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 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;
- executeWRKEnv <arch>(see note about <arch>in Exercise #1);
- executeWinDbg %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.
- 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.
- 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]
- 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 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.
- 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?”)
- 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!
1
[1] We recommend you make a backup copy of this file before saving the modified version.