Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Kernel Debugger Reference
Introduction Installing the Kernel Debugger The T Terminal Emulator Entering the Debugger Expressions Operator Precedence Binary Operators Unary Operators Numbers Strings Symbol Files Using Kernel Debugger Commands The Breakpoint (BP) Command Breakpoint Commands External Commands Using Default Commands External Debugger Commands Setting Useful Breakpoints Debugging Kernel Device Drivers Debugging VM Start Sessions Debugging a Remote System Notices

The menu-based debug installation program installs debug replacement files for the kernel and the Presentation Manager interface. Once the program is installed, you can install other debug files, or restore retail files, from the OS/2 command prompt.

During initial installation, two files are copied to the root directory of your specified installation drive:

DBINST.CMD: A command file that can be executed separately. This file calls DBUGINST.EXE with the requested installation drive as a command-line argument.
DBUGINST.EXE: This executable file is the user interface. The user can choose which parts of the debug system to install, or which parts to restore to the retail version.

Installing from Diskette

To install and start the debug installation program:

1. Insert Debug Diskette 1 in drive A. 2. At the OS/2 command prompt, type:

  a:install c a

where:

c is the drive where OS/2 resides.
a is the diskette drive.

Note: Do NOT type a colon after the drive letters.

3. Press Enter. A screen appears that presents installation choices.

Installing from CD-ROM or Remote Disk

To install and start the debug installation program:

1. Insert the Toolkit installation CD-ROM into the CD-ROM drive.

  Note: If installation is from a remote disk, ensure you have access to it.

2. At the OS/2 command prompt, type:

  ```
  d:\OS2TK21\CDINST d c
  ```
  where:
  * d is the drive of the CD-ROM or remote disk.
  * c is the drive where OS/2 resides.
  Note: Do NOT type a colon after the drive letters.

3. Press Enter. A screen appears that presents installation choices.

The user interface consists of a menu that provides installation choices in three optional parts. It also provides the ability to restore two of those parts to their corresponding retail versions. The menu choices are as follows:

Install utilities/symbols
Install Kernel Debugger
Install Debug PM
Restore Retail Kernel
Restore Retail PM

When prompted to enter a debug installation option, choose the options in the order they appear on the screen.

When you complete the debug installation procedure, you may need to edit your CONFIG.SYS file.

Debug Support - Edit CONFIG.SYS

Edit CONFIG.SYS - Debug Kernel

If you installed only the Kernel Debugger, shutdown and restart your system.

Note: If you have a second communication port, then the output of the debug kernel will go to that port (COM2), otherwise output will go to COM1. Be sure to connect your cable to the active port.

Restoring the Kernel

To restore the retail kernel, run the debug installation program and select the "Restore Retail Kernel" option.

Debug Presentation Manager Interface

If you have installed the debug version of the Presentation Manager Interface, modify the DEVICE statement with the PMDD.SYS line as follows:

DEVICE=c:\OS2\DEBUG\DLL\PMDD.SYS /C:n

where:

c is your installation drive
n is the communication port for debug output

Allowed values for n are:

2 if COM2 is present
1 if COM2 is not present

The DEVICE statement includes the C drive as the installation drive and allows you to call the debug version of PMDD.SYS from the OS2\DEBUG\DLL subdirectory. The /C switch is set with n as the communication port for the debug output.

Modify the LIBPATH statement by adding the DEBUG\DLL subdirectory as follows:

LIBPATH=C:\OS2\DEBUG\DLL; ....

Shutdown and restart your system to have the changes take effect.

Restoring the Presentation Manager Interface

To restore the retail Presentation Manager, do the following:

1. Restore the device statement:

  DEVICE=C:\OS2\PMDD.SYS

2. Modify the LIBPATH statement by removing the DEBUG\DLL subdirectory. 3. Shutdown and restart your system to have the changes take effect.

Debug Support - Install Utilities / Symbols

The Install utilities / symbols option copies all the kernel and the Presentation Manager symbol files (.SYM) to the installation partition. The subdirectory structure follows:

─ROOT
     └──── OS2 
           ├── DLL 
           └── DEBUG 
                 └──── DLL

Debug Support - Install Kernel Debugger

The Install Kernel Debugger option:

Unhides OS2KRNL in the root directory
Renames it with a .RTL file name extension
Replaces it with the debug version from the 'DB' diskette
Adds a kernel symbol file to the root directory

─ROOT
     └───── OS2 
             │ 
             └─── DEBUG 
                   │ 
                   └──── DLL ──>   ┌───────────┐
                                   │ PMDD.SYS  │
                                   │ PMDD.SYM  │
                                   │ PMGRE.DLL │ 
                                   │ PMWIN.DLL │ 
                                   │ PMWIN.SYM │ 
                                   │ PMGRE.SYM │ 
                                   └───────────┘

Debug Support - Install Debug PM

The Install debug PM option:

Unpacks debug versions of the Presentation Manager and display DLLs and PMDD.SYS to the \OS2\DEBUG\DLL directory
Replaces the PMWIN symbol file:

─ROOT
     └───── OS2 
             │ 
             └─── DEBUG 
                   │ 
                   └──── DLL ──>   ┌───────────┐
                                   │ PMDD.SYS  │
                                   │ PMDD.SYM  │
                                   │ PMGRE.DLL │ 
                                   │ PMWIN.DLL │ 
                                   │ PMWIN.SYM │ 
                                   │ PMGRE.SYM │ 
                                   └─

Debug Support - Restore Retail Kernel

The Restore retail kernel option copies the saved OS2KRNL.RTL file in the root directory to the same name without extension, and deletes the .RTL file. (The kernel symbol file will be left in the root directory.)

 ┌──────────────┐
 │ OS2KRNL      │
 └──────────────

Debug Support - Restore Retail PM

The Restore retail PM option describes the config.sys changes required to restore the retail version. The debug DLLs (which are currently active) are left in the \OS2\DEBUG\DLL subdirectory.