Kernel Debug Program Commands

The following table shows the kernel debug program commands in alphabetical order:

Kernel Debug Program Commands Grouped by Task Categories

The kernel debug program commands can be grouped into the following task categories:

• Displaying Registers
• Modifying Registers
• Setting, Specifying, and Deleting Breakpoints
• Displaying Data
• Manipulating Memory
• Controlling the Debugger

Displaying Registers

Modifying Registers

Setting, Specifying, and Deleting Breakpoints

Displaying Data

Manipulating Memory

Controlling the Debugger

Descriptions of the Kernel Debug Program Commands

This includes a description of each of the kernel debug program commands. The commands are in alphabetical order.

alter Command for the Kernel Debug Program

Purpose

Alters a memory location to the hexadecimal value entered.

Syntax

Description

The alter command changes the memory location specified by the Address parameter to the hexadecimal value specified by the Data parameter. The alter command can be used to change one or several bytes of memory. The number of bytes modified with this command depends on the number of bytes you specified. If you specified an odd number of hexadecimal digits, only the first four bits of the last byte are changed.

The alter command cannot be used to modify storage to the value of a variable or an expression. Instead, use the st command, the stc command, or the sth command.

Examples

1. To store the 16-bit ffff value at the 1000 address, enter:

   alter 1000 ffff

2. To store the 8-bit 2C value in the high-order byte at the 1000 address, enter:

   a 1000 2C

back Command for the Kernel Debug Program

Purpose

Decreases the instruction address register (IAR).

Syntax

Description

The back command decreases the IAR by the number of bytes specified by the Number parameter and displays the new current instruction.

Examples

1. To decrement the IAR by 4 bytes, enter:

   back

2. To decrement the IAR by 16 bytes, enter:

   b 16

break Command for the Kernel Debug Program

Purpose

Sets a breakpoint.

Syntax

Description

The break command sets a breakpoint in a program at the address specified by the Address parameter. The Address parameter should be a hexadecimal expression. A breakpoint starts the loaded debug program when the instruction at the specified address is run.

There is a maximum of 32 breakpoints.

Examples

1. To set a breakpoint at the instruction address register (IAR), enter:

   break

2. To set a breakpoint at address 521A, enter:

   break 521a

3. To set a breakpoint at A0+8300, enter:

   br 8300+A0

4. To set a breakpoint at the origin plus A0, enter:

   break +A0

5. To set a breakpoint at the address in the link register, enter:

   break lr

breaks Command for the Kernel Debug Program

Purpose

Lists the current breakpoints, and the watchpoint.

Syntax

Description

The breaks command lists all currently active breakpoints. For each breakpoint, an offset into a segment is given along with the segment register value at the time the breakpoint was set. This information is required to distinguish between breakpoints set at identical offsets from different segment register values.

Following the list of breakpoints, a currently active watchpoint, an offset into a segment is given along with the segment register value and access value, namely load, store or both, at the time the watchpoint is set.

buckets Command for the Kernel Debug Program

Purpose

Displays statistics on the net_malloc kernel memory pool by bucket size.

Syntax

Description

The buckets command displays the contents of the kmembucket kernel structures. These structures contain information on the net_malloc memory pool by size of allocation.

All output values are printed in hexadecimal format.

This command can also be invoked via the alias, bu.

Example

To display kmembucket kernel structure for offset 0 and allocation size of 2 enter:

buckets

clear Command for the Kernel Debug Program

Purpose

Removes one or all breakpoints and the watchpoint.

Syntax

Description

The clear command removes one or all breakpoints, or a watchpoint. The Address parameter specifies the location of the breakpoint to be removed. If you specify no flags, the breakpoint pointed to by the instruction address register (IAR) is removed. The clear command can be initiated by entering clear , c , or cl at the command line.

Addresses are maintained as offsets from the start of their segment. In the event that two breakpoints are set at the same offset at the start of two different segments, and one breakpoint is then removed, the address specified to the clear command is not unique. In this case, each of the conflicting segment IDs are displayed, and the clear command displays a prompt requesting the ID of the segment whose breakpoint you want to remove.

The clear command, when specified with watch or w flag, clears the watchpoint.

Examples

1. To clear the breakpoint at the IAR, enter:

   clear

2. To clear the breakpoint at the 10000200 address, enter:

   cl 10000200

3. To clear all breakpoints, enter:

   clear *

4. To clear the watchpoint, enter:

   clear w

cpu Command for the Kernel Debug Program

Purpose

Switches the current processor, and reports the kernel debug state of processors.

Syntax

Description

The cpu command places the processor specified by the ProcessorNumber parameter in debug mode; the processor enters the debugger and is ready to accept commands. The processor where the debugger was previously running is stopped. This command is available only on multiprocessor systems.

If no processor is specified, the cpu command displays the kernel debug state of each processor. The possible states are as follows:

Example

To select the first processor, enter:

cpu 0

display Command for the Kernel Debug Program

Purpose

Displays a specified amount of memory.

Syntax

Description

The display command displays memory storage, starting at the address specified by the Address parameter. The Length parameter indicates the number of bytes to display, and has a default value of 16.

The display command displays the contents of the specified region of memory in a two-column format. The left column displays the contents of memory in hexadecimal, and the right column displays the printable ASCII representation of the hexadecimal data.

