Revision as of 13:41, 9 January 2009 by Keesj (talk | contribs) (Build OpenOCD)
Jump to: navigation, search

This page is about how to use open source OpenOCD JTAG software with BeagleBoard. With this, it will be possible to have OMAP3 JTAG debug using cheap JTAG hardware, e.g. Flyswatter.

As of December 2008, OpenOCD doesn't work with Beagle Board (ARM Cortex A8, OMAP3). OpenOCD support is work in progress. This section tries to cover the recent status to

  • give everybody the steps to recent status in case they want to help
  • be ready if support is ready

OpenOCD JTAG bring up

On IRC it was discussed what will be Add Cortex-A8 CPU ID. Currently only Cortex-M3 is supported. Take this as example. Once you connect to target you should get error message expect cpuid of xxxxxx but got yyyyyy which should contain Cortex-A8 CPU ID.

  • Take CPU scan lengths from OMAP3530 CCS config.
  • Regarding EMU0/EMU1 pins on BeagleBoard, pulling both pins down does currently not make Cortex-A8 CPU accessible. Only one TAP is visible (ICEPick). Therefore OpenOCD will not be able to validate the scan chain. The documentation for the control of EMU0/EMU1 is very misleading:
0 0 ICEPick + default TAP(s)
0 1 ICEPick Reserved
1 0 ICEPick Wait-in-reset
1 1 ICEPick Default condition
NOTES: ICEPick is always in the scan chain
Default TAPs are the ARM and the ETB

This table is identical to the Davinci documentation, with one BIG difference:

  • The OMAP3xx has NO default TAP (ARM or ETB taps) which means that the configuration of EMU0-L/EMU1-L doesn't add ARM to scan chain (above table is wrong, though).

The OMAP3xx uses a TAP router, it needs to be programmed with the information about available TAPS first, before ARM is accessible. Once the DAP has been added to the TAP router, via a programming sequence, the ARM core can be accessed.

TI has a good presentation describing the functionality of the ICEPick TAP Router (or generically refered to as JTAG Route Controller or JRC). The ICEPick jtag device ID is 0x0b73b02f (Manufacturer: 0x017, Part: 0xb73b, Version: 0x0) and is the same as the Davinci series.

It may still be possible to use the EMU0-L/EMU1-L configuration, but with consideration that the TAP router will already configured for with the arm core interface. Yet to be tested.

If above basics work, additionally MMU, cache support and some include files for A8 might be added to OpenOCD.

Note: If you made some progress regarding BeagleBoard OpenOCD support, please send a short note to BeagleBoard ML and OpenOCD ML.

Status December 2008:

  • Status mail at OpenOCD mailing list.
  • There is some discussion how to extend OpenOCD to support JRC configuration (see thread JTAG emulator with openocd for beagleboard).

Build OpenOCD

OpenOCD build instructions describe how to build OpenOCD. For questions you can use OpenOCD Mailing list.

Get OpenOCD code via svn:

> svn checkout svn:// openocd

For Flyswatter you additionally need libftd2xx or libFTDI. While libFTDI is available in source, libftd2xx is supposed to be 50% faster than libFTDI. The libtfd2xx binaries are available booth as shared library or linkable archive.

If you downloaded OpenOCD svn and have libftd2xx or libFTDI, build OpenOCD (assuming you extracted/built FTDI library already):

> cd openocd
> ./bootstrap
> ./configure --enable-ft2232_ftd2xx --with-ftd2xx-linux-tardir=<path_to>/libftd2xx0.4.16 --prefix=/home/user/bin/openOCD
or (depending which FTDI library you use, see above)
> ./configure --enable-ft2232_libftdi --prefix=/home/user/bin/openOCD
> make
> make install

Note: By default (make & make install) only .info documentation is installed. You can get PDF or HTML documentation by

make pdf


make html

Resulting documentation can be found in openocd/doc, then.

Note: If you like to save some disk space and don't plan to debug OpenOCD binary itself, you can strip this (remove unneeded debug symbols):

> cd <openocd_install_dir>/bin
> strip openocd

(e.g. with OpenOCD 1.0 this reduced binary size from ~3MB to ~700kB)

Note: If you don't have libftdi in standard path, you might like to extend library search path:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path_to>/lib

if you e.g. get

> ./openocd
./openocd: error while loading shared libraries: cannot open shared object file: No such file or directory

Beagle configuration file

OpenOCD runtime is controlled by several configuration files. I.e. main configuration file (openocd.cfg) calling ("source") various sub configurations. For Beagle, in directory where you start openocd create a file openocd.cfg (assuming you use Flyswatter):

#File openocd.cfg
#Basic configuration
telnet_port 4444
gdb_port 3333

source [find interface/flyswatter.cfg]

