The Kernel debugger included with the OS/2 Toolkit is a low-level debugger oriented toward system and device-driver debugging. The kernel debugger can assist in debugging Workplace Shell applications until higher-level debuggers, such as IPMD, can provide adequate debugging functions in complex situations.

When the Kernel debugger is installed, two files are copied to the root directory of the boot drive: OS2KRNL and OS2KRNL.SYM. OS2KRNL is a hidden file, which will be renamed OS2KRNL.RTL when debugging is active. Because the Kernel debugger supports symbolic debugging, numerous symbol files (.SYM files) are copied to the \OS2\DEBUG\DLL directory. These symbol files contain information on symbols defined and used by OS/2.

To make symbols defined in your Workplace Shell application available to the Kernel debugger, use the MAPSYM program. MAPSYM converts the .MAP file generated by the linker to a .SYM file. The .SYM file should reside in the same directory as the .EXE or .DLL executable file it represents and it should have the same name.

When using the Kernel debugger, it is a good idea to use the functionprefix= modifier in the IDL file implementation statement. There are three reasons for this:

In the following sample code, the methods generated are called Dogdisplay and Dogbark.

/****************************************************************//* By adding the functionprefix= modifier to the class, all     */
/* methods defined will be unique, for example, Dogbark.        */
/* This is useful when debugging, because every method in the   */
/* class will start with this prefix and will not be static.    */
/****************************************************************/

#ifndef dogdbug_idl
  #define dogdbug_idl

  #include <somobj.idl>

  interface Dog : SOMObject
  {
    attribute string breed;

    // The breed for the dog
    void display();

    // Display characteristics for this dog
    void bark();

    // Have the dog bark
    #ifdef __SOMIDL__
      implementation
    {
      releaseorder:  _get_breed, _set_breed, display, bark;

      //# Class modifiers
      functionprefix = Dog;   // This will help when debugging
      callstyle      = oidl;
      majorversion   = 1;
      minorversion   = 2;

    }; #endif /* __SOMIDL__ */

  }; #endif