The display command also shows the exact amount of storage requested when you specify a length of 1, 2, or 4 bytes. In this instance, it uses the processor load character, load halfword, or load fullword instruction, respectively. These instructions should be used when displaying input and output address space. Any other value for the Length parameter causes memory to be loaded one byte at a time.

Examples

1. To display 16 bytes at the IAR , enter:

   display iar

2. To display 12 bytes at address 152F , enter:

   d 152F 12

3. To display 16 bytes at the origin + B7 , enter:

   display +B7

4. To display 16 bytes at the address in r3 , enter:

   disp r3

5. To display from the address contained in the address in r3 , enter:

   d r3>

dmodsw Command for the Kernel Debug Program

Purpose

Displays the internal STREAMS driver switch table.

Syntax

Description

The dmodsw command displays the internal STREAMS driver switch table, one entry at a time. By pressing the Enter key, you can walk through all the dmodsw entries in the table. The contents of the first entry are meaningless except for the d_next pointer. When the last entry has been reached, the dmodsw command will print the message, "This is the last entry. "

The information printed is contained in an internal structure. The following members of this internal structure are described here:

The flags structure member, if set, is based one of the following values:

#define           value  description
----------------  -----  ------------------------------------------
F_MODSW_OLD_OPEN    0x1  Supports old-style (V.3) open/close
                         parameters
F_MODSW_QSAFETY     0x2  Module requires safe timeout/bufcall
                         callbacks
F_MODSW_MPSAFE      0x4  Non-MP-Safe drivers need funneling

The synchronization level codes are described in the /usr/include/sys/strconf.h header file.

This command can also be invoked via the alias, dm.

drivers Command for the Kernel Debug Program

Purpose

Displays the contents of the device driver (devsw) table.

Syntax

Description

The drivers command displays the contents of the devsw table. If no parameters are specified, then each entry in the table is displayed. If a parameter is specified and is a valid slot number (less than 256), then the corresponding slot in the devsw table is displayed. If the parameter is not a valid slot number, then it is understood as an address and the slot with the last entry point prior to the given address is displayed, along with the name of that entry point.

Each devsw entry consists of a number of entry points (read, write, and so on) into the specified driver. Each entry consists of a function descriptor, and the address of the function.

Examples

1. To display the entire devsw table, enter:

   drivers

2. To display the tenth slot of the devsw table, enter:

   drivers 10

3. To display the last entry point before the address 0x130000F, enter:

   dr 130000f

find Command for the Kernel Debug Program

Purpose

Searches storage.

Syntax

Description

The find command searches storage for a pattern beginning at the address specified by the Address parameter. If the specified argument is found, the search stops and storage containing the specified argument is displayed. The address of the storage is placed into the fx variable.

The following defaults apply to the first execution of the find command:

• Address = 0

• EndAddress = 0x0FFFFFFFFFFFFFFF (for 64-bit process)
• EndAddress = 0xFFFFFFFF (for 32-bit process)
• Alignment = 1 (byte alignment)

An asterisk (*) can be substituted for any of the parameters. An asterisk causes the find command to use the value for that parameter that was used in the previous execution of the command.

Examples

1. To find the first occurrence of 7c81 in virtual memory starting at 0, enter:

   find 7c81

2. To find the first occurrence of the string TEST , enter:

   find "TEST"

3. To find the first occurrence of 7c81 after address 10000 , enter:

   f 7c81 10000

4. To find the first occurrence of 7c81 between 0 and the user-defined top variable, enter:

   f 7c81 0 top

5. To find the first occurrence of 7c81 starting at the last address used, enter:

   find 7c81 *

6. To find the first of occurrence of 7c81 starting at the last address used and aligned on a halfword, enter:

   f 7c81 * * 2

7. To find the next occurrence of 7c starting at 1 plus the last address at which the find command stopped, enter:

   f 7c fx+1 * 2

8. To search for the last pattern used, enter:

   find *

9. To search for the last pattern starting at the next location (the find command remembers the alignment which was used in the previous search), enter:

   f * fx+1

float Command for the Kernel Debug Program

Purpose

Displays floating-point registers.

Syntax

Description

The float command displays the contents of floating-point registers and other control registers.

In a 64-bit context, the segment register contents will not be displayed.

fmodsw Command for the Kernel Debug Program

Purpose

Displays the internal STREAMS module switch table.

Syntax

Description

The fmodsw command displays the internal STREAMS module switch table, one entry at a time. By pressing the Enter key, you can walk through all the fmodsw entries in the table. The contents of the first entry are meaningless except for the d_next pointer. When the last entry has been reached, the fmodsw command will print the message This is the last entry . This command can also be invoked via the alias, fm.

The information printed is contained in an internal structure. The following members of this internal structure are described here:

fs Command for the Kernel Debug Program

Purpose

Displays the internal file system tables.

Syntax

Description

The fs command displays the internal inode data structures, vnode data structures and vfs tables. If you specify no flags, the fs command displays a menu of commands.

The flags structure member, if set, is based one of the following values:

#define           value  description
----------------  -----  -------------------------------------------
F_MODSW_OLD_OPEN    0x1  Supports old-style (V.3) open/close
                         parameters
F_MODSW_QSAFETY     0x2  Module requires safe timeout/bufcall
                         callbacks
F_MODSW_MPSAFE      0x4  Non-MP-Safe drivers need funneling

The synchronization level codes are described in the /usr/include/sys/strconf.h header file.

