OpenOCD on Balloon 3

Introduction

OpenOCD is an open means of working with the JTAG test and debug port on ARM processors, and it supports the PXA270. It can be used from Windows and Linux hosts, and is now the normal base system upload mechanism, supported by bbl.

We currently recommend v0.3.1 or later with libftdi 0.16 or later, and that is what the balloonboard.org release config files support. v0.4 upstream also works fine, but needs a minor non-backwards-compatible config file change.

OpenOCD works fine on CPLD boards using the standard IO board for chained-JTAG programming, but on FPGA boards only single-channel programing works (needs a 'Hop' JTAG board). E1 -vintage boards need a mod to be JTAGable.

Chris jones has had it working on Windows with an Amontec JTAGKey dongle, an iEndian interface board (prototype), and the (very old) OpenOCD version supplied with the JTAGkey (r717 in OpenOCD SVN), and corresponding Amontec Windows device drivers.

The configuration files are completley different (different, options, different config file language) between the old r717 OpenOCD verison and anything at all current (v0.3.0 onwards). Only current releases are supported in baloonboard.org releases, but the old info remains here and in svn for you to try.

Hardware

Both the Amontec and Olimex dongles end in the ARM JTAG standard 20pin 0.1" header.

There are two IO boards which convert this to the Balloon J12 JTAG/serial/USB connector: the iEndian JTAG board and the Hop TCL JTAG board. They both essentially have the same wiring, although the iEndian board alows chaining of the CPLD and CPU JTAG ports. If you do that then the OpenOCD config has to change accordingly. This page currently details config for separate JTAG ports.

ARM JTAG header	Balloon3 FFC pin
1	14	VDD +3V power to dongle (via reg)
3	2	nTRST
5	5	TDI
7	3	TMS
9	6	TCLK
13	4	TDO
15	20	nSRST/NRES_BUTTON
20	1	GND

The important things are to make sure that PORT_EN is pulled high on the CPLD so that its JTAG port is active, and that nSRST and nTRST are connected to NRES_BUTTON and nTRST respectively. Since the JTAGkey's output buffers are powered by Vref from the board, and the PXA270's power architecture is such that VDD_IO (the primary 3.3V rail) is switched off while reset is asserted, there's a chicken-and-egg problem at powerup. I added a 3.3V LP2950 regulator to my dongle wiring powered from VDD_RAW (available on the Balloon JTAG connector (J12) pins 23 and 24) so that the JTAGkey always has 3.3V power.

If you have not got the power supply right then you will get errors at the 'reset halt' stage of programming - just after reading the cpu ID.

Unreliable operation of the dongle and OpenOCD can sometimes be due to having the dongle plugged into a USB hub. Try to plug it directly into a PC if possible.

Connecting things up

PLug the USB dongle into a USB socket. Best not to go through a hub - that sometimes breaks things. Connect the dongle arm connector to the IO board CPLD connector or CPU conenctor as required. Connect a 24-way FPC cable to J12 and the loon. Top contact on the loon and bottom-contact on the hop interface board.

Installing Open OCD

On Debian (lenny or later):

apt-get install openocd/testing

The version of openocd in lenny (r655) is too old to work usefully. The version currently in testing (r1409) is OK, as is r1655 (currently) from unstable.

Checking your dongle is recognised

Plug in your dongle to USB socket.

lsusb

should show something like

Bus 001 Device 014: ID 15ba:0004 Olimex Ltd. OpenOCD JTAG TINY

If not you need to edit /etc/udev/rules.d/z60_openocd.rules to add

# Olimex ARM-USB-TINY
SYSFS{idVendor}=="15ba", SYSFS{idProduct}=="0004", MODE="664", GROUP="plugdev"

There is no corresponding device node. libftdi uses USB directly.

The user doing the programming needs to be a member of group 'plugdev' (on Debian) to access the device.

Bringing up a bare board using OpenOCD

You need to have checked out the balloonboard svn trunk, or downloaded a prebuilt distro. This includes the OpenOCD config files. And you need to have either built yourself, or downloaded CPLD xsvf file, bootloader image, kernel/installer image. See SoftwareBuilding and SoftwareLoading.

Uploading the CPLD is done over the CPLD JTAG port - make sure the cable is connected to the correct connector (marked 'CPLD/FPGA' on the hop interface board).

