Gonemad's Bus Pirate/OpenOCD walk through
This is a post about how to quickly dive into JTAG'ing for a newbie. I'll be using OpenOCD with Cygwin and a BusPirate, with the goal is to successfully "scan_chain" a Broadcom board.
Installing drivers and plugging in your BPv3b on Windows Vista
Last Update: 2011-04-25 System Software: Windows Vista Home Premium (32bit) V6.0 B6002, SP2 Cygwin DLL version: 1.7.9 System Hardware: HP Pavilion DV9000 (AMD Turion 64 X2 TL-68) + BusPirate Version 3b
"BPv3b" = BusPirate Version 3b
First and foremost, and if you are really serious about JTAG'ing, save yourself an ocean of trouble and get your self a semi-professional USB-based JTAG adapter/dongle and check that it has hardware support for the board/device you are most interested in. Contrary to what the guys are saying on the Dangerous Prototype's BusPirate support forum, JTAG with the BP is really NOT "supported" out of the box and without hacking, apart being a great tool for other protocols. But if you have already spent your $$$ on a BP and happen to need to do some very simple one-time JTAG operation, it is possible... Here is how to.
The easiest way to get and install the proper drivers for your new BusPirate is by going to the BP chip provider web pages and download their Windows driver package, which is distributed as either a .zip file or a .exe installer. I choose the .exe installer, but the drawback is that there is no feedback message that anything have been installed (at least not for me). The screen just flashes once and that's it. I haven't tried the .zip file installation. (Please let me know how that works.)
In our case, for the BPv3b, the chip is the FT232RL and the provider company is FTDI (Future Technology Devices International). Their drivers are now ASFAIK distributed in a single download package containing both the drivers for VCP (Virtual COM Port) and D2XX (direct USB access via DLL) connections. The one to use for BP terminal access is VCP and the one you need for openOCD is D2XX. [?]
Windows* 2011-04-12 2.08.14 http://www.ftdichip.com/Drivers/CDM/CDM20814_WHQL_Certified.zip http://www.ftdichip.com/Drivers/CDM/CDM20814_Setup.exe http://www.ftdichip.com/Drivers/CDM/CDM%202%2008%2014%20Release%20Info.rtf
Download both (the .exe and the .zip), as you will need the .zip package later.
After having run the "Setup" installer, plug in your BusPirate and let windows search for the drivers. This will take a while so don't worry. If something is not working properly, keep trying and check the BusPirate website for changes or updates.
By now, you can fire up "Device Manager" and look under: "Ports (COM & LPT)", then right-click on the "USB Serial Port (COMX)" [where X is some number from 1-255] and select "Properties". If you clicked the right one, you should be presented with a new window. Select the "Driver" tab which is saying something like:
Driver Provider: FTDI Driver Date: 3/18/2011 Driver Version: 188.8.131.52 Digital Signer: <blah blah ...>
This confirms that you're probably using the right COM port and driver. Now click on the "Port Settings" tab and change the setting to this:
Bits per second: 115200 Data bits: 8 Parity: None Stop bits: 1 Flow control: None
[There is a bug here, with the effect that the "current" Port Setting are not updated and always showing the default (57200 etc.) after having closed and re-opened Device manager.]
Now it's time to open your favorite terminal application. I use the free "RealTerm". (You can download it from here: http://realterm.sourceforge.net/ ) I like it simply because it has too many features! Select the same settings as above and make sure you choose the same port as shown in Windows Device Manager. Hit [RET] a few times and you should be greeted with BP's built in command-line interface with the "HiZ>" prompt. The first useful thing to do is to check your exact hardware/firmware/bootloader version by typing "i" and find out which protocols are directly/natively supported by typing "m". In the latest FW versions, "JTAG" is not present in the list, although it should be supported through OpenOCD according to developers, but not according to users!
HiZ>i Bus Pirate v3b Firmware v5.10 (r559) Bootloader v4.4 DEVID:0x0447 REVID:0x3043 (24FJ64GA002 B5) http://dangerousprototypes.com HiZ>m 1. HiZ 2. 1-WIRE 3. UART 4. I2C 5. SPI 6. 2WIRE 7. 3WIRE 8. LCD 9. DIO x. exit(without change) (1)> x no mode change HiZ>
If your Firmware version is "5.9/10" or earlier, you will need to update your firmware to "6.0RC" or later if you intend to use/run OpenOCD. Unless you see "JTAG" in the list above, in which case there should be a very simple native BP JTAG terminal mode. Else see the FW update instructions below.
Close/Disconnect your terminal. You're done, for now...
Updating/Changing BPv3b Firmware
Download the latest (OpenOCD activated) firmware, which is currently "6.0RC" in the "busPirate.production.zip" from here: http://dangerousprototypes.com/forum/download/file.php?id=3493
You can update the BPv3b Firmware using two methods. a) With the "ds30 Loader GUI" for Mac & Windows (Mono/.NET required) b) With the "pirate-loader" command line tool for Mac/Linux/Windows. where: (a) is a PIC bootloader that can be used on well over 400 devices. (b) is a PIC24FJ64GA002 only bootloader.
Download the latest versions here:
It is strongly recommended to use (a) only, unless your current bootloader version is older than "v4+". I will not cover (b).
After installing the "ds30" loader application, you need to connect your BP first. (Don't do this now, I'm just telling you.) Then open a terminal window and put the BP in bootloader mode (in order to accept firmware/bootloader upgrade) by typing "$" at the "HiZ>" prompt.
To get all the right "ds30 Loader" parameters for your BPv3b, download and extract the appropriate BitPirate .zip firmware package, that also contain the older ds30 Loader, but with the addition of a "settings.xml" file. Copy this file to the ds30's default settings directory (for Windows Vista): "C:\Users\YourWindowsUsername\AppData\Roaming\.ds30Loader\". You can then navigate to this file (from ds30) by going to "View" --> "Settings directory". If you use this file, you will notice that most settings are disabled from changes as a sefty precaution in order for careless people not to brick their BP!
[These "settings" instructions are NOT working at this time, as ds30 refuses to properly load a changed settings.xml file! Ask ds30/BP developer...]
Of course you can adjust all the settings manually in the GUI. The following settings should suffice.
Basic: Baudrate: 115200 Device: PIC24FJ 64GA002 Port: USB Serial Port (COMnn) Write program: "True" Write Eeprom: "False" Advanced: De-select everything! Timing: Poll time: 250 Timeout: 5000 Reset: Manual Activation: Manual Security: De-select everything! Terminal: Baudrate: 115200
Then follow this procedure: • Connect your BP to your PC • Open a terminal to your BP • Type "$" and then accept with "yes". • Close/disconnect terminal • Start the "ds30 Loader" GUI • Adjust the ds30 GUI settings according to those above, if needed • Load the path to the new Firmware • Hit "Write" button • Wait until the green progress bar is complete • Wait a few seconds more and then disconnect your BP • Close the "ds30 Loader" • Reconnect BP • Open a terminal and check the results.
HiZ>i Bus Pirate v3b Firmware v6.0RC (r572) Bootloader v4.4 DEVID:0x0447 REVID:0x3043 (24FJ64GA002 B5)
Great! You're done for now.
For other BP Firmware versions (and everything else):
Installing OpenOCD on Cygwin (Vista)
The original instructions was found here:
However, these are mostly outdated, but may prove useful for more details or for resolving particular problems. But after having read and updated these instructions, I have been able to install OpenOCD on Windows/Cygwin. I'll attempt to present this information here.
This is what you need to do: A) Install Cygwin + relevant packages B) Test the BP COM port in Cygwin C) Download latest FTDI drivers & OpenOCD D) Compile and install OpenOCD with FTDI drivers E) Test BusPirate and OpenOCD communication F) Connect OpenOCD to your board/device
A) You need to install at least these additional Cygwin packages:
aclocal autoconf automake gcc-core git libtool make tetex tetex-extra unzip
And one or more of: netcat, telnet, openssh
- If you plan to use other USB/parallel-port-based JTAG devices and software like UrJTAG, you probably also need to install some of the following Cygwin/*nix packages and libraries.
ioperm popt libusb libftdi gettext readline
B) Test your BP COM port in Cygwin:
How do you access a Windows USB serial COM port from Cygwin?
The first and most important thing you need to know, is that in Cygwin, normal Windows based USB-serial COMX [where X is your windows COM port number] ports, are mapped as follows:
Win32: COMX ==> Cygwin: /dev/ttyS[X-1] == /dev/comX
where "ttySn" (n=X-1) is preferred. Now to see if it works, connect your BP and try to send a character to it. (Do NOT send random ones!)
echo -ne "i\n" >/dev/ttySn
If you get an "Access Denied"-like message, you probably have something else connected to your BP or some other device using that COM port. If you get nothing in return, it probably works. Try it again and see if the BP Tx/Rx LED flashes when you hit return. Did you see it? Good.
The second thing to know about Cygwin, is that your /dev/<device> is NOT normally visible for "ls /dev". In order to see the settings of a device you have to specify it, otherwise you will not see anything:
$ ls /dev fd@ mqueue/ nul shm/ stderr@ stdin@ stdout@ $ ls -al /dev/ttyS12 crw-rw-rw- 1 xxxxxx None 117, 12 Apr 24 14:32 /dev/ttyS12
NOTE: This way you will also see devices that are not connected! :/
You can read more about this here:
C) Download the latest FTDI drivers and OpenOCD
Download and extract the FTDI (FT2232) drivers from: http://www.ftdichip.com/Drivers/D2XX.htm
As already mentioned, these Windows driver packages should contain both the D2XX and VCP drivers. (E.g. "CDM20814_WHQL_Certified.zip".) Extract and change name of the extraction directory to something more simple like "ftd2xx". It is recommended that you do this in a new and empty directory near the root of your drive, to keep your command lines short and leggible, while keeping your development stuff separate from the rest of the system. For example I created "C:\myusr\" for all my BP/OpenOCD stuff. Some stuff will obviously still be installed in your Cygwin path! But for the remainder of this tutorial I'll assume we are in this directory...or nearby.
$ mkdir /cygdrive/c/myusr $ cd /cygdrive/c/myusr $ unzip CDM20814_WHQL_Certified.zip -d ftd2xx $ git clone git://openocd.git.sourceforge.net/gitroot/openocd/openocd Cloning into openocd... remote: Counting objects: 36741, done. remote: Compressing objects: 100% (9533/9533), done. remote: Total 36741 (delta 30324), reused 32961 (delta 27101) Receiving objects: 100% (36741/36741), 7.98 MiB | 467 KiB/s, done. Resolving deltas: 100% (30324/30324), done. $ ls -al drwxr-xr-x+ 1 Administrators None 0 Apr 21 18:49 ftd2xx/ drwxr-xr-x+ 1 Administrators None 0 Apr 21 18:18 openocd/
Later, IF needed, you can simply update your "openocd" git cloned directory with the "git pull" command.
For a great GIT tutorial:
D) Compile & Install OpenOCD with FTDI D2XX drivers
Go to the newly created "openocd" directory:
$ cd openocd $ ./bootstrap + aclocal + libtoolize --automake --copy + autoconf + autoheader + automake --gnu --add-missing --copy configure.in:20: installing `./compile' configure.in:28: installing `./config.guess' configure.in:28: installing `./config.sub' configure.in:8: installing `./install-sh' configure.in:8: installing `./missing' doc/Makefile.am:1: installing `doc/mdate-sh' doc/Makefile.am:1: installing `doc/texinfo.tex' src/Makefile.am: installing `./depcomp' Makefile.am: installing `./INSTALL' Setting up submodules Submodule 'jimtcl' (http://repo.or.cz/r/jimtcl.git) registered for path 'jimtcl' Submodule 'tools/git2cl' (http://repo.or.cz/r/git2cl.git) registered for path 'tools/git2cl' Cloning into jimtcl... Submodule path 'jimtcl': checked out '60dfb023c4afa95047e0fa8db49830ccb46446b2' Cloning into tools/git2cl... Submodule path 'tools/git2cl': checked out '8373c9f74993e218a08819cbcdbab3f3564bbeba' Bootstrap complete. Quick start build instructions: ./configure --enable-maintainer-mode ....
The following command is checking all your (Cygwin) system settings and packages and configures the compile scripts to use for "make". This can take some time and you should keep an eye out for missing (Cygwin) packages, which may or may not be OK. Especially if you get errors later, when compiling. You may also consider adding the "--enable-dummy" switch to create a dummy JTAG interface for testing.
$ ./configure --enable-buspirate --enable-maintainer-mode --disable-werror --disable-shared --enable-ft2232_ftd2xx --with-ftd2xx-win32-zipdir=/cygdrive/c/myusr/ftd2xx $ make && make install ... too long and boring to display ... unless there are errors ... $ which openocd.exe /usr/local/bin/openocd.exe $ openocd.exe --help Open On-Chip Debugger 0.5.0-dev-00858-g3c6af51-dirty (2011-04-21-20:38) Licensed under GNU GPL v2 For bug reports, read http://openocd.berlios.de/doc/doxygen/bugs.html Open On-Chip Debugger Licensed under GNU GPL v2 --help | -h display this help --version | -v display OpenOCD version --file | -f use configuration file <name> --search | -s dir to search for config files and scripts --debug | -d set debug level <0-3> --log_output | -l redirect log output to file <name> --command | -c run <command>
E) Test your BusPirate & OpenOCD communication
In order to use OpenOCD to perform a JTAG operation, you execute a command in the form:
openocd -f interface/buspirate.cfg -f target/your-target-name.cfg -c <JTAG-command>
But to do this you need to have:
a) The correct configuration settings for: buspirate.cfg. b) The correct configuration settings for your target board.(Eg."sam7x256.cfg") c) A successful communication between BP and OpenOCD.
Optionally you may omit all command line arguments, if you instead have a configuration file called "openocd.cfg" in the current directory, that contain the configuration-file path-finder commands:
source [find interface/buspirate.cfg] source [find board/your-board-name.cfg]
Finally we have to test the communication between your BP and the OpenOCD, usually by just checking the results of sending a few JTAG commands to a non-connected target-board.
NOTE: According to some people, OpenOCD should automatically attempt a chain-scan when executed without a target specification.
(a) Configuration settings for: buspirate.cfg
So first you have to find out where "make install" have put the "buspirate.cfg" file. This is not obvious, but I can tell you that if you are using a default Cygwin environment it is most likely located in /usr/local/share/openocd/. If you don't find it there, use the "find" command to search your relevant cygwin tree (before attempting the entire HD) with:
$ find /usr/ -name buspirate.cfg /usr/local/share/openocd/scripts/interface/buspirate.cfg
Now copy this file into your working directory and change name to something more suitable:
$ cp /usr/local/share/openocd/scripts/interface/buspirate.cfg /cygdrive/c/myusr/bpv3b.cfg $ cd /cygdrive/c/myusr/
Now you need to edit this, according to the target board and JTAG cable you are using. But BP is supposedly easy to configure when using standard JTAG cables/connectors. I have edited my "bpv3b.cfg" file like this:
$ cat bpv3b.cfg # ========================================================= # What: BusPirate Version 3b with OpenOCD support # Using: USB serial on COM port 13 # JTAG: <available pins & description> # See: http://dangerousprototypes.com/docs/Bus_Pirate_JTAG_connections_for_OpenOCD # Note: 1) If you have "normal" mode AND "0" pullup, # THEN do not connect Vpu & VTref! # 2) Cygwin uses serial USB COM ports as: # /dev/ttyS[N-1] == /dev/comN # Make sure it's not already used with # any other terminal or programs... # ========================================================= interface buspirate # Not yet implemented properly... #transport select jtag # Set the serial port to be used: buspirate_port /dev/com13 #buspirate_port /dev/ttyS12 # Set "normal" or "fast" (~1 MHz)communication speed: buspirate_speed normal # Turn OFF the voltage regulator: #buspirate_vreg 0 # --------------------------------------------------------- # Remember that VTref (Vcc) is connected to pull-up's. # If you are NOT using pull-up's with "normal" drain # pin-mode, then do NOT connect Vpu to VTref! # --------------------------------------------------------- #buspirate_mode normal #buspirate_pullup 0 # --------------------------------------------------------- #buspirate_mode open-drain #buspirate_pullup 1 # --------------------------------------------------------- # This depends on the cable, you are safe with this option: reset_config srst_only # =========================================================
Please note, that if you want to use comments on the configuration lines, you have to first terminate each command line with ";" before adding comments with "#". Also remember to set your editor to use UNIX CR/LF file format. For example:
"buspirate_pullup 0 # Pullup disabled" ==> NOT OK! "buspirate_pullup 0 ;# Pullup disabled" ==> OK!
As for the rest of this configuration, it is based on the particular JTAG cable/board connection you are using and I really don't know what it should be even for my own, at this time. Please feel free to enlighten me!
My Broadcom board's JTAG connector pads (probably) have the following layout (JTAG PCB top solder pads):
^Pin ^Function ^^Pin ^ 1 | nTRST | GND | 2 3 | TDI | GND | 4 5 | TDO | GND | 6 7 | TMS | GND | 8 9 | TCK | GND | 10 11 | nSRST | -- | 12 13 | -- | Vref | 14
12: This pin is sometimes removed on connector 13: This pin is used for Debug Interrupt (DINT) and is not always used. 14: Vref = VIO = Vcc (3.3V in my case)
Quote: NOTE-1: These should conform to the 14-pin EJTAG 2.5 MIPS standard. NOTE-2: nTRST is a "TAP Reset" signal and it's active level is "0" (the first "n" indicates negative logic). This signal resets the TAP controller independently from the CPU logic. To conform to MIPS EJTAG specifications this pin should be pulled to the ground via ~1K Ohm resistor to keep the TAP in a reset state w/o attached probe. If the probe does not control this pin, you only need to feed a logical "1" to the nTRST pin or pull it up to the +Vcc via a ~300 Ohm resistor. nSRST is a "system reset" signal and acts like a conventional "Reset' button. It does not reset the TAP controller and is often used to reset SoC peripherals (i.e. DRAM controllers) although is optional. NOTE-3: Many Broadcom chips are using the "DMA"-mode for EJTAG. NOTE-4: The IMPCODE register contains the "EJTAGver" field, which can be read to determine EJTAG version.
Very nice and detailed info here:
(b) Configuration settings for: <your-board>.cfg
The most difficult and tricky part, is figuring out what board you have and what settings are required for it. [I have not yet been able to do this for my board...]
But I am looking at:
c) Testing BP and OpenOCD communication
For some reason many boards like to receieve the "init" command before any other JTAG operations. (And in some other cases, the CPU should also be stopped with "halt" + "reset halt".)
$ openocd.exe -f bpv3b.cfg Open On-Chip Debugger 0.5.0-dev-00858-g3c6af51-dirty (2011-04-21-20:38) Licensed under GNU GPL v2 For bug reports, read http://openocd.berlios.de/doc/doxygen/bugs.html Warn : Adapter driver 'buspirate' did not declare which transports it allows; assuming legacy JTAG-only Info : only one transport option; autoselect 'jtag' srst_only separate srst_gates_jtag srst_open_drain Info : Buspirate Interface ready! Error: Translation from jtag_speed to khz not implemented Info : adapter-specific clock speed value 0 Warn : There are no enabled taps. AUTO PROBING MIGHT NOT WORK!! Error: JTAG scan chain interrogation failed: all zeroes Error: Check JTAG interface, timings, target power, etc. Error: Trying to use configured scan chain anyway... Error: IR capture error at bit 0, saw 0x00 not 0x...3 Warn : Bypassing JTAG setup events due to errors Warn : gdb services need one or more targets defined [HANG!]
This may still indicate it works, since we never specified a target device and don't have anything connected.
F) Connecting OpenOCD to your board/device:
Once you have the 2 configuration files setup corrctly you should be able to successfully issue a command like this:
openocd -f bpv3b.cfg -f my-target-board-name.cfg [... long and informative output ...]
If you want to see more detailed output add the debug flag "-d 3".
Now connect to the OpenOCD JTAG port with one of the following:
telnet localhost:4444 nc localhost 4444 ssh localhost:4444
(If "localhost" is not working try "127.0.0.1") If something goes wrong (or BP is locked up in some unknown state) try: Code:
openocd -f buspirate.cfg -c "init" -c "halt" -c "reset halt" and if that doesn't work, just unplug it!
How to use JTAG for Boundary Scans
Bundary scans also loosly known as "chain scans", although not strictly correct, are used to map out the various components of a board, but without detailed scans of each one. This is great for figuring out what the various chips are, that are connected to eachother.
See for example:
Sorry I have not gotten to the "scan_chain" yet, as my board is currently not with me. I'll update this when I do and in addition if I find or create a proper configuration file for my board...
As I am new to all this myself, it is quite possible that there are problems or errors in these instructions, please let me know about about those.