BeagleBoardOpenOCD

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 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.
 * 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).

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://svn.berlios.de/openocd/trunk 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=/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

or

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 /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:/lib

if you e.g. get

> ./openocd ./openocd: error while loading shared libraries: libftdi.so.1: 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):

telnet_port 4444 gdb_port 3333 source [find interface/flyswatter.cfg] source [find target/omap3530.cfg]
 * 1) File openocd.cfg
 * 2) Basic configuration
 * 1) Interface
 * 1) jtag scan chain

and a file omap3530.cfg:

if { [info exists CHIPNAME] } { set _CHIPNAME $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 ] } { set _CPUTAPID $CPUTAPID } else { # force an error till we get a good number set _CPUTAPID 0xffffffff } 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" }
 * 1) File omap3530.cfg
 * 2) TI OMAP3530 processor - http://www.ti.com
 * 1) jtag scan chain

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

=Starting OpenOCD=

Assuming you you can now start OpenOCD with
 * have a omap3530.cfg in target directory
 * have Flyswatter switched on (attached to USB)
 * have openocd.cfg in the directory you start openocd from

openocd -s  // e.g. /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 http://svn.berlios.de/svnroot/repos/openocd/trunk/BUGS $URL: svn://svn.berlios.de/openocd/trunk/src/openocd.c $ 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

telnet
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 Trying 127.0.0.1... 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                      - prints out target options and a comment on CPU which matches name debug_level              adjust debug level <0-3> drscan                   execute DR scan   ... endstate                 finish JTAG operations in  exit                     exit telnet session fast                     fast  - 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                     - print full path to file according to                           OpenOCD search rules ft2232_device_desc       the USB device description of the FTDI FT2232 device 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 device 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_detach 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 invocations interface                try to configure interface irscan                   execute IR scan  [dev2] [instr2] ... jtag                     perform jtag tap actions jtag_device              jtag_device    jtag_khz                 same as jtag_speed, except it takes maximum khz as                           arguments. 0 KHz = RTCK. jtag_nsrst_delay         jtag_nsrst_delay  - delay after deasserting srst in ms jtag_ntrst_delay         jtag_ntrst_delay  - 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 jtag_speed               set jtag speed (if supported) log_output               redirect logging to (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 processing power_restore            Overridable procedure run when power restore is                           detected. Runs 'reset init' by default. production               - Runs production procedure. Throws exception if procedure failed. Prints progress messages. Implement this procedure in the target script. 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 script. profile                  profiling samples the CPU PC reset_config runtest                  move to Run-Test/Idle, and execute  scan_chain               print current scan chain configuration script                   - filename of OpenOCD script (tcl) to                           run shutdown                 shut the server down sleep                     [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 connections verify_ircapture         verify value captured during Capture-IR <enable|disable> version                  show OpenOCD version virt2phys                translate a virtual address into a physical address xsvf                     run xsvf flash bank               flash bank   <chip_width> <bus_width> [driver_options ...] mflash bank              mflash bank  <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 1 > 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

GDB
tbd.

=GDB ARM=

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

Test:

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 <http://gnu.org/licenses/gpl.html> 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". (gdb)