Installing, modifying, compiling and debugging the Windows WRK kernel

1. Installing, modifying, compiling and debugging the Windows WRK kernel Practical session #1 バリ　ゲローフィ Advanced operating systems course, The University of Tokyo

2. Introduction • Please call me バリ! • not 先生:) • I am a PhD student • The Windows Kernel is big and difficult, let’s try to find our way together!

3. Outline • Installing the Windows WRK environment • Setting up the Virtual machine (VM) • Contents of the VM • Compiling the kernel source • Deploying the new kernel • Setting up and using the debugger • Modifying the kernel • Comments, using cscope + vim

4. Please copy the flash disk!Or download and uncompress:http://tinyurl.com/yju5xu3http://www.il.is.s.u-tokyo.ac.jp/~bgerofi/WindowsWRKInstall.tar

5. What kind of text editor are u guys using? • Vim ???

6. WRK directory contents • Docs and Examples - WRK build instructions and documentation • Virtual PC 2007 - setup for Virtual PC 2007 • Win2k3SP1 Image - preconfigured Windows Server 2003 SP1 image • WinDbg - setup for the Windows Debugging Tools • WRK-v1.2 - NTOS kernel source code and build environment for the kernel • WindowsInternalsBook4thEdition - Textbook

7. Installing the WRK environment • Open cmd window (Run as Administrator!) • Go to WindowsWRKInstall directory and run WRKInstall.bat, installs: • VirtualPC 2007 • WRK source tree • Debugger • Win2k3 SP1 VM image prepared for you

8. Setting up the virtual machine • Run: Programs -> Microsoft Virtual PC 1.) choose: “Add an existing virtual machine” 2.) Browse to C:\WRK-v1.2\Win2k3SP1 Image\Win2k3 SP1 WRK.vmc 3.) Click Next 4.) Start up the virtual machine

9. Boot menu entries • Windows Server 2003, Standard - you can use this always to boot up your machine and copy a new kernel image in case something went wrong with your own kernel • Windows Server 2003, WRK [debugger enabled] – your kernel with debugger • Windows Server 2003, WRK – No Debugger – your kernel without debugger • Choose the Standard for now!

10. What is in the VM? You have: • Visual Studio.NET 2003 for writing your user space applications in the VM (you can also do it on your own computer…) • Process Explorer - a Windows Sysinternals tool for examining your processes, shows: • Open handles, DLLs • Page faults, working set size, threads • a lot more… • Total Commander – file manager • Preconfigured to log in as administrator • Z: mapped to your host computer’s C:

11. Compiling the kernel source 1.) Open a command window 2.) Go to C:\WRK-v1.2\base\ntos 3.) Execute: nmake x86= • For the first time, you may not have MSVCR71.dll and/or MSVCP71.dll • copy them from the install directory’s DLL folder to C:\WRK-v1.2\tools\x86 4.) New kernel will be generated here: C:\WRK-v1.2\base\ntos\BUILD\EXE\wrkx86.exe

12. http://kedl.undergorund.hu/03.pptx

13. Deploying your own kernel image 1.) Boot up the Virtual machine • Choose Standard from the boot menu 2.) Copy wrkx86.exe from Z:\WRK-v1.2\base\ntos\BUILD\EXE\ (this is your local computer’s folder) to C:\WINDOWS\system32\ (this is a folder in the VM) • IMPORTANT: Never forget to copy the image after you recompiled the kernel!

14. Setting up the debugger SHUT DOWN YOUR VM FIRST! 1.) In the VirtualPC -> Settings -> COM1, set to named pipe: \\.\pipe\debug 2.) Start debugger: WRKDebug.bat (in WindowsWRKInstall folder) executes: “C:\Program Files\Debugging Tools for Windows\windbg.exe” –k com:port=\\.\pipe\debug,pipe,resets=0,reconnect 3.) Change the following settings: Symbol file path: C:\WRK-v1.2\base\ntos\BUILD\EXE (Symbol file holds variable, function names and offsets in the binary, similar to System.map in Linux) Source file path: C:\WRK-v1.2\base\ntos Image file path: C:\WRK-v1.2\base\ntos\BUILD\EXE

15. Who could set up the debugger ???

16. Using the debugger • Always start the debugger first and then the VM • After booting, choose: Windows Server 2003, WRK [debugger enabled] • Things you can do: • Break – suspend the execution and jump to the source • Go – continue execution • Run to cursor – execute until the cursor is reached in the source code (useful one!) • Step into/over/out – control the execution of functions • View local variables, view call stack

17. Example scenario • Open a command window in the VM • In the debugger open source file: c:\WRK-v1.2\base\ntos\ps\create.c • Go to the NtCreateProcessEx() function (gets called when you create a new process) • Debug -> Break, then Go to cursor at the beginning of the function • type “Notepad” into the command window • type !process in the debugger • Which process has been suspended?

18. Modifying the kernel source • Let’s print out in the debug window when a new process is created. • Open file: c:\WRK-v1.2\base\ntos\ps\create.c • Add this to the end of PspCreateProcess(), at line number 1748: DbgPrint("%s has been created by %s\n", (Process->ImageFileName ? Process->ImageFileName : "??"), (Parent ? Parent->ImageFileName : "the system")); • Recompile, deploy and boot your kernel with debugging on!

19. Output should be like this: …. svchost.exe has been created by services.exe svchost.exe has been created by services.exe svchost.exe has been created by services.exe spoolsv.exe has been created by services.exe msdtc.exe has been created by services.exe mpnotify.exe has been created by winlogon.exe userinit.exe has been created by winlogon.exe ….

20. cscope + vim – source code indexing tool • Why? • Makes it easier to explore a big codebase • Direct jump to definitions :cs f g “string” • Search calls :cs f s “string” • Search callers :cs f c “string” • cscope –kqRvb • Generates the index database

21. Final comments • Put the code into a version management system, SVN or git • Commit as often as you can • so that you can revert if something goes wrong • Preferably use branches for different features • Reference book: • Microsoft Windows Internals (4th Edition) by Mark E. Russinovich and David A. Solomon • Available in PDF: • WindowsWRKInstall\WindowsInternalsBook4thEdition\WindowsInternals-4e.pdf