
Kernel Debugger Setup Reference                           22 May 2009
-------------------------------                      Steven H. Levine
                                                steve53@earthlink.net

0. Introduction.
----------------

This note explains how to set up for kernel debugging on eComStation or OS/2.

In the following, MUT means the machine under test, that is the machine
begin debugged.

Host means the machine running the debug terminal application.

There are two supported methods of interfacing the host to the MUT, serial
and network.  This note documents only the serial connection method.

While this note is oriented to those running eComStation, the same
procedures apply to all versions of OS/2.  Only the file versions change.

To get started, you need to

  - Acquire files
  - Install a debug terminal application
  - Verify the serial interface
  - Install a kdb.ini file on MUT
  - Install symbol files on MUT
  - Install a debug kernel on MUT
  - Start debugging

If you are looking for a kernel debugging tutorial, take a look at The OS/2
Debugging Handbook #0.7a (sg25-4640-00).

http://home.earthlink.net/~steve53/os2diags contains some content you might
find useful, especially KDebug.ref, which is a debugger command cheat-sheet.

The System Dump and Process Dump references may be helpful if you have
trouble with setting up pmdf.  They also describe to organization of the
distribution files that contain debug symbol files.

1. Acquire Files.
-----------------

To use the kernel debugger, the MUT needs to have a debug kernel installed
and needs to have an appropriate set of debug symbol files installed.

The debug kernel contains the logic to control the kernel and to communicate
with the debug terminal on the Host.

Symbol files allow the kernel debugger to convert numeric addresses to
symbolic names.  A symbol file is specific to particular version of an
executable file becuse the symbol file is generated from the map file
produced by the linker.  If you can not locate the correct symbol file, you
can try to use one for a similar version of the executable.  The results
will vary.

Debug kernels and debug symbols for the kernels typically used on
eComStation are available from

  http://www.os2site.com/sw/upgrades/kernel/

Some the dump symbols file you need may already be installed.  If not, they
may be available on your installation CD in the \os2image\debug and the
\os2image\fi\sysmgmt directories.  They may also available from your account
at the eComStation website (www.ecomstation.com).

Generally you want to use a debug kernel that matches your retail kernel.
If you are running a 14.104a W4 kernel, you want to run a 14.104a W4 debug
kernel.

Use the bldlevel command to check your kernel version.


2. Install Debug Terminal Application
--------------------------------------

The Host needs to be running a terminal program that can communicate with
the debug kernel over the debug interface.

You can use any terminal program that supports serial communication.  I
recommend either pmdf or debugo.  Both provide features that make kernel
debugging more efficient.  I will discuss pmdf here.  For reference, I
prefer this version of pmdf

 1-27-06   9:25         392,764           0  pmdf.exe
 e57fa680d3d407b5103b5a0080a36dca *pmdf.exe

To configure pmdf, use Options->Terminal Settings and select

  Speed 115200
  Bits length   8 bits
  Parity        None
  X-on          On
  Auto Receive  Normal


3. Testing the Serial Interface.
--------------------------------

Start pmdf on the Host and the MUT and verify the Terminal Settings.  Open
the COM interfaces with File->Connect->No Break In.  Characters typed into
the host's pmdf command line should appear on the MUT's screen and visa
versa.


4. Install kdb.ini on MUT
-------------------------

On startup, the kernel debugger looks for the file kdb.ini in the root of
the boot volume and executes the commands contained in this script.  I
recommend the following script

.b 115200T 1
? " 10 May 09 SHL "
? " on debug terminal - mode com1 115200,n,8,1,rts=hs,buffer=on,xon=on or equivalent "
? " on mut "
o 3fc b
o 3fa c7
vsf *
vc e
g

This is an annotated version of the above

; Set com1 to run at 115k
.b 115200T 1
; This is a hack to add comments to kdb.ini
? " 10 May 09 SHL "
? " on debug terminal - mode com1 115200,n,8,1,rts=hs,buffer=on,xon=on or equivalent "
? " on mut "
; Access com1 mcr and set ie,rts,dtr on
o 3fc b
; Access com1 fcr and trigger fifo at 14, enable fifos, reset both
o 3fa c7
; Hook all executions
vsf *
; Unhook page exceptions
vc e
; List break points
bl
; Resume execution
g

Retail kernels ignore this file, you can leave it installed permanently.


5. Install symbol files on MUT
------------------------------

The symbol files allow the kernel debugger to convert addresses to symbolic
names.  When using the kernel debugger, the symbol files need to be installed
in the same directory as the associated binary file.  This differs from the
setup required when using pmdf to analyze dump files.

For example, install uniaud32.sym in same directory as uniaud32.sys,
typicall \mmos2 on the boot volume.

Some distributions add a d or r suffix to the name of the debug symbol file,
where d means debug and r means retail.  For example, os2krnld.sym.  When
copying the symbol file to install directory, rename the file and drop the
suffix,

6. Install debug kernel on MUT
------------------------------

If the destination files are marked read/only, system or hidden, clear the
attributes.

To install the debug kernel, copy it to the root of the boot volume,
overwriting the retail kernel.  Copy the matching os2krnl.sym into place at
this time.

It should go without saying that you should backup the existing files before
overwriting them.

7. Start Debugging
------------------

Once everthing is installed, reboot the MUT and you should kernel debugger
output on the pmdf console.

To get the debuggers attention, type Ctrl-C or click on Ctrl-C on the menu.

From this point on the possibilities are endless.

The kernel supports more than a few commands.  The ones you are most likely
to need are

  r             display registers
  k             display stack
  ln            list nearest symbol
  d             display memory
  u             disassemble code
  .maac         find arena record for address and show context
  .lmo          list module
  .p*           display current process
  .p#           display process selected by .s
  b             set/clear/list break points
  p             single step over procedures
  t             single stop into procedures
  g             resume execution
  lm            list maps
  wa            add map
  wr            remove map

Pmdf Analyze menu options will often work under the kernel debugger.

Pmdf supports a REXX interface which can save a lot of typing if you need a analyze complex
data structures.


Good luck.

Steven
