View source for KernelDebugRef - Installing the Kernel Debugger

{{IBM-Reprint}}
{{KernelDebugRef}}

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:

* [[#Debug Support - Install Utilities / Symbols|Install utilities/symbols]]
* [[#Debug Support - Install Kernel Debugger|Install Kernel Debugger]]
* [[#Debug Support - Install Debug PM|Install Debug PM]]
* [[#Debug Support - Restore Retail Kernel|Restore Retail Kernel]]
* [[#Debug Support - Restore Retail PM|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 [[#Debug Support - Edit CONFIG.SYS|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.