As soon as the Kernel debugger is active, use the .p command to display process information. The Process ID (pid) of the Shell process and the Workplace process can be located quickly using this command. The following figure shows an example of the information you obtain when using the .p command:

    ## .p
       Slot  Pid  Ppid Csid Ord  Sta Pri  pTSD     pPTDA    pTCB     Disp SG Name
       0001  0001 0000 0000 0001 blk 0100 ffe3a000 ffe3c7d4 ffe3c620 1e7c 00 *ager
       0002  0001 0000 0000 0002 blk 0200 7b92a000 ffe3c7d4 7bb28020 1f3c 00 *tsd
       0003  0001 0000 0000 0003 blk 0200 7b92c000 ffe3c7d4 7bb281d4 1f50 00 *ctxh
       0004  0001 0000 0000 0004 blk 081f 7b92e000 ffe3c7d4 7bb28388 1f48 00 *kdb
       0005  0001 0000 0000 0005 blk 0800 7b930000 ffe3c7d4 7bb2853c 1f20 00 *lazyw
       0006  0001 0000 0000 0006 blk 0800 7b932000 ffe3c7d4 7bb286f0 1f3c 00 *asyncr
       0008  0005 0001 0005 0001 blk 0200 7b936000 7bb458a4 7bb28a58      00 cmd
      *0009# 0006 0005 0006 0001ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿7bb28c0c 1eb8 01 pmshell
       000d  0006 0005 0006 0002³                          ³7bb292dc      01 pmshell
       000e  0006 0005 0006 0003³   In this example,       ³7bb29490      01 pmshell
       000f  0006 0005 0006 0004³   Pid #6 is the first    ³7bb29644      01 pmshell
       0010  0006 0005 0006 0005³   PMSHELL process, or    ³7bb297f8      01 pmshell
       0007  0006 0005 0006 0006³   the "Shell process".   ³7bb288a4 1ecc 01 pmshell
       0013  0006 0005 0006 0007³                          ³7bb29d14      01 pmshell
       0015  0006 0005 0006 0008ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ7bb2a07c      01 pmshell
       0016  0006 0005 0006 0009 blk 0200 7b952000 7bb44020 7bb2a230      01 pmshell
       0017  0006 0005 0006 000a blk 0800 7b954000 7bb44020 7bb2a3e4      01 pmshell
       0018  0006 0005 0006 000b blk 0800 7b956000 7bb44020 7bb2a598      01 pmshell
       0019  0006 0005 0006 000c blk 0800 7b958000 7bb44020 7bb2a74c      01 pmshell
       001a  0006 0005 0006 000d blk 0804 7b95a000 7bb44020 7bb2a900      01 pmshell
       001b  0006 0005 0006 000e blk 0804 7b95c000 7bb44020 7bb2aab4      01 pmshell
       001c  0006 0005 0006 000f blk 0500 7b95e000 7bb44020 7bb2ac68      01 pmshell
       001d  0006 0005 0006 0010 blk 0800 7b960000 7bb44020 7bb2ae1c 1bb0 01 pmshell
       Slot  Pid  Ppid Csid Ord  Sta Pri  pTSD     pPTDA    pTCB     Disp SG Name
       001e  0006 0005 0006 0011 blk 0800 7b962000 7bb44020 7bb2afd0 1b8c 01 pmshell
       001f  0006 0005 0006 0012 blk 0200 7b964000 7bb44020 7bb2b184      01 pmshell
       000a  0003 0000 0003 0001 blk 0200 7b93a000 7bb4484c 7bb28dc0      00 lanmsgex
       000b  0004 0000 0004 0001 blk 0200 7b93c000 7bb45078 7bb28f74      00 lsdaemon
       000c  0007 0006 0007 0001 blk 0800 7b93e000 7bb460d0 7bb29128      00 harderr
       0011  0007 0006 0007 0002 blk 0800 7b948000 7bb460d0 7bb299ac      00 harderr
       0012  0007 0006 0007 0003 blk 0800 7b94a000 7bb460d0 7bb29b60      00 harderr
       0014  0008 0000 0008 0001 blk 0200 7b94e000 7bb468fc 7bb29ec8      01 stoplan
       0020  0009 0006 0009 0001 blk 0500 7b966000 7bb47128 7bb2b338 1eb8 10 pmshell
       0021  0009 0006 0009 0002 blk 0200 7b968000 7bb47128 7bb2b4ec      10 pmshell
       0022  0009 0006 0009 0003ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿7bb2b6a0 1eb8 10 pmshell
       0023  0009 0006 0009 0004³                          ³7bb2b854 1ecc 10 pmshell
       0024  0009 0006 0009 0005³   In this example,       ³7bb2ba08      10 pmshell
       0025  0009 0006 0009 0006³   Pid #9 is the second   ³7bb2bbbc      10 pmshell
       0026  0009 0006 0009 0007³   PMSHELL process, or    ³7bb2bd70      10 pmshell
       0027  0009 0006 0009 0008³   the "Workplace         ³7bb2bf24      10 pmshell
       0028  0009 0006 0009 0009³   process".              ³7bb2c0d8      10 pmshell
       002a  0009 0006 0009 000b³                          ³7bb2c440 1eac 10 pmshell
       002b  0009 0006 0009 000cÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ7bb2c5f4 1eb8 10 pmshell
       0029  000a 0006 000a 0001 blk 0200 7b978000 7bb47954 7bb2c28c      11 cmd
       002c  000b 0006 000b 0001 blk 0200 7b97e000 7bb48180 7bb2c7a8      12 cmd
       002f  001f 0006 001f 0001 blk 0200 7b984000 7bb4a230 7bb2ccc4      15 cmd
       Slot  Pid  Ppid Csid Ord  Sta Pri  pTSD     pPTDA    pTCB     Disp SG Name
       0030  001d 0006 001d 0001 blk 0200 7b986000 7bb49a04 7bb2ce78      13 cmd
    ##

The Kernel debug command VSF * sets the trap vectors. This allows traps in the Workplace Shell application to be located quickly. The Kernel debugger stops on the instruction that is about to cause a trap when these vectors are set. In this way, it is possible to examine the stack and registers to determine the cause of the trap.


[Back] [Next]