On Linux

The procedure is different for FPGA and CPLD boards. On FPGA everything is programmed down the CPU JTAG port.

To install code, change to the top-level directory of a balloon distro, which contains kernel, initrd, booldr, utils dirs.

On a CPLD board, to install the CPLD code, do:

openocd -s utils/openocd/ -f balloon3-cpld-olimex.cfg -f cpld.cfg

You should see

5000 kHz
Error: There are no enabled taps?
Error: There are no enabled taps?
Warn : no gdb ports allocated as no target has been specified
xsvf processing file: "vhdl/cpld/l3cpld.xsvf"
XSVF file programmed successfully

You may need to reset the board a few times and retry this as quite often the CPLD is 'not in the right state'. The hopinterface board has a conveneient reset button for this purpose. There is a pause of 15 seconds or so after "xsvf processing file: "vhdl/cpld/l3cpld.xsvf"".

if you see

5000 kHz
Error: There are no enabled taps?
Error: There are no enabled taps?
Warn : no gdb ports allocated as no target has been specified
xsvf processing file: "vhdl/cpld/l3cpld.xsvf"
Warn : TAP (unknown):
Warn : value captured during scan didn't pass the requested check:
Warn : captured: 0xFFFFFFFF check_value: 0xF494FFFF check_mask: 0x0FFF8001
Warn : in_handler: w/o "in_value", mismatch in SDR
XSDRTDO mismatch
TDO mismatch, somewhere near offset 28 in xsvf file, aborting
Runtime error, file "utils/openocd//cpld.cfg", line 5:

Then that usally means 'no power to device' or 'cables not plugged in' or 'connected to wrong JTAG connector'.

Now change the arm JTAG connector over to the other header (marked 'PXA' on the hopinterface board). For a CPLD board do

openocd -s utils/openocd/ -f balloon3-cpu-olimex.cfg -f loadloon.cfg

For an FPGA board do

openocd -s utils/openocd/ -f balloon3-cpu-olimex.cfg -f loadloon.cfg -f loadfpga.cfg

You should see something like

5000 kHz
Info : JTAG tap: pxa270.cpu tap/device found: 0x49265013 (Manufacturer: 0x009, Part: 0x9265, Version: 0x4)
Info : JTAG Tap/device matched
Info : JTAG tap: pxa270.cpu tap/device found: 0x49265013 (Manufacturer: 0x009, Part: 0x9265, Version: 0x4)
Info : JTAG Tap/device matched
Warn : TAP pxa270.cpu:
Warn : value captured during scan didn't pass the requested check:
Warn : captured: 0x00 check_value: 0x02 check_mask: 0x07
Warn : in_handler: w/o "in_value", mismatch in SDR
Error: JTAG error while writing DCSR
Warn : TAP pxa270.cpu:
Warn : value captured during scan didn't pass the requested check:
Warn : captured: 0x00 check_value: 0x01 check_mask: 0x7F
Warn : in_handler: w/o "in_value", mismatch in SIR
target state: halted
target halted in ARM state due to debug-request, current mode: Supervisor
cpsr: 0x580000d3 pc: 0x00000000
MMU: disabled, D-Cache: disabled, I-Cache: disabled
(processor reset)
     TapName            | Enabled |   IdCode      Expected    IrLen IrCap  IrMask Instr     
---|--------------------|---------|------------|------------|------|------|------|---------
 0 | pxa270.cpu         |    Y    | 0x49265013 | 0x49265013 | 0x07 | 0x01 | 0x7f | 0x10
flash 'cfi' found at 0x00000000
wrote  219904 byte from file bootldr/bootldrpxa.fast to flash bank 0 at offset 0x00000000 in 22.387569s (9.592376 kb/s)
wrote  3163772 byte from file kernel/zImageInitrd to flash bank 0 at offset 0x00200000 in 302.219513s (10.223103 kb/s)

There is a pause of 20 seconds or so after "flash 'cfi' found at 0x00000000" and one of several minutes before "wrote 3163772 byte from file kernel/zImageInitrd to flash bank 0 at offset 0x00200000 in 302.219513s (10.223103 kb/s)".

Linux users can stop reading here.

Config files

Overall config file bringing in appropriate target, interface and base config stuff:

# config for Intel PXA270 Balloon 3, with olimex dongle
# connected to pxa JTAG port