#jtag scan chain
source [find target/omap3530.cfg]

and a file omap3530.cfg:

#File omap3530.cfg
#TI OMAP3530 processor - 

if { [info exists CHIPNAME] } {	
} else {	 
   set  _CHIPNAME omap3530

if { [info exists ENDIAN] } {	
   set  _ENDIAN $ENDIAN    
} else {	 
  # this defaults to a little endianness
  set  _ENDIAN little

if { [info exists CPUTAPID ] } {
} else {
  # force an error till we get a good number
  set _CPUTAPID 0xffffffff

#jtag scan chain
jtag newtap $_CHIPNAME jrc -irlen 6 -ircapture 0x1 -irmask 0xf -expected-id 0x0b7ae02f
jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0x0 -expected-id $_CPUTAPID -disable

jtag configure $_CHIPNAME.cpu -event tap-enable {
	puts "Enabling Cortex-A8 @ OMAP3"
	irscan omap3530.jrc 7
	drscan omap3530.jrc 8 0x89
	irscan omap3530.jrc 2
	drscan omap3530.jrc 32 0x81000080
	drscan omap3530.jrc 32 0xa3002048
	drscan omap3530.jrc 32 0x81002148
	drscan omap3530.jrc 32 0xa3002148
	runtest 10
	puts "Cortex-A8 @ OMAP3 enabled"

Interface configuration file flyswatter.cfg is part of OpenOCD source.

Assuming you

  • have a omap3530.cfg in target directory
  • have Flyswatter switched on (attached to USB)
  • have openocd.cfg in the directory you start openocd from

you can now start openocd with

openocd -s <path_to_config_files> // e.g. <patch_of_openocd_install_dir>/lib/openocd

This should result in

> openocd -s lib/openocd/

Open On-Chip Debugger 1.0 (2008-12-19-17:38) svn:1261

BUGS? Read

$URL: svn:// $
jtag_speed: 1
Info:   JTAG tap: omap3530.jrc tap/device found: 0x0b7ae02f (Manufacturer: 0x017, Part: 0xb7ae, Version: 0x0)
Info:   JTAG Tap/device matched
Warning:no gdb ports allocated as no target has been specified
Warning:no tcl port specified, using default port 6666

This shows that your (Flyswatter) JTAG dongle basically works and that you are able to see OMAP3 JRC. OpenOCD now runs as deamon.

Controlling OpenOCD

Once OpenOCD runs as daemon like above, you can connect using telnet or GDB


Connect to OpenOCD daemon. Assuming you do it on your local machine, open a second terminal window and do (assuming port 4444 as configured in above openocd.cfg):

> telnet localhost 4444
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger

This should give you

Info:   accepting 'telnet' connection from 0

in window where OpenOCD daemon is started.

At OpenOCDs telnet prompt you can now issue OpenOCD commands. E.g. help should result in

> help
cpu                       <name> - prints out target options and a comment
                          on CPU which matches name
debug_level               adjust debug level <0-3>
drscan                    execute DR scan <device> <num_bits> <value>
                          <num_bits1> <value2> ...
endstate                  finish JTAG operations in <tap_state>
exit                      exit telnet session
fast                      fast <enable/disable> - place at beginning of
                          config files. Sets defaults to fast and dangerous.
fast_load                 loads active fast load image to current target -
                          mainly for profiling purposes
fast_load_image           same args as load_image, image stored in memory -
                          mainly for profiling purposes
find                      <file> - print full path to file according to
                          OpenOCD search rules
ft2232_device_desc        the USB device description of the FTDI FT2232
ft2232_latency            set the FT2232 latency timer to a new value
ft2232_layout             the layout of the FT2232 GPIO signals used to
                          control output-enables and reset signals
ft2232_serial             the serial number of the FTDI FT2232 device
ft2232_vid_pid            the vendor ID and product ID of the FTDI FT2232
gdb_breakpoint_override   hard/soft/disabled - force breakpoint type for gdb
                          'break' commands.The raison d'etre for this option
                          is to support GDB GUI's without a hard/soft
                          breakpoint concept where the default OpenOCD
                          behaviour is not sufficient
gdb_flash_program         enable or disable flash program
gdb_memory_map            enable or disable memory map
gdb_port                  daemon configuration command gdb_port
gdb_report_data_abort     enable or disable report data
help                      Tcl implementation of help command
init                      initializes target and servers - nop on subsequent
interface                 try to configure interface
irscan                    execute IR scan <device> <instr> [dev2] [instr2]
jtag                      perform jtag tap actions
jtag_device               jtag_device <ir_length> <ir_expected> <ir_mask>
jtag_khz                  same as jtag_speed, except it takes maximum khz as
                          arguments. 0 KHz = RTCK.
jtag_nsrst_delay          jtag_nsrst_delay <ms> - delay after deasserting
                          srst in ms
jtag_ntrst_delay          jtag_ntrst_delay <ms> - delay after deasserting
                          trst in ms
jtag_rclk                 fallback_speed_khz - set JTAG speed to RCLK or use
                          fallback speed
jtag_reset                toggle reset lines <trst> <srst>
jtag_speed                set jtag speed (if supported)
log_output                redirect logging to <file> (default: stderr)
ocd_array2mem             convert a TCL array to memory locations and write
                          the values
ocd_flash_banks           return information about the flash banks
ocd_mem2array             read memory and return as a TCL array for script
power_restore             Overridable procedure run when power restore is
                          detected. Runs 'reset init' by default.
production                <serialnumber> - Runs production procedure. Throws
                          exception if procedure failed. Prints progress
                          messages. Implement this procedure in the target
production                Runs test procedure. Throws exception if procedure
                          failed. Prints progress messages. Implement in
                          target script.
production_info           Displays information on production procedure for
                          target script. Implement this procedure in target
profile                   profiling samples the CPU PC
runtest                   move to Run-Test/Idle, and execute <num_cycles>
scan_chain                print current scan chain configuration
script                    <filename> - filename of OpenOCD script (tcl) to
shutdown                  shut the server down
sleep                     <n> [busy] - sleep for n milliseconds. "busy"
                          means busy wait
srst_deasserted           Overridable procedure run when srst deassert is
                          detected. Runs 'reset init' by default.
target                    configure target
targets                   change the current command line target (one
                          parameter) or lists targets (with no parameter)
tcl_port                  port on which to listen for incoming TCL syntax
telnet_port               port on which to listen for incoming telnet
verify_ircapture          verify value captured during Capture-IR
version                   show OpenOCD version
virt2phys                 translate a virtual address into a physical
xsvf                      run xsvf <file>
flash bank                flash bank <driver> <base> <size> <chip_width>
                          <bus_width> <target> [driver_options ...]
mflash bank               mflash bank <soc> <base> <chip_width> <bus_width>                               
                          <RST pin> <WP pin> <DPD pin> <target #>
nand device
pld device

Now, we can try to print recent OMAP3 scan chain configuration and enable Cortex-A8 manually (by configuring JRC):

> scan_chain
    TapName            | Enabled |   IdCode      Expected    IrLen IrCap  IrMask Instr
 0 | omap3530.jrc       |    Y    | 0x0b7ae02f | 0x0b7ae02f | 0x06 | 0x01 | 0x0f | 0x3f
 1 | omap3530.cpu       |    n    | 0x00000000 | 0xffffffff | 0x04 | 0x01 | 0x00 | 0x0f

> jtag tapenable omap3530.cpu
Enabling Cortex-A8 @ OMAP3
Cortex-A8 @ OMAP3 enabled
> scan_chain
     TapName            | Enabled |   IdCode      Expected    IrLen IrCap  IrMask Instr
 0 | omap3530.jrc       |    Y    | 0x0b7ae02f | 0x0b7ae02f | 0x06 | 0x01 | 0x0f | 0x3f
 1 | omap3530.cpu       |    Y    | 0x00000000 | 0xffffffff | 0x04 | 0x01 | 0x00 | 0x0f




To debug an ARM target with GNU debugger (GDB), you need a GDB understanding ARM processor. If your ARM cross compilation tool chain doesn't include a GDB, you can easily build it your self.

  • Download latest GDB sources. OpenOCD docu recommends to use GDB 6.7 or newer. Here, we use GDB 6.8 which is the recent version while writing this.
  • Extract, configure and build GDB for ARM. Afterwards remove temporary stuff. Options are:
    • <path_where_ARM_gdb_shall_be_installed_to> : Directory where you want to install the resulting tool to. E.g. /home/user/arm-gdb/
    • <ARM_toolchain_prefix> : The prefix of your ARM GCC toolchain, e.g. arm-linux or arm-none-linux-gnueabi (CodeSourcery tool chain).
> tar xfj gdb-6.8.tar.bz2
> mkdir build-gdb
> cd build-gdb/
build-gdb > ../gdb-6.8/configure --prefix=<path_where_ARM_gdb_shall_be_installed_to> --target=<ARM_toolchain_prefix> i686-pc-linux-gnu
build-gdb > make -j4
build-gdb > make install
build-gdb > cd ..
> rm -rf gdb-6.8 build-gdb
> export PATH=$PATH:<path_where_ARM_gdb_shall_be_installed_to>/bin


bin> ./arm-none-linux-gnueabi-gdb
GNU gdb 6.8
Copyright (C) 2008 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=arm-none-linux-gnueabi".