KernelDebugRef - Installing the Kernel Debugger

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
 ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
 ³ OS2KRNL      ³
 ³ OS2KRNL.SYM  ³
 ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
 ³ OS2KRNL.RTL  ³
 ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

```

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.)

  ÄROOT
 ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
 ³ 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.