#set up ports and standard config
source [find base.cfg]

jtag_khz 5000

#dongle
source [find olimex-jtag-tiny.cfg]

#jtag chain

set CPUTAPID 0x49265013
source [find pxa270.cfg]

# aleph1 and lart dongles dont' have SRST reset control - it's manual
# TRST is just pulled by resistor/ignored
# FT2232=type devices have both signals properly passed through
if { [info exists DONGLETYPE] } {
   set  RESETSIGNALS none
} else {
   set  RESETSIGNALS trst_and_srst
   set  RESETFLAVOUR separate
}
#reset_config $RESETSIGNALS $RESETFLAVOUR
reset_config trst_and_srst separate

#flash bank <driver> <base> <size> <chip_width> <bus_width>
# 29LV650 64Mbit Flash
flash bank cfi 0x00000000 0x800000 2 2 0
 
init 
reset halt
scan_chain
flash_probe 0

The end of the file here initialises the openocd server, sets the CPU into 'halt', displays the JTAG scan chain (shoing the CPU ID that was read during boundary scan - a good indication if things are working or not, and then probes teh flash to see if it can be found.

The reset configuration is a complicated interaction of the capabilities of the board, the JTAG dongle and the cabling interface between them, so it can't live nicely in any of the target or interface files.

base.cfg just contains the server port config that is the same for all configs: You get distracting warnigns about having not set this stuff if you don't set it explicitly, even though these are the defaults.

telnet_port 4444
gdb_port 3333
tcl_port 6666

Interface configuration file. The ones supplied with open OCD are buggy so best to use this local one:

##
# Olimex JTAG TINY USB Debugger
# Linux USB tends to see the device description without the 'A' on the
# end of the description as in target/olimex-jtag-tiny.cfg,
# but Windows still needs the 'A'. This is a replacement for Linux users.
##

# REFERENCE:  http://www.olimex.com/dev/arm-usb-tiny.html
interface ft2232
ft2232_device_desc "Olimex OpenOCD JTAG TINY"
ft2232_layout olimex-jtag
ft2232_vid_pid 0x15ba 0x0004

This is the script which actually programs code into the the flash down the cpu JTAG port. It needs to be called after tha bove set-up stuff:

flash write_image erase bootldr/bootldrpxa.fast 0 bin
flash write_image erase kernel/zImageInitrd 0x200000 bin
#flash write_bank 0 bootldr/bootldrpxa.fast 0
#flash write_bank 0 kernel/zImageInitrd 0x200000

#for fpga
#flash write_image erase vhdl/fpga/l3fpga.bin 0x100000
#flash write_bank 0 vhdl/fpga/l3fpga.bin 0x100000 
shutdown

Note that two different programing commands are given as I've found versions which only work with one and not the other (v1.0, r1439 needed write_bank. r1409 needs write_image. r1655 seems to do both.) The the other if you have problems at the programming stage.

Shutdwon at the end closes the openocd session.

To program the CPLD code down the CPLD JTAG port, the config file is simpler - doing nothing but port setup and init

# config for Intel PXA270 Balloon 3, with olimex dongle
# connected to CPLD JTAG port

#set up ports and standard config
source [find base.cfg]

jtag_khz 5000

source [find olimex-jtag-tiny.cfg]

#don't need to set up JTAG tap for this device, because using xsvf

# aleph1 and lart dongles dont' have SRST reset control - it's manual
# TRST is just pulled by resistor/ignored
# FT2232=type devices have both signals properly passed through
if { [info exists DONGLETYPE] } {
   set  RESETSIGNALS none
} else {
   set  RESETSIGNALS trst_and_srst
   set  RESETFLAVOUR separate
}
#reset_config $RESETSIGNALS $RESETFLAVOUR
reset_config trst_and_srst separate

init

and then running this command to actually upload the code - which simply repeats the commands inthe xsvf file:

xsvf plain vhdl/cpld/l3cpld.xsvf
shutdown

On Windows with r717

Note: these instructions only work properly with OpenOCD version 717, as supplied by Amontec. Later revisions use an entirely different configuration file and command structure.

If you're using a CPLD board, use the Xilinx iMPACT tool to program it. We can't yet do this by OpenOCD but we hope to soon.
Connect your board to the OpenOCD dongle.
Start OpenOCD with the appropriate configuration file.
telnet to localhost port 4444 to talk to OpenOCD
load the bootldr by doing

flash write_image erase bootldrpxa.fast

This should take about 10-15 seconds.
load the initrd/recovery kernel by doing

flash write_image erase zImageInitrd 0x200000

This should take about 3 minutes.
if yours is an FPGA board, load the FPGA code:

flash write_image erase l3fpga.bin 0x100000

This should take around 25 seconds.
the board should now boot and you can do the rest by USB networking - see Balloon3SingleSidedRootFS

Software config

Chris Jones has used OpenOCD r717 successfully. The Windows version can be downloaded from

http://www.yagarto.de/#download

The Linux version can be downloaded via svn

svn co -r 717 svn://svn.berlios.de/openocd/trunk

Note that the configuration file format has completely changed since that version, so the files below probably won't work with newer versions of OpenOCD.

The OpenOCD configuration files for r717 look like this:

CPLD Version

 # config for Intel PXA270 Balloon 3
 # not, as of 2007-06-22, openocd only works with the
 # libftd2xx library from ftdi.  libftdi does not work.
 telnet_port    4444
 gdb_port    3333
 interface ft2232
 interface ft2232
ft2232_device_desc "Amontec JTAGkey A"
ft2232_layout jtagkey
ft2232_vid_pid 0x0403 0xcff8
jtag_speed 0
# set jtag_nsrst_delay to the delay introduced by your reset circuit
 # the rest of the needed delays are built into the openocd program
 jtag_nsrst_delay 260
 # set the jtag_ntrst_delay to the delay introduced by a reset circuit
 # the rest of the needed delays are built into the openocd program
 jtag_ntrst_delay 0
 #use combined on interfaces or targets that can't set TRST/SRST separately
 reset_config trst_and_srst separate
 #jtag scan chain
 #format L IRC IRCM IDCODE (Length, IR Capture, IR Capture Mask, IDCODE)
 # first device is the one closest to TDO
# XCR3256XL
 jtag_device 5 0x01 0x1f 0x01
 # PXA270
 jtag_device 7 0x1 0x7f 0x7e

 #target configuration
 daemon_startup reset
 target xscale little reset_halt 1 pxa27x
 # maps to PXA internal RAM.  If you are using a PXA255
 # you must initialize SDRAM or leave this option off
 working_area 0 0x5c000000 0x10000 nobackup
 run_and_halt_time 0 30
 #flash bank <driver> <base> <size> <chip_width> <bus_width>
 # 29LV650 64Mbit Flash
 flash bank cfi 0x00000000 0x800000 2 2 0

FPGA Version

# config for Intel PXA270 Balloon 3
 # not, as of 2007-06-22, openocd only works with the
 # libftd2xx library from ftdi.  libftdi does not work.

 telnet_port    4444
 gdb_port       3333

 interface ft2232
 interface ft2232
ft2232_device_desc "Amontec JTAGkey A"
ft2232_layout jtagkey
ft2232_vid_pid 0x0403 0xcff8
jtag_speed 0
# set jtag_nsrst_delay to the delay introduced by your reset circuit
 # the rest of the needed delays are built into the openocd program
 jtag_nsrst_delay 260
 # set the jtag_ntrst_delay to the delay introduced by a reset circuit
 # the rest of the needed delays are built into the openocd program
 jtag_ntrst_delay 0

 #use combined on interfaces or targets that can't set TRST/SRST separately
 reset_config trst_and_srst separate

 #jtag scan chain
 #format L IRC IRCM IDCODE (Length, IR Capture, IR Capture Mask, IDCODE)
 # first device is the one closest to TDO
# XC3S1000
 jtag_device 6 0x01 0x03 0x01
 # PXA270
 jtag_device 7 0x1 0x7f 0x7e
 
 #target configuration
 daemon_startup reset

 target xscale little reset_halt 1 pxa27x

 # maps to PXA internal RAM.  If you are using a PXA255
 # you must initialize SDRAM or leave this option off
 working_area 0 0x5c000000 0x10000 nobackup

 run_and_halt_time 0 30

 #flash bank <driver> <base> <size> <chip_width> <bus_width>
 # 29LV650 64Mbit Flash
 flash bank cfi 0x00000000 0x800000 2 2 0