Kernel Debugger Setup Reference 18 Feb 2023 ------------------------------- Steven H. Levine steve53@earthlink.net 0. Introduction. ---------------- This note explains how to set up for kernel debugging on ArcaOS, 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. This note also assumes that the HOST and the MUT are connected with a null modem (i.e. Laplink) cable. If you running ArcaOS on a VirtualBox VM, see: https://cs.wmich.edu/~rhardin/s14cs4540/presentations/2virtualmachines.txt for a guide on how to set up and connect to the virtual COM ports. While this note is oriented to those running ArcaOS, the same procedures apply to all versions of eComStation and OS/2. Only the file versions change. To get started, you need to - Acquire files - Verify serial port operation - Install a debug terminal application - 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://www.warpcave.com/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 because 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 used on ArcaOS are available on your ArcaOS distribution media. Files for half-strict SMP debug kernels are in \OS2IMAGE\DEBUG\SMP Files for half-strict W4 debug kernels are in \OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45 Debug kernels and debug symbols for the kernels typically used on eComStation are available from http://www.os2site.com/sw/upgrades/kernel/ Some the symbol files you need may already be installed. If not, they may be available on your installation media 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 with the same bldlevel as your retail kernel. Use the bldlevel command to check your kernel version. If you are running a 14.106_SMP (or higher) kernel, you will need to to run the 14.104a_SMP debug kernel. There is no 14.106_SMP debug kernel. 2. Verify Serial Port Operation ------------------------------- If this is the first time you have used the serial port on either the HOST or the MUT, it is recommended that you verify that the serial ports are operating properly. The MUT must have a hardware serial port with standard ISA style COM port addresses (i.e 3f8h etc.) The HOST can have either a hardware serial port or an USB attached serial port. A hardware serial port is typically easier to get working. If you must use a USB-to-Serial adapter make sure you get one that is compatible with the Prolific Technology Inc. PL-2303 chipset. The standard IBM USB Communications Class driver (usbcom.sys) does not support this chipset. Use one of the available modified versions: usbcom-20110818.zip usbcommp.zip usbcomm_pl2303.zip Users have reported varying levels of success with these drivers. The quality of the available USB-to-Serial adapters varies a lot and there's no way to know if a particular adapter will perform well in a specific system without testing. If you don't have a serial communications application installed, install HALITE from eComStation CD#2 (BONTRIAL\IBMBON\OS2IMAGE\FI\BONUSPAK\HALITE) or install the ZOC 4.15 demo from http://hobbes.nmsu.edu/h-search.php?key=zoc on both the HOST and the MUT. Configure the application to communicate at 115KBaud, 8 data bits, no parity, 1 stop bit. Turn off RTS, DTS and CD signalling and turn on XON/XOFF flow control in both directions. Start the communication applications on the HOST and the MUT. Characters typed into the HOST's comm app window appear on the MUT's screen and visa versa. 3. 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 the version of pmdf that reports itself as: 12-08-12 1:11 195,290 0 pmdf.exe with bldlevel: Signature: @#slainc:14.106#@##1## 2012/12/07 14:01:06 slamain::EN:US:2::@@Process Dump Formatter for eComStation and has MD5 sum: 81ae02619af54a7619cebf740925ae3b *pmdf.exe and which is available from: http://www.warpcave.com/betas/pmdf_exe-20121208.zip This is a patched version of the pristine pmdf that reports itself as: 12-29-04 11:53 392,764 0 pmdf.exe and has MD5 sum: 2faee8338d2716b350c466fc13609885 *pmdf.exe and which shipped with the MCP FixPak 5 and newer and eCS 2.1 and newer. The patch is cosmetic and causes the build a pristine pmdfvers.lst file that reference the 14.106 rather rather than the 14.013f kernel. To configure pmdf on the HOST, use Options->Terminal Settings. Set the COM port to match the hardware you have. Set the other terminal setting to: Speed 115200 Bits length 8 bits Parity None Xof/Xoff Mode On Auto Receive Flow Control Mode Normal Use File->Connect->No Break In to verify that PMDF can access the COM port. 4. Install kdb.ini on MUT ------------------------- On startup, the kernel debugger looks for the script file kdb.ini in the root of the boot volume and executes the commands contained in this script. I recommend starting with 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 115KBaud .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 If the MUT is using a port other than COM1, edit the .b and o commands to match. If you find you have troubles communicating with the MUT at 115KBaud, edit the .b command to select a speed that communicates without losing data. When editing the .b command do not omit the T suffix. It is required to indicate that the speed is a decimal number. Retail kernels ignore this file, you can leave it installed permanently. 5. Install debug symbol files on MUT ------------------------------------ The debug 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, typically \mmos2 on the boot volume. The base name of the debug symbol file must match the base name of the associated binary file. Most of the symbol files follow this naming convention. The symbol files for the kernels have a different naming convention. For the retail kernel, the symbol file will be named os2krnlr.sym. For the half-strict debug kernel, the symbol file will be named os2krnlb.sym. For the all-strict debug kernel, the symbol file will be named os2krnld.sym. When copying the kernel symbol file to root directory, rename the file and drop the suffix. The kernel debugger always looks for os2krnl.sym, regardless of the kernel type. We almost always install the half-strict debug kernel so we need to copy and rename os2krnlb.sym. Some of the symbol files for the TCP/IP stack have yet another naming convention. The files for some of the 32-bit drivers have a k suffix (i.e. socketsk.sys and socketsk.sym). However, the internal module name omits the k suffix for backward compatibility. This mean that when copying socketsk.sym to the \MPTN\PROTOCOL directory, it must be renamed sockets.sym. When choosing symbol files to install, install only the files you need to debug the current issue. Symbol files use up limited kernel resources and too many installed symbol files can cause problems. 6. Install debug kernel on MUT ------------------------------ There are two types of debug kernels, half-strict and all-strict. These days we always use the half-strict debug kernels because IBM did not distribute all-strict kernels for recent kernel version. The half-strict kernel is named os2krnlb. The all-strict kernel is named os2krnld. The retail kernel is named os2krnl. If the installed files are marked read/only, system or hidden, clear the attributes. To install the debug kernel, copy the kernel file to the root of the boot volume and rename it to overwrite the os2krnl file. Copy the debug kernel os2krnl.sym file into place at this time. For the half-strict kernel, copy os2krnlb and overwrite os2krnl. It should go without saying that you should backup the existing files before overwriting them. It should also go without saying that you should have a procedure in place to restore the retail kernel if something goes wrong. 7. Start Debugging ------------------ Once everything is installed, reboot the MUT and you should see kernel debugger output on the pmdf console. To get the debugger's 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 when you need to analyze complex data structures. 8. Using a Shared COM port -------------------------- Sometimes, it is convenient to work from a HOST that is not directly connected to the MUT. If you have an IBM LAN setup, this can be accomplished by sharing the connected HOST's COM port on the LAN. The connected HOST is directly connected to the MUT and is on the LAN. The non-connected HOST is also on the LAN, but is not directly attached to the MUT. On the connected HOST, enter net share' COM1 = COM1 /COMM /remark:"Shared COM1" to share the HOST's COM port on the LAN. On the non-connected HOST, enter net use COM1 \\connectedhost\COM1 replacing connectedhost the with host name of the connected HOST. This method works even if the HOST that is not connected to the MUT does not have a physical COM port or if a COM port driver is not loaded on this HOST. Good luck. Steven