[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts

Kernel Debug Program

The Kernel Debug Program on AIX 4.3 will provide new commands to display new kernel data added to 64-bit applications support. The Kernel Debug Program on AIX 4.3 would now be able to handle all the 64-bit user addresses or data that are typed in on the command line wherever applicable.
The user address space ranges from 0x0 through 0x0FFFFFFFFFFFFFFF.

In AIX 4.3, though the kernel execution is always 32bit, it is possible that while in the Kernel Debug Program, the currently active process be a 64-bit program and the current execution mode is in Problem State. It is possible to enter such state (henceforth mentioned as 64-bit context) by invoking the debugger from the native or tty keyboard key sequence.

When the debugger is in 64-bit context, the display format of the screen would be different on AIX 4.3 in order to display 64-bit wide GPRs and other relevant 64-bit wide register contents.

The Kernel Debug Program on AIX 4.3 also supports debugging 64-bit real mode kernel code. The screen display format would be similar to that of the 64-bit context debug mode.

Use the kernel debug program (also known as the kernel debugger or low-level debugger) for debugging the kernel, device drivers, and other kernel extensions. The kernel debug program provides the following functions:

Loading and Starting the Kernel Debug Program

The kernel debug program must be loaded by using the bosboot command before it can be started. Use either of the following commands:

bosboot -a -d /dev/ipldevice -D


bosboot -a -d /dev/ipldevice -I

The -D flag causes the kernel debugger program to be loaded. The -I flag also causes the kernel debug program to be loaded, but it is also invoked at system initialization. This means that when the system starts, it will trap the kernel debug program.

After issuing the bosboot command, you must restart the machine. The kernel debug program will not be loaded until the system is restarted. When started, the debug program accepts the commands described in "Kernel Debug Program Commands".

If the kernel debug program is invoked during initialization, use the go command to continue the initialization process.

  1. The debug program disables all external interrupts while it is in operation.
  2. On AIX Version 4.1.4 systems (and later), it is no longer required that the key switch be in the service position to operate the kernel debugger. To debug the kernel program, use the bosboot command with the -D or -I flags. This change was instituted to allow use of the debugger on systems without a key.

Using a Terminal with the Kernel Debug Program

The debug program opens an asynchronous ASCII terminal when it is first started, and subsequently upon being started due to a system halt. Native serial ports are checked sequentially starting with port 0 (zero). Each port is configured at 9600 bps, 8 bits, and no parity. If carrier detect is asserted within 1/10 seconds, then the port is used. Otherwise, the next available native port is checked. This process continues until a port is opened or until every native port available on the machine has been checked. If no native serial port is opened successfully, then the result is unpredictable.

You can only display the kernel debugger on an ASCII terminal connected to a native serial port. The kernel debugger does not support any displays connected to any graphics adapters. The debugger has its own device driver for handling the display terminal. It is also possible to connect a serial line between two machines and define the serial line port as the port for the console. In that case, use the cu command to connect to the target machine and run the debugger.

Attention: If a serial device, other than a terminal connected to a native serial port, is selected by the kernel debugger, the system may appear to hang up.

Entering the Kernel Debug Program

It is possible to enter the kernel debug program using one of the following procedures:

If the kernel debug program is not available (nothing happens when you type in the above key sequence), you must load it. To do this, see "Loading and Starting the Kernel Debug Program".

Note: You can use the crash command to determine whether the kernel debug program is available. Use the od subcommand:
# crash
>od dbg_avail

If the od subcommand returns a 0 or 1, the kernel debug program is available. If it returns 2, the debug program is not available.

Debugging Multiprocessor Systems

On multiprocessor systems, entering the kernel debug program stops all processors (except the current processor running the debug program itself). Generally, when the debugger returns control to the program being debugged, other processors are released to run again. However, other processors are not released during the step command. On multiprocessor systems, the kernel debug program prompt indicates the current processor as follows:


where ProcessorNumber identifies the current processor.

Kernel Debug Program Concepts

When the kernel debugger is invoked, it is the only running program. All processes are stopped, interrupts are disabled, and the cache is flushed. The system creates a new mstsave (machine state save) area for use by the debugger. However, the data displayed by the debugger comes from the mstsave area of the thread that was interrupted when the debugger was entered. After exiting from the kernel debugger, all the processes will continue to run unless you entered the debugger through a system halt.

The data displayed by the debugger in 64-bit context comes from the mstsave64 area of the thread (of a 64-bit process) that was interrupted.


The kernel debug program must be loaded and started before it can accept commands

Once in the kernel debugger, use the commands to investigate and make alterations. Each command has an alias or a shortened form. This is the minimum number of letters required by the debugger to recognize the alias as unique. See "Kernel Debug Program Commands" for lists and descriptions of the commands.

Numeric Values and Strings

Numeric arguments are required to be hexadecimal for all commands except the loop and step commands and the slotnumber option of the drivers command, which all take a numeric count in decimal. Decimal numbers must either be decimal constants (0-9), variables, or expressions involving both options (see "Expressions"). Hexadecimal numbers can also include the letters A through F.

In some cases, only numeric constants are allowed. Wherever appropriate, this restriction is clearly identified.

On the other hand, a string is either a hexadecimal constant or a character constant of the form "String". Hexadecimal constants can be no longer than 8 digits. Double quotation marks separate string constants from other data.


Variable names must start with a letter and can be up to eight characters long. Variable names cannot contain special symbols. Variables usually represent locations or values which are used again and again. A variable must not represent a valid number. Use the set command to define and initialize variables. Variables can contain from 1 to 4 bytes of numeric data or up to 32 characters of string data. You can release a variable with the reset command. You cannot use the reset command with reserved variables.

For example:

set name 1234           Sets your variable called name=1234
set s8 820c00e0         Sets seg reg 8 to point to the IOCC

Note that s8 is a reserved variable.

Reserved Variables

There is a set of variables that have a reserved meaning for the kernel debug program. You can reference and change these variables, but they represent the actual hardware registers. There are also two variables (fx and org) reserved for use by the kernel debug program, which can be changed or set. If you change any registers while in the kernel debug program, the change remains in effect when you leave the kernel debug program. The reserved variables are:

asr Address space register
bat0l BAT register 0, lower.
bat0u BAT register 0, upper.
bat1l BAT register 1, lower.
bat1u BAT register 1, upper.
bat2l BAT register 2, lower.
bat2u BAT register 2, upper.
cppr Current processor priority register.
cr Condition register.
ctr Count register.
dar Data address register.
dec Decrementer.
dsier Data storage interrupt error register.
dsisr Data storage interrupt status register.
eim0 External interrupt mask (low).
eim1 External interrupt mask (high).
eis0 External interrupt summary (low).
eis1 External Interrupt summary (high).
fp0-fp31 Floating point registers 0 through 31.
fpscr Floating point status and control register.
fx Address of the last item found by the find command.
iar Instruction Address Register (program counter). Points to the current instruction.
lr Link register.
mq Multiply quotient.
msr Machine State register.
org The current value of origin. It is useful to set this to the program load point.
peis0 Pending external interrupt status register 0.
peis1 Pending external interrupt status register 1.
r0 - r31 General Purpose Registers 0 through 31. These registers have the following usage conventions:
r0 Used on prologs. Not preserved across calls.
r1 Stack pointer. Preserved across calls.
r2 TOC. Preserved across calls.
r3 - r10 Parameter list for a procedure call. The first argument is r3, the second is r4 and so on until r10 is the 8th argument. These registers are not preserved across calls.
r11 Scratch. Pointer to FCN; DSA pointer to int proc(env) .
r12 PL8 exception return. Value preserved across calls.
r13-r31 Scratch. Value preserved across calls.
rtcl Real Time clock (nano seconds).
rtcu Real Time clock (seconds).
s0-s15 Segment registers. If a segment register is not in use, it has a value of 007FFFFF.
sdr0 Storage description register 0.
sdr1 Storage description register 1.
sisr Data Storage-Interrupt Status register.
srr0 Machine status save/restore 0.
srr1 Machine status save/restore 1.
tbl Time base register, lower.
tbu Time base register, upper.
tid Transaction register (fixed point).
xer Exception register (fixed point).
xirr External interrupt request register.


The kernel debug program does not allow full expression processing. Expressions can only contain decimal or hex constants, variables and operators. The variable operators include:

+ addition
- subtraction
* multiplication
/ division
> dereference

The > operator indicates that the value of the preceding expression is to be taken as the address of the target value. The contents of the address specified by the evaluated expression are used in place of the expression.

You can enter expressions in the form Expression(Expression). This form causes the two expressions to be evaluated separately and then added together. This form is similar to the base address syntax used in the assembler.

You can also enter expressions in the form +Expression or -Expression. This form causes the expression to be added to or subtracted from the origin (the reserved variable org.)

Expressions are processed from left to right only. The type of data specified must be the same for all terms in the expression.

Pointer Dereferences

A pointer dereference can be used to refer indirectly to the contents of a memory location. For example, assume that the 0xC50 location contains a counter. An expression of the form c50> can be used to refer to the counter. Any expression can be placed before the > (greater than) operator, including an expression involving another > operator. In this case multiple levels of indirection are used. To extend the example, if the FF7 location contains the C50 value, the expression FF7>> refers to the above counter.

The following examples show how to use a pointer dereference with the alter command:

alter 124> 0582
alter addrl>+8 d96e

In the first case, data is placed into the memory location pointed to by the word at the 124 address. The second case places the d96e variable into memory at the address computed by adding 8 to the word at the address in the addrl variable.


The debugger creates a table of breakpoints that it internally maintains. The break command creates breakpoints. The clear command clears breakpoints. When the breakpoint is set, the debugger temporarily replaces the corresponding instruction with the trap instruction. The instruction overlaid by the breakpoint operates when you issue a step or go command.

A breakpoint can only be set if the instruction is not paged out. Breakpoints should not be set in any code used by the debugger.

For more information, see "Setting Breakpoints".

[ Previous | Next | Contents | Home | Search ]