How To Debug a Linux Kernel with the BDI2000 and BDI 3000 JTAG from the Command Line

This document describes how to use the Abatron BDI2000 and BDI3000 on-chip debugging device from a command-line interface to debug a Linux kernel. The BDI2000 and BDI3000 connect to the board by using the JTAG interface.

You can follow this basic procedure to debug your kernel with the BDI without using the TimeStorm integrated development environment.

Tip:

JTAG-based debugging is also supported in the TimeStorm integrated development environment.

Prepare and build your kernel as usual, ensuring that kernel debugging options are enabled in your kernel configuration (look in the Kernel Hacking section of the kernel configuration for useful tools). Transfer the kernel to the board if you are booting the kernel directly, or to the TFTP server if you are using TFTP to boot the board.

Refer to the BDI documentation for details about how to connect the BDI to your target board and host system.

To start your debugging session, follow these steps:

Rename the vmlinux file. Typically, this file is stored in the top level of your kernel source directory (that is, kernel/). Any filename other than vmlinux is acceptable.

The vmlinux file is a statically linked executable file that is written to the kernel source directory before the final kernel image is created. To debug a kernel, you pass the vmlinux file to GDB as the “program” to debug. (See Step 5 for details.) This method allows GDB to correlate the running kernel with the kernel source code.

However, when GDB is told to debug a program named vmlinux, it attempts to use the KGDB kernel debugging interface. The BDI does not support KGDB; it requires regular GDB commands. Changing the vmlinux filename avoids this problem.

Because a new vmlinux file is created with every build, you must repeat this step each time you rebuild the kernel.
Find a suitable breakpoint inside the kernel. Timesys recommends using the start_kernel symbol, because it occurs early in the boot process but after the memory map has been set up. To find this symbol, search the System.map file in your kernel’s root directory for the proper hexadecimal address:
```
# grep start_kernel System.map
c00085d4 T start_kernel
```
In this example, the start_kernel breakpoint address is 0xc00085d4.
Boot the board with the BDI. Follow these general steps – they are specifically for an EP8260 board, but the procedures will work with some minor changes on all boards.
1. Open a serial console connection to the board.
2. Telnet to the BDI.
3. On the BDI Telnet session: Issue the “go” command:
```
 go
```
4. On the target serial console: Transfer the kernel to the bootloader and answer the questions presented:
```
 tftp 
```
5. On the BDI Telnet session: Stop the board using the debugger and issue a breakpoint at the kernel start:
```
 halt
 bi 0xc00085d4
```
6. On the BDI Telnet session: Start the board again using the debugger:
```
 go
```
7. On the target serial console: Use the “go” command to boot the kernel:
```
 go
```
  The bootloader will load the kernel and stop at the breakpoint.
8. On the BDI Telnet session: Clear the breakpoint in the debugger:
```
 ci
```

At this point, the debugger is connected and the kernel is loaded, but the board has been stopped.

Start the version of GDB that corresponds to your target system (it is part of the toolchain).
```
$ /opt/timesys/toolchains/ppc85xx/bin/ppc85xx-gdb
```
In the GDB console, specify the location of the renamed vmlinux file. (As noted earlier, you must change the vmlinux file to another name to avoid GDB/KGDB compatibility problems with the BDI. Any other name – for example, vmlinux1 or really_vmlinux – is acceptable.)
```
 file <path_to_vmlinux> 
```
This specifies the renamed vmlinux file as the “program” to be debugged.

For <path_to_vmlinux>, use either the absolute or relative path to the renamed vmlinux file. Typically, this file is found in the top level of the kernel source directory (that is, kernel/) after a build.

For example, if you renamed the vmlinux file as vmlinux1, give GDB a command like the following:
```
file /home/user/kernel_project/vmlinux1     
```
In the GDB console, specify the Ethernet address and port of the BDI.
```
target remote <IP_address>:<port>
```
Replace <IP_address> and <port> with the actual host and port where your BDI is connected. For example:
```
target remote 192.168.99.118:2001
```

For additional information about configuring and using GDB, consult the GDB online documentation: http://sourceware.org/gdb/current/onlinedocs/gdb.html