Using the Demo

This demo shows a very simple set of DevIOCtl calls being made from a sample application to a device driver. It explains some of the actions you could take to debug this scenario at the source level.

To run the demo, follow these steps:

• Copy SAMPLEDD.SYS to the root directory of the C drive on your victim system.
  
• On the victim system, edit CONFIG.SYS so that it contains the following line:

     DEVICE=C:\SAMPLEDD.SYS
  

  This loads the sample device driver when you reboot the victim system.
  

• Copy SAMPLE.EXE to your victim system.
  
• Reboot your victim machine so that the SAMPLEDD.SYS binary and the debug OS2KRNL and OS2LDR binaries are instantiated.

  You can perform a quick check to see if the victim machine is OK by running your normal terminal emulator (T, ZOC, and so on). This will show if KDB is communicating at 9600 baud.
  

• Shut down the terminal emulator before you run the debugger.
  
• Run the SETICAT.CMD file to set the environment variables on your host system.
  
• Type icatgam. The Initialization window displays.
  
• From the Initialization window, select the Attach push button.
  
• In the Debug Session Control, make sure you see SAMPLEDD.SYS. Click on the plus sign (+) next to it and notice that one part is displayed. Click on that plus sign (+) and notice eight entries are now displayed.
  10.
  Click on STRATEGY. The STRATEGY routine of the sampledd device driver should display in a source window.

  Note: This is MASM source, so you will see assembler directives, but it is source. We support both CodeView (CL and CL386) and HLL (IBM VACPP) debug formats for C.

  11.
  Set a breakpoint on line 209 inside the STRATEGY routine by double-clicking on the line number. Run the debugger by selecting the Run button.
  12.
  On the victim machine, type sample. SAMPLE.EXE will emit a DevIOCtl to open the SAMPLEDD device driver.
  13.
  When the debugger notifies you that the breakpoint has been encountered, open the Registers window and then open the Storage window. Edit one of the addresses in this storage window by double-clicking on the address and change the address value to that of the PC register, which is located at the top of the list of status flags registers in the Registers window. You will see memory that corresponds to the code space.
  14.
  From the Source window, select Passthru from the Monitors menu.
  15.
  In the Passthru window, type dg cs in the Command entry field and select the Send push button or press the Enter key. This sends the command to KDB and the output is displayed in the response area. Notice that it provides information about SAMPLEDD's code descriptor. You can emit most KDB commands from the Passthru window. Commands that cause the victim machine to resume execution (for example, g and t) should be avoided.

  Note: If you change the state of the victim machine with KDB commands in the Passthru window, you must select the Resync push button to allow the debugger to reflect the changes.

  16.
  Set another breakpoint on line 275 inside the Open subroutine. Run the debugger until the breakpoint is encountered.
  17.
  Select the step into choice or button to do a step into on the Ccall macro to SubrWFrame. You are in the SubrWFrame subroutine. Click on the Call Stack icon.
  18.
  From the Call Stack window, select the Display style choice from the Options menu.
  19.
  From the Display style window, enable the Return Address choice, which is located under the Select items group heading. Select the OK push button.
  20.
  Select the step over choice or button and notice the change in the Call Stack window.
  21.
  Look at the Debug Session Control window and find SAMPLE.EXE. Click on the plus sign (+) and notice that one part is displayed. Click on that plus sign (+) and you will see MAIN.
  22.
  Click on MAIN and set a breakpoint at line 44. Run the debugger by selecting the Run button. The breakpoint will be encountered in the STRATEGY routine again.
  23.
  Run one more time and the breakpoint will be encountered in SAMPLE.EXE in MAIN.

  After you have completed these steps, close the debugger. At this point, you can use your terminal emulator to communicate with KDB. If you did not use the CAT_SETUP_RATE environment variable, KDB will be set at the baud rate you used to communicate with the debugger.

  ---

  [Back: When Things Go Wrong]
  [Next: Getting Started]