go Command for the Kernel Debug Program

Purpose

Starts executing the program under test or generates a system dump.

Syntax

Description

The go command resumes operation of your program. Program operation begins at the current instruction address register (IAR) setting. Specify an address with the Address parameter to set the Instruction Address Register (IAR) to a new address and begin running there.

If you specify dump flag, the go command generates a system dump and the machine will halt.

Examples

1. To continue running your program at the IAR, enter:

   go

2. To set the IAR to 1000 and begin running there, enter:

   g 1000

help Command for the Kernel Debug Program

Purpose

Displays the help screen of the kernel debug program.

Syntax

Description

The help command displays a two-line help message for each debug program command. The first line gives the help message and the second line gives the syntax of that command. A list of commands or their alias names can be typed as parameters to the help command.

Example

To display the list of valid kernel debug program commands, enter:

help

To display the help messages for Break, Clear and Next commands, enter:

help br c next

loop Command for the Kernel Debug Program

Purpose

Runs the program being tested until the IAR reaches the current value several times.

Syntax

Description

The loop command causes the system to continue running and to stop when the instruction address register (IAR) returns to the current value the number of times specified by the Number parameter. All other breakpoints are ignored. The Number parameter specifies the number of loops that execute before the debug program regains control, and must be a valid decimal expression. The default value for the Number parameter is 1.

The loop command is similar to setting a breakpoint at the current IAR, but allows you to stop on a specified instance when the IAR returns to the current point.

Example

To execute until the second time the IAR has the current value, enter:

loop 2

map Command for the Kernel Debug Program

Purpose

Displays the system load list.

Syntax

Description

The map command displays information from the system load list. The system load list is the list of symbols exported from the kernel. If the map command is entered with no parameters, then the entire load list is displayed one page at a time. If an address is given, the name and value of the last symbol located before the given address is displayed. If a symbol name is given, then the load list is searched for the symbol and any matching entries are displayed. There can be more than one entry for a given symbol table.

Since the load list contains only symbols exported from the kernel, a given symbol name can be in the kernel but not reported by the map command.

The symbol value for a data structure is the address of that data structure. The symbol value for a function is not the address of the function, but the address of the function descriptor. The first word of the function descriptor is the address of the function. For example, if entering map execexit displays 0x1000 , then entering display 1000 displays the address of the execexit function in the first word of the displayed memory.

Examples

1. To display the entire load list, enter:

   map

2. To display the symbol with a value closest to 0xe3000000, enter:

   m e3000000

3. To display the value of the function execexit , enter:

   map execexit

mblk Command for the Kernel Debug Program

Purpose

Displays the contents of the STREAMS message blocks defined by the msgb structure in the /usr/include/sys/stream.h header file.

Syntax

Description

The mblk command displays the contents of the msgb structure that is defined in the /usr/include/sys/stream.h headerfile. If you do not specify an Address, the command displays the contents of the message blocks of type M_MBLK and M_MBDATA, as well as displays the address of mh_freelater.

The mh_freelater parameter is a pointer to the message blocks that are just now freed and are scheduled to be given back to the system, but are not yet given back.

All output values are printed in hexadecimal format.

This command can also be invoked via the alias, mb.

Examples

1. To display the contents of the message blocks of type M_BLK and M_MBDATA, and the address of mh_freelater, enter:

   mblk

2. To display the contents of the message block structure at address 0005ec80 , enter:

   mblk 0005ec80

mst64 Command for the Kernel Debug Program

Purpose

Displays the mstsave64 structure of a 64-bit process. It also displays the kernel remap structure containing all the remapped 64-bit user addresses.

Syntax

Description

The mst64 command displays the mstsave64 structure if you specify the thread id of any thread of a 64-bit process. With no parameter specified, the mstsave64 structure of the currently active thread of a 64-bit process is displayed. In addition, the kernel remap structure containing all the remapped 64-bit user addresses are displayed.

Examples

1. To display mstsave64 structure of a thread of a 64-bit process with thread id 205, enter:

   mst64 205

netdata Command for the Kernel Debug Program

Purpose

Displays the mbuf, ndd, socket, inpcb and tcpcb data structures.

Syntax

Description

The netdata or net command displays a menu of options to display one of the mbuf, ndd, socket, inpcb and tcpcb data structures, at the specified address.

next Command for the Kernel Debug Program

Purpose

Increases the instruction address register (IAR).

Syntax

Description

The next command increases the instruction address register (IAR) by the number specified by the Number parameter and displays the new current instruction. The default value for the Number parameter is 4 bytes.

Examples

1. To increment the IAR by 4 bytes, enter:

   next

2. To increment the IAR by 20 bytes, enter:

   n 20

origin Command for the Kernel Debug Program

Purpose

Sets the address origin of the instruction address register (IAR).

Syntax

Description

The origin command sets the address origin. The origin address specified by the Number parameter is added to any hexadecimal expression beginning with a + (plus sign). This command is especially useful when setting breakpoints. Use the screen command to display the value of the origin and the origin displacement of the IAR.

The origin command also sets the reserved org variable. For example, entering origin 652C0 does the same as entering set org 652C0 .

Examples

1. To set the origin to 178D, enter:

   origin 178D

2. To set the origin to 59cc, enter:

   o 59cc

ppd Command for the Kernel Debug Program

Purpose

Displays per-processor data.

Syntax

Description

The ppd command displays the per-processor data structure of the specified processor. If no argument is given, data for the current processor, as selected by the cpu command, is displayed.

Note: The ppd command is available only on multiprocessor systems.

Examples

1. To display per-processor data for the current processor, enter:

   ppd

2. To display per-processor data for processor 2, enter:

   ppd 2

proc Command for the Kernel Debug Program

Purpose

Displays the formatted process table.

Syntax

Description

The proc command displays the process table in a format similar to the output of the ps command, with an * (asterisk) placed next to the currently running process on the processor where the debugger is active . If the ProcessID (pid) parameter is specified, the proc command displays information pertaining to this process only, and gives more detailed information.

If you specify - flag, then sid, tty, pgrpl, ganchor fields of the proc table will be displayed. If you specify a string of flags of desired process states, then only the list of process that match the desired process states will be displayed.

A #(pound) is placed next to the process state column for all the 64-bit processes if any.

Flags

List of process states indicated by flags:

Examples

1. To display the process table, enter:

   p

2. To display the process table entry for the process with processID (pid) 1, enter:

   proc 1

3. To display some more detailed information still as table of entries, enter:

   proc - 

4. To display only the entries of active and zombie processes, enter:

   p "az"

queue Command for the Kernel Debug Program

Purpose

Displays the contents of the STREAMS queues.

Syntax

Description

The queue command displays the contents of the STREAMS queue at the specified Address. Refer to the /usr/include/sys/stream.h header file for the queue structure definition.

In the output, an X indicates that the value is printed in hexadecimal format.

This command can also be invoked via the alias, que.

Example

To display the contents of the STREAMS queue stored at address 59c1874 , where 59c1874 is a valid queue address, enter:

queue 59c1874

quit Command for the Kernel Debug Program

Purpose

Ends the debug program session.

Syntax

Description

The quit command terminates the debug session. Use this command when you have completed debugging and want to clear all breakpoints. The quit command performs the following tasks:

• Clears all breakpoints, and the watchpoint
• Issues the go command.

If you specify dump flag, the quit command generates a system dump and the machine will halt.

To use the debug program again after issuing the quit command, use one of the keyboard sequences described in "Entering the Kernel Debug Program".

reason Command for the Kernel Debug Program

Purpose

Displays the reason for entering the debugger.

Syntax

Description

The reason command displays the actual reason why the debugger was entered.

reboot Command for the Kernel Debug Program

Purpose

Reboots the machine.

Syntax

Description

The reboot command reboots the system, after getting confirmation from the user by an input prompt.

Note: The system cannot be rebooted using this command at boot-time debugger prompt.

reset Command for the Kernel Debug Program

Purpose

Clears a user-defined variable.

Syntax

Description

The reset command clears those variables specified with the VariableName parameter. Resetting a variable effectively deletes it, and allows the variable slot to be used again. Currently, 16 user-defined variables are allowed, and when they are all in use, you cannot set any more. Use the vars command to display all variables currently set.

Variables that are not user-defined, such as registers, cannot be reset. If you specify a variable that is not user-defined, or a variable that is not defined, an error message is displayed.

Example

To delete the user-defined variable foo, enter:

reset foo

screen Command for the Kernel Debug Program

Purpose

Displays a screen of data.

Syntax

Description

The screen command primarily displays memory and registers, but it is also used to control the format of subsequent screen commands. By default, memory is displayed starting at the instruction address register (IAR), or at the variable currently tracked. Variables can be tracked by specifying them with the track VariableName flag.

The track option changes the address that the screen displays as the expression that is being tracked changes. This option is useful in a case where, at a breakpoint, the memory to be displayed is addressed by a register.

You can also use parameters to modify the format of the screen so that only half of the physical screen is used, or even turn off the screen display entirely. The format modification parameters are useful if important information can be scrolled off the screen when the debugger is entered. Restore the default (full) screen by entering:

screen on

In 64-bit context, the screen command displays 64-bit wide GPRs and other control registers that exist only on 64-bit hardware. The memory display is limited. All screen operations remain same as before.

Flags

Examples

1. To display the next 112 bytes of data, enter:

   screen +

2. To display the previous 112 bytes of data, enter:

   screen -

3. To display memory starting at 20000FF7, enter:

   s 20000ff7

4. To display memory at the address contained in location 200, enter:

   s 200>

5. To turn on the display, enter:

   screen on

6. To turn off the display, enter:

   screen off

7. To set the display format to use about half of the screen, enter:

   screen on half

8. To track memory starting at the value in general purpose register 3, enter:

   sc track r3

segst64 Command for the Kernel Debug Program

Purpose

Displays the states of all memory segments of a 64-bit process.

Syntax

Description

The segst64 command displays the states of all the segments starting from the specified Esid (segment register). You can also specify Segflag parameter, with a string to identify the type of the segment (SEG_AVAIL_, SEG_MAPPED, etc.) and optionally either fileno or pointer to shared memory segment or srval, or segment attribute (attr) to uniquely locate the segment you are looking for. You will be prompted to specify ProcessID (pid) of a 64-bit process. You will also be prompted to specify starting Esid (segment register) if you do not specify it as a parameter. The currently active 64-bit process's ProcessID (pid) with starting register value of 3 would be the default. If no parameter was specified, the segst64 command displays states of all the segments of the currently active 64-bit process starting from segment register value 3.

Examples

1. To display the states of all the segments of the currently active 64-bit process starting from Esid (segment register) value 3.

   segst64

2. You will be prompted to specify the ProcessID (pid) and Esid (segment register). Press the Enter key at the prompt if you want to accept the default values.
3. To display states of all the segments in SEG_AVAIL, state, of the currently active 64-bit process starting from Esid (segment register) value 3, enter:

   seget64 -s "SEG_AVAIL"

   You will be prompted to specify the ProcessID (pid) and Esid (segment register). Press the Enter key at the prompt if you want to accept the default values.

4. To display states of all the segments in SEG_MAPPED state with fileno value of 1, of the currently active 64-bit process starting from Esid (segment register) value 3, enter:

   seg -s "SEG_MAPPED" 1

   You will be prompted to specify the ProcessID (pid) and Esid (segment register). Press the Enter key at the prompt if you want to accept the default values.

5. To display the states of all the segments of the currently active 64-bit process starting from Esid (segment register) value 257, enter:

   segst64 257

   You will be prompted to specify the ProcessID (pid). Press the Enter key at the prompt if you want to accept the default value.

set Command for the Kernel Debug Program

Purpose

Create and change values of debugger variables.

Syntax

Description

This command sets debugger variables. Use the set command to create new variables or modify the value of old variables. Certain debugger variables are symbolic names for machine registers, which you can modify. See "Reserved Variables" for a list of these variables.

An additional debugger variable asr has been introduced in AIX4.3. Also, in 64-bit context, you can set segment register values to all the possible segment registers ranging from 0 to FFFFFFFF, using a debugger variable sx<nnnnnnnn> (i.e., sx followed by segment register number). In 64-bit context, the segment registers are emulated in memory. An error message will be displayed if the assignment to the memory location is paged out.

The sr64 subcommand could be used to verify the srval just set to the sx<nnnnnnnn>register.

Note: The reset command cannot be used to release the sxnnnnnnnn debugger variable.

Examples

1. To assign value 100 to variable start.

   set start 100

2. To set general purpose register 12 to 0.

   set r12 0

3. To set segment register 3 to 10000.

   se s3  10000

4. To assign 45F0 to the Iar.

   set iar 45F0

5. To assign string "AIX" to variable name.

   se name "AIX"

6. To set segment register 257 to 10000

   set sx257 10000

sregs Command for the Kernel Debug Program

Purpose

Displays segment registers all times except in 64-bit context.

Syntax

Description

The sregs command displays the contents of the segment registers and other control registers. The display created is similar to that created by the screen command.

The screen display format changes in 64-bit context. If the debugger is in 64-bit context, then the segment registers will not be displayed. All GPRs and other control registers with 64-bits wide contents will be displayed.

Note: sr64 command must be used to look at the contents of the segment registers for a 64-bit process.

sr64 Command for the Kernel Debug Program

Purpose

Displays segment registers only in 64-bit context.

Syntax

Description

The sr64 command displays all the segment register values of a 64-bit process specified by a ProcessID (pid) parameter starting from specified Esid (segment register) parameter. The default Pid value process would be that of the currently active 64-bit process and the default Esid value would be zero. An error message will be displayed if either the specified process or the default currently active process is not a 64-bit process.

Examples

1. To display the segment registers of currently active 64-bit process, starting from esid (segment register number) 257, enter:

   sr64

2. To display the segment registers of a 64-bit process of pid 204, starting from Esid (segment register number) zero, enter:

   sr64 -p 204

3. To display the segment registers of a 64-bit process of pid 204, starting from Esid (segment register number) 257, enter:

   sr64 -p 204 257

st Command for the Kernel Debug Program

Purpose

Stores a fullword into memory.

Syntax

Description

The st command stores a fullword of data into memory by using the processor fullword store instruction. If the address specified by the Address parameter is not word-aligned, it is rounded down to a fullword. The st command is the correct way to place a fullword of data into input and output memory.

This is similar to the alter command, but the word size is implicit in the command. stc and sth are used to perform similar functions for bytes and halfwords.

Example

To store the 32-bit value 5 at address 1000 , enter:

st 1000 5

stack Command for the Kernel Debug Program

Purpose

Displays a formatted stack traceback.

Syntax

Description

The stack command displays a formatted kernel-stack traceback for the specified kernel thread. If no thread is specified, the currently running thread is used. Stack frames show return addresses and can be used to trace the calling sequence of the program. Be aware that the first few parameters are passed in registers to the called functions, and are not usually available on the stack. Generally only the stack chain (stacks back-chain pointer) and return address (address where the current function returns upon completion) are valid. To interpret the stack thoroughly, it is necessary to use an assembler language listing for a procedure to determine what has been stored on the stack. Stack frames for the specified thread are not always accessible.

Examples

1. To format any existing stack frames, enter:

   stack

2. To format stack frames for the thread with thread ID 251 enter:

   sta 
   251

stc Command for the Kernel Debug Program

Purpose

Stores one byte into memory.

Syntax

Description

The stc command stores a byte of data specified by the Data parameter into memory at the address specified by the Address parameter by using the processor store-character instruction. The stc command is the correct way to place a byte of data into input and output memory.

This is similar to the st and sth commands, which are used for fullwords and halfwords.

Example

To store the 8-bit value FF at address 1000 , enter:

stc 1000 ff

step Command for the Kernel Debug Program

Purpose

Runs instructions single-step.

Syntax

Description

The step command causes the processor to enter a single instruction and return control to the debug program. If a branch is the next instruction to be run, the s flag causes the processor to step over a subroutine call. An integer Number parameter is used as the number of instructions to run before returning control to the debug program.

Note: On multiprocessor systems, other processors are not released during step, contrary to most commands.

Flag

Examples

1. To single step the processor, enter:

   step

2. To single step and skip over a subroutine call, enter:

   step s

3. To step for 20 instructions, enter:

   step 20

sth Command for the Kernel Debug Program

Purpose

Stores a halfword into memory.

Syntax

Description

The sth command stores a halfword of data specified by the Data parameter into memory by using the processor store halfword instruction. If the address specified by the Address parameter is not halfword-aligned, it is rounded down to a halfword boundary. The sth command is the correct way to place a halfword into input and output memory space.

This is similar to the st and stc commands, which are used for fullwords and bytes.

Example

To store the 16-bit value 14 at address 1000 , enter:

sth 1000 0014

stream Command for the Kernel Debug Program

Purpose

Displays the contents of the stream head table.

Syntax

Description

The stream command displays the contents of the stream head table. If no address is specified, the command displays the first stream found in the STREAMS hash table. If the address is specified, the command displays the contents of the stream head stored at that address.

The information printed is contained in an internal structure. The following members of this internal structure are described here:

The read_mode and write_mode values are defined in the /usr/include/sys/stropts.h header file.

The read_error and write_error variables are integers defined in the /usr/include/sys/errno.h header file.

The flags structure member, if set, is based on combinations of the following values:

In the output, values marked with X are printed in hexadecimal format.

This command can also be invoked via the alias, str.

Examples

1. To display the first stream head found in the stream head table, enter:

   stream

2. To display the contents of the particular stream head located at address 59b2e00 (where 59b2e00 is a valid stream head address), enter:

   stream 59b2e00

swap Command for the Kernel Debug Program

Purpose

Switches to the specified RS-232 port.

Syntax

Description

The swap command allows control of the debug program to be transferred to another terminal. The Port parameter specifies which asynchronous tty port to transfer control. The swap command does not support returning to a port that was previously used.

Specify 0 for port 0 (s1) or 1 for port 1 (s2).

Ports must be configured the same as the port on which the debug program is currently running: 9600 baud, 8 data bits, no parity. The device attached to the port must respond with a carrier detect within 1/10 seconds or the command fails and control will not be transferred.

Example

To switch display to RS-232 port 1 , enter:

swap 1

sysinfo Command for the Kernel Debug Program

Purpose

Displays the system configuration information.

Syntax

Description

The sysinfo command displays the system configuration information such as the model, architecture and more details.

thread Command for the Kernel Debug Program

Purpose

Displays thread table entries.

Syntax

Description

The thread command displays the contents of the kernel thread table. If the ProcessID (pid) parameter is given, information about all kernel threads belonging to that process is displayed. If the ThreadID parameter is given, detailed information about the specified kernel thread is displayed. If no parameters are given, information about all kernel threads in the kernel thread table is displayed. Note that the ProcessID (pid) and ThreadID parameters share a common name space: even numbers are always used for ProcessIDs, whereas odd numbers are used for threads (the init processes, PID 1, is an exception).

If you specify a string of flags of desired thread states, then only the list of threads that match the desired threads states will be displayed.

Flags

List of process states indicated by flags:

Examples

1. To display information about all threads in the thread table, enter:

   thread

   The output is similar to:

   SLT ST TID  PID CPUID  POLICY PRI CPU  EVENT  
   PROCNAME      FLAGS
     0 s    3    0   ANY  OTHER  10  78          swapper  0x00001400
     1 s  103    1   ANY  OTHER  3C   0          init     0x00000400
     2*r  205  204     0  OTHER  7F  78          wait     0x00001000
     3 r  307  306     1  OTHER  7F  78          wait     0x00001000
     4 s  409  408   ANY  OTHER  24   0          netm     0x00001000
     5 s  50B  50A   ANY  OTHER  24   0          gil      0x00001000
     6 s  60D  50A   ANY  OTHER  24   0 000B2DA8 gil      0x00001000
     7 s  70F  50A   ANY  OTHER  24   0 000B2DA8 gil      0x00001000
     8 s  811  50A   ANY  OTHER  24   0 000B2DA8 gil      0x00001000
     9 s  913  50A   ANY  OTHER  24   1 000B2DA8 gil      0x00001000
    10 s  A15  60C   ANY  OTHER  3C   0          sh       0x00000400
    11 s  B17  70E   ANY  OTHER  3C   0          sh       0x00000400

2. To display information about the threads in process 2106, enter:

   th 2106

3. To display information about the thread with thread ID 1497, enter:

   th 1497

4. To display only the entries of sleeping and zombie threads, enter:

   th "sz"

   Note: All the flags must be entered as a single string.

trace Command for the Kernel Debug Program

Purpose

Displays formatted kernel trace buffers.

Syntax

Description

The trace command displays the last 128 entries of a kernel trace buffer in reverse chronological order. There are 8 trace buffers, each associated with a trace channel. Each can trace any combination of trace events. Trace data gives an indication of system activity at a very low level; interrupts, input/output, and process scheduling are examples of event types that can be traced.

The trace command displays headers for the trace buffers that contain pointers into the trace buffers and the state of the trace driver. Following this are the last 128 entries from the selected trace buffer. Trace entries consist of a major and a minor number for the trace hook, an ASCII trace ID, an ASCII trace hook type, followed by either a hexadecimal dump of the trace data or a pointer to the start of a variable-length block of trace data.

The trace command is not meant to replace the trcfmt command, which formats the trace data in more detail. It is a facility for viewing system trace data in the event of a system crash before the data has been written to disk.

Flags

Examples

1. To display a sequence of trace entries, enter:

   trace

   The system then returns the following question:

   Display channel (0 - 8): 0

2. To display a sequence of trace entries with hookword 105 , enter:

   trace 105 -c 0

3. To display a sequence of trace entries with hookword 105 and subhook d , enter:

   trace 105:d -c 0

4. To display all entries with hookword 105 or 10b , enter:

   trace 105 10b

5. To display all entries with hookword 105 and a 300 in the trace data, enter:

   trace 105 #300

6. To display the trace headers, enter:

   trace -h

trb Command for the Kernel Debug Program

Purpose

Displays the timer request blocks (TRBs).

Syntax

Description

The trb command displays a menu of commands to display timer request block (TRB) information.

The trb command allows you to traverse the active and free TRB chains; examine TRBs by process, slot number, or address; and examine the clock interrupt handler information.

tty Command for the Kernel Debug Program

Purpose

Displays the tty structure.

Syntax

Description

The tty command displays tty data structures. If no parameters are specified, a verbose listing of all terminals is displayed. Short forms of the listings can be requested showing all terminals or all currently open terminals. If no parameters are specified, a short listing of all opened terminals is displayed. Selected terminals can be displayed by specifying the terminal name in the Name parameter, such as tty1, or a major device number with optional minor and channel numbers. If the Major parameter is specified, all terminals with the specified major number are listed. If the Major and Minor parameters are both specified, all the terminals with both the specified major and minor numbers are is listed.

Selected type of information can be displayed, according to the specified flags.

Flags

Examples

1. To display listings for each open terminal, enter:

   tty

2. To display the driver and line disicipline information for terminal tty1, enter:

   tty d l tty1

3. To display the listing for the terminal with a major number 7 and a minor number 1, enter:

   tty 7 1

un Command for the Kernel Debug Program

Purpose

Displays the assembly instruction(s).

Syntax

Description

The un command disassembles the contents starting at the address specified by the Addr parameter and displays the assembly instructions. The Size parameter indicates the number of instructions to be displayed and has a default value of 1.

Examples

1. To disassemble and display the instruction at the address 1000, enter:

   un 1000

2. To disassemble and display 5 instructions starting at 1000, enter:

   un 1000 5

user Command for the Kernel Debug Program

Purpose

Displays the U-area (user area).

Syntax

Description

The user command with * parameter, displays the U-area for the current process. With a long flag specified, the user command displays more details of the U-area displayed. If the U-area is being displayed for a 64-bit process, a message will be displayed to indicate so.

Examples

1. To display the current U-area, enter:

   user

2. To display the U-area for the process with ProcessID 314, enter:

   u 314

3. To display U-area of currently active process, enter:

   u *

4. To display U-area of a process with ProcessID (pid) 204, giving more details, enter:

   u 204 long

user64 Command for the Kernel Debug Program

Purpose

Displays the user64 structure of a 64-bit process.

Syntax

Description

The user64 command displays the user64 structure if you specify the processID (pid) of a 64-bit process. With no parameter specified, the user64 structure of the currently active 64-bit process is displayed.

Examples

1. To display user64 structure of a 64-bit process with processID (pid) 204, enter:

   user64 204

uthread Command for the Kernel Debug Program

Purpose

Displays the uthread structure.

Syntax

Description

The uthread command displays uthread structures. If the ThreadID parameter is given, the uthread structure of the specified kernel thread is displayed. Otherwise, the uthread structure of the current kernel thread is displayed.

If the uthread is being displayed for thread of a 64-bit process, a message will be displayed to indicate so. In 64-bit context, the segment registers will not be displayed and GPRs contents displayed will be 64 bits wide.

Examples

1. To display the uthread structure of the current kernel thread, enter:

   uthread

   The output is similar to:

   using current thread:
   UTHREAD AREA FOR TID 0x00000205
   SAVED MACHINE STATE
       curid:0x00000204  m/q:0x00000000  iar:0x000214D4  cr:0x24000000
       msr:0x00009030  lr:0x00021504  ctr:0x0002147C  xer:0x20000000
       *prevmst:0x00000000  *stackfix:0x00000000  intpri:0x0000000B
       backtrace:0x00  tid:0x00000000  fpeu:0x00  ecr:0x00000000
       Exception Struct
         0x00000000  0x00000000  0x00000000  0x00000000  0x00000000
       Segment Regs
        0:0x00000000   1:0x007FFFFF   2:0x00000408   3:0x007FFFFF
        4:0x007FFFFF   5:0x007FFFFF   6:0x007FFFFF   7:0x007FFFFF
        8:0x007FFFFF   9:0x007FFFFF  10:0x007FFFFF  11:0x007FFFFF
       12:0x007FFFFF  13:0x007FFFFF  14:0x00000204  15:0x007FFFFF
       General Purpose Regs
        0:0x00000000   1:0x2FEAEF38   2:0x00270314   3:0x00000054
        4:0x00000002   5:0x00000000   6:0x000BF9B8   7:0x00000000
        8:0xDEADBEEF   9:0xDEADBEEF  10:0xDEADBEEF  11:0x00000000
       12:0x00009030  13:0xDEADBEEF  14:0xDEADBEEF  15:0xDEADBEEF
       16:0xDEADBEEF  17:0xDEADBEEF  18:0xDEADBEEF  19:0xDEADBEEF
       20:0xDEADBEEF  21:0xDEADBEEF  22:0xDEADBEEF  23:0xDEADBEEF
       24:0xDEADBEEF  25:0xDEADBEEF  26:0xDEADBEEF  27:0xDEADBEEF
       28:0xDEADBEEF  29:0xDEADBEEF  30:0xDEADBEEF  31:0xDEADBEEF
       Press "ENTER" to continue, or "x" to exit:>0>
   Floating Point Regs
           Fpscr: 0x00000000
        0:0x00000000 0x00000000  1:0x00000000 0x00000000  2:0x00000000 0x00000000
        3:0x00000000 0x00000000  4:0x00000000 0x00000000  5:0x00000000 0x00000000
        6:0x00000000 0x00000000  7:0x00000000 0x00000000  8:0x00000000 0x00000000
        9:0x00000000 0x00000000 10:0x00000000 0x00000000 11:0x00000000 0x00000000
       12:0x00000000 0x00000000 13:0x00000000 0x00000000 14:0x00000000 0x00000000
       15:0x00000000 0x00000000 16:0x00000000 0x00000000 17:0x00000000 0x00000000
       18:0x00000000 0x00000000 19:0x00000000 0x00000000 20:0x00000000 0x00000000
       21:0x00000000 0x00000000 22:0x00000000 0x00000000 23:0x00000000 0x00000000
       24:0x00000000 0x00000000 25:0x00000000 0x00000000 26:0x00000000 0x00000000
       27:0x00000000 0x00000000 28:0x00000000 0x00000000 29:0x00000000 0x00000000
       30:0x00000000 0x00000000 31:0x00000000 0x00000000
      
   Kernel stack address: 0x2FEAEFFC
   Press "ENTER" to continue, or "x" to exit:>0>
       
   SYSTEM CALL STATE
   7    user stack:0x00000000  user msr:0x00000000
       errno address:0xC0C0FADE  error code:0x00  *kjmpbuf:0x00000000
     ut_flags:
            
   PER-THREAD TIMER MANAGEMENT
       Real/Alarm Timer (ut_timer.t_trb[TIMERID_ALRM]) = 0x0
       Virtual Timer (ut_timer.t_trb[TIMERID_VIRTUAL]) = 0x0
       Prof Timer (ut_timer.t_trb[TIMERID_PROF]) = 0x0
       Posix Timer (ut_timer.t_trb[POSIX4]) = 0x0
               
                
              
             
              
               
                 
   SIGNAL MANAGEMENT
            
       *sigsp:0x0  oldmask:hi 0x0,lo 0x0  code:0x0
   Press "ENTER" to continue, or "x" to exit:>0>
                
   Miscellaneous fields:
      fstid:0x00000000   ioctlrv:0x00000000   selchn:0x00000000
   Uthread area printout terminated.

2. To display the uthread structure of the kernel thread with thread ID 1497, enter:

   ut 1497

vars Command for the Kernel Debug Program

Purpose

Displays a list of user-defined variables.

Syntax

Description

The vars command displays the user-defined variables and their values.

The command displays the variable name and value, and an indication of what is the base of the value. Since the value 10 can be either decimal or hexadecimal it is displayed as HEX/DEC . The command displays string variables with no quotes around the string value.

The values of the reserved variables fx and org are also displayed.

vmm Command for the Kernel Debug Program

Purpose

Displays the virtual memory information menu.

Syntax

Description

The vmm command displays a menu of commands for displaying the virtual memory data structures. These commands examine segment register values for kernel segments such as the ram disk and the page space disk maps. Addresses and sizes of VMM data structures are also available, as are VMM statistics such as the number of page faults and the number of pages paged in or out.

The stab contents could be displayed using one of vmm menu commands, for a 64-bit process.

Watch Command for the Kernel Debug Program

Purpose

Watches for load and/or store at an address.

Syntax

Description

The watch command allows you to enter the debugger if and when there is a load and/or store at an address that you specify. The optional flag l or load indicates that load is to be detected, s or store indicates that store is to be detected. With no flag specified, either load or store will be detected by the debugger. Since the watch command is only available on some hardware, check the hardware thechnical reference information to see if this is available on your system.

Example

1. To enter the debugger once the address 1000 is loaded (read):

   watch l 1000

2. To enter the debugger once the address 1000 is either loaded (read) or stored (written) with some value:

   watch 1000

xlate Command for the Kernel Debug Program

Purpose

Translates a virtual address to a real address.

Syntax

Description

The xlate command displays the real address corresponding to the specified virtual address.

Example

To display the real address corresponding to the virtual address 10054000 , enter:

xlate 10054000
10054000 -virtual- 00000000_000EF004 -real-

00000000_000EF004 is the corresponding real address. The real address is displayed 64 bits wide, since AIX 4.3 supports real memory greater than 4GB on 64-bit systems.