{"id":69,"date":"2006-12-01T18:50:17","date_gmt":"2006-12-01T18:50:17","guid":{"rendered":"https:\/\/driverentry.com.br\/en\/2006\/12\/01\/step-into-kernel-serial\/"},"modified":"2026-07-24T19:02:59","modified_gmt":"2026-07-24T19:02:59","slug":"step-into-kernel-serial","status":"publish","type":"post","link":"https:\/\/driverentry.com.br\/en\/2006\/12\/01\/step-into-kernel-serial\/","title":{"rendered":"Step into Kernel (Serial)"},"content":{"rendered":"
\"\"<\/a><\/div>\n

I earned my first computer when I was 13 years-old, but seven years later, when I started my internship, I discovered that it was possible to debug programs that I used to write. Until then, my debug methods were always things like printing the variable value on screen. All right, in that time I didn’t use to develop complex\u00a0programs enough to be stuck; over the time, I think I got used to working without the luxury as break-points and so on.<\/p>\n

When I was introduced to a debugger, I even paid attention to it. I thought to myself: I can just put a printf<\/em> and I’ll be OK. I don’t need all this stuff. At that time, we used the CodeView<\/em>, a 16-bit debugger that runs on DOS which is displayed on the picture below.<\/p>\n

\"\"<\/div>\n

It didn’t take long for me starting to depend on the debugger doing the simplest things, like brushing my teeth, for example. In fact, some situations, such as writing code for data collectors, writing firmware for hardware that has no display, situations in which we could not count on a serial port to see what was happening with the software, and the unforgettable situation where I had placed an oscilloscope on a particular processor pin to catch our software life signs, so, situations that we would give an arm to have a simple break-point made me realize that the debugger is really necessary.<\/p>\n

The funny thing is that nowadays, in college, most students in my class don’t know how to debug software. I’ve tried to explain to my friends the tremendous advantage of using a debugger, but they end up having the same reaction I had years ago: “No way, Fernando, this is too complicated. Just by looking at the source code we end up finding the mistake”. So, that’s fine for me.<\/p>\n

Well, we’re here to debug or to talk? Let us debug the driver generated by the traditional post Getting Started<\/a>. This time we’ll do according to the tradition. We will need two machines, a Null Modem<\/em> serial cable and last but not least, a copy of WinDbg<\/strong>. No, not worth reading this sentence again, you didn’t take it wrongly; you’ll really need two machines. I don’t know why some people have a certain resistance to believe in this. Well, I think we have overcome that phase and we can continue with the post.<\/p>\n

If you do not have a copy of WinDbg, you can download it for free from the Windows Debugging Tools <\/a>page at Microsoft site.<\/p>\n

\"\"<\/p>\n

Let’s take this picture borrowed from the Windbg Help, which shows how we should set computers to do Kernel debug.<\/p>\n

The machine named HOST<\/strong> is where WinDbg will run. This machine is, in most cases, the machine where the driver was developed. Let’s assume that this is the machine where the driver was developed and defer the details about how to set the symbol and source directory to another post. The machine named TARGET<\/strong> is where our driver is loaded by the system. The TARGET machine’s operating system don’t necessarily need to be Checked Build<\/em> nor it is necessary to install any additional kit to the operating system. All you need is your driver and a serial port. All of the Windows NT platform (Windows NT, Windows 2000, Windows XP, Windows 2003 Server and Windows Vista) already bring their native debugger since its installation. Actually, this is a great feature in the use of WinDbg. Imagine that kind of problem that manifests itself on the client machine. You will not want to install anything aggressive or even that will change the scenario that would make the problem not manifest itself anymore. Believe me, this is not so rare as it seems to be. In these cases, simply enable the Debug mode on the TAGET computer and we’re done.<\/p>\n

To enable the Debug mode in the TARGET machine, we need to edit some initialization parameters that are in the Boot.ini<\/strong> file located in the system root folder. This file has its attributes as system file<\/em>, hidden file<\/em> and also read-only<\/em>. You may need to configure Windows Explorer to view these files. Using Windows Explorer, go to the root folder, remove the read-only property from the Boot.ini file, then open this file using a text editor like Notepad, for example. The contents of this file is similar to that shown below.<\/p>\n

\"\"<\/div>\n

At Operating Systems<\/em> section you will need to duplicate the referenced\u00a0system line you will want to debug. Add to its end the \/debugport=com1 \/baudrate=115200<\/strong> parameters <\/strong>that will configure the Debug mode. The first parameter selects the COM port being used, while the second selects communication speed. The serial protocol is not the fastest communication way between machines HOST and TARGET and in some cases is annoying having to wait for interactions between WinDbg and debugee system. There are other media that can be used if your computer does not have an available serial port or if you wish more speed and comfort during the Debug. See more details in the post Serial Killers<\/a>.<\/p>\n

The final result of our Boot.ini file should be something like shown below. I’ll skip the lines beginning that describe the operating system for better visualization putting “…” in their places.<\/p>\n

\n
[boot loader]<\/pre>\n
timeout=30<\/pre>\n
default=multi(0)disk(0)rdisk(0)partition(2)\\WINDOWS<\/pre>\n
[operating systems]<\/pre>\n
multi(0)... \/NoExecute=OptIn<\/pre>\n
multi(0)... \/NoExecute=OptIn \/debugport=com1 \/baudrate=115200<\/pre>\n<\/div>\n
After making these changes, you can save the file and restore the original file attributes on it. In Windows XP and Windows 2003, the same described steps above could be done with the help of a tool named Bootcfg.exe<\/strong>. In Windows Vista, the process is quite different and I will describe it in a future post.<\/p>\n
Back on the HOST machine, start WinDbg and select Kernel Debug…<\/em> from the File menu. You should see a window that sets the communication way. Make it so in a compatible way with what was set in the Boot.ini on the TARGET machine. In this case, we are using COM1 serial port and baud rate of 115200. Clicking on OK will make WinDbg opening the serial port on the HOST machine and it will wait until the TARGET machine be ready. At this point, we get the following messages in WinDbg command window .<\/p>\n
\"\"<\/div>\n
While the HOST machine waits, make sure your driver is installed on the TARGET machine and restart it. After that, when system is starting, the system loader is \u00a0displaying the options found in the Boot.ini edited by you. Select the option which appears [debugger enabled]<\/strong> as shown below.<\/p>\n
\"\"<\/div>\n
After selecting  this option, the machines HOST and TARGET should connect each other and the  Command<\/em> window would show a text similar to that shown below.<\/p>\n
\n
Microsoft (R) Windows Debugger  Version 6.6.0007.5<\/pre>\n
Copyright (c) Microsoft Corporation. All rights reserved.<\/pre>\n
 <\/pre>\n
Opened \\\\.\\com1<\/pre>\n
Waiting to reconnect...<\/pre>\n
Connected to Windows XP 2600 x86 compatible target, ptr64 FALSE<\/pre>\n
Kernel Debugger connection established.<\/pre>\n
Symbol search path is: *** Invalid ***<\/pre>\n
****************************************************************************<\/pre>\n
* Symbol loading may be unreliable without a symbol search path.           *<\/pre>\n
* Use .symfix to have the debugger choose a symbol path.                   *<\/pre>\n
* After setting your symbol path, use .reload to refresh symbol locations. *<\/pre>\n
****************************************************************************<\/pre>\n
Executable search path is:<\/pre>\n
*********************************************************************<\/pre>\n
* Symbols can not be loaded because symbol path is not initialized. *<\/pre>\n
*                                                                   *<\/pre>\n
* The Symbol Path can be set by:                                    *<\/pre>\n
*   using the _NT_SYMBOL_PATH environment variable.                 *<\/pre>\n
*   using the -y  argument when starting the debugger. *<\/pre>\n
*   using .sympath and .sympath+                                    *<\/pre>\n
*********************************************************************<\/pre>\n
*** ERROR: Symbol file could not be found.  Defaulted to export symbols for<\/pre>\n
ntkrnlpa.exe -<\/pre>\n
Windows XP Kernel Version 2600 UP Free x86 compatible<\/pre>\n
Built by: 2600.xpsp_sp2_gdr.050301-1519<\/pre>\n
Kernel base = 0x804d7000 PsLoadedModuleList = 0x805531a0<\/pre>\n
 <\/pre>\n<\/div>\n
Well, so far we know that the machines are connected. Pressing Ctrl + Break<\/em> in Windbg, we will make the system freeze in the TARGET machine and the control is passed to the debugger. The  debugger is ready to receive your commands when you get a command  prompt KD<\/strong> indicated by the letters at Command <\/em>window bottom left.<\/p>\n
\"\"<\/div>\n
Just to make a simple test, type “lm” command and hit enter. This command lists the modules loaded by the system. Note that the Useless<\/em> driver is not on this list yet. This  happens because the driver instance is configured to have its execution started manually, so, the driver has not yet been  loaded by the system. Then, select the item Open Source File…<\/em> from File<\/em> menu and open Useless.c<\/em> file. Click on the DriverEntry function name and hit F9. Although there is no visible sign, we put a break-point on this function. The fact of having no visual change is due to the fact that our module has not been loaded yet. We can be sure that the breakpoint is installed listing the breakpoints with the “bl” command.<\/p>\n
\n
kd> bl<\/pre>\n
 0 e f9fb3430     0001 (0001) Useless!DriverEntry<\/pre>\n<\/div>\n
Now we launch the “g” command that will cause the system to return to its normal execution.<\/p>\n
Once the system is loaded, we will start the driver through the “net start Useless” <\/em>command <\/em>. When the driver starts, the DriverEntry entry point runs and consequently, we have its execution stopped at our breakpoint. The TARGET machine will freeze while the debugger has control over the system. Note that now our module is loaded, the breakpoints are easily identified by lines with red background color.<\/p>\n
Well,  the first steps have already been done, the commands and details on how  to debug the kernel for Windows would be outside the scope of this  post. But a good tip on how to obtain tons of details about this subject is the Windows 2000 Kernel Debugging<\/a> book. The  book is not one of my favorites; it gives a good introduction to the  subject besides talking about how to use and build Debug  Extensions, but does not bring the used\u00a0techniques by real Kernel Debugging ninja masters. Another excellent information source on this subject is the discussion list Windows Debugger Users List<\/a> dedicated to Windbg. That’s all without forgetting the Help.<\/p>\n
This  was an initial post about the subject, wait for future posts where I will give  the steps about how to use Windbg with VMware and how to debug Windows  Kernel with one machine using SoftIce (God rest his soul).<\/p>\n
Have fun… \ud83d\ude09<\/p>\n","protected":false},"excerpt":{"rendered":"
I earned my first computer when I was 13 years-old, but seven years later, when I started my internship, I discovered that it was possible to debug programs that I used to write. Until then, my debug methods were always things like printing the variable value on screen. All right, in that time I didn’t […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"pagelayer_contact_templates":[],"_pagelayer_content":"","footnotes":""},"categories":[1],"tags":[],"class_list":["post-69","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/69","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/comments?post=69"}],"version-history":[{"count":1,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/69\/revisions"}],"predecessor-version":[{"id":70,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/69\/revisions\/70"}],"wp:attachment":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/media?parent=69"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/categories?post=69"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/tags?post=69"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}