JTAG 101

What is it?

JTAG stands for the Joint Test Action Group, and the TAP or Test Access Port this group defined is one of the most (if not the most) common way to program and debug embedded devices and computers of all flavors. For the professional, JTAG devices are bountiful and usually not too much of a strain on the commercial budget. But for the hobbyist, things aren’t so peachy. A Segger J-Link EDU can be had for ~$70 USD shipped, but the full featured J-Link is still ~$400, which is more than I want to pay as a hobbyist.

What does it do?

The JTAG TAP port consists of a few standard signals which essentially give you complete control over the systems in the JTAG chain. The chain is exactly what it sounds like: multiple devices which support JTAG chaining can be chained up and accessed from a single JTAG port. Need that flash programmed? JTAG can do that. Need to debug that microcontroller? JTAG can do that too. Want to do both without switching out tools? Yep, JTAG can do it. See this helpful diagram at Wikipedia for a visual representation.

JTAG for the Hobbyist

Chances are that you’ve got an USB -> Serial cable or breakout board lying around somewhere in your hoard. Chances are also, that it’s based on the wildly popular FTDI FT232R or a similar FT232-esque chip which converts USB to RS232. If you’re lucky enough to have this essential piece of hobbyist equipment, you’ve got a USB->JTAG adapter waiting to be unlocked!

Enter OpenOCD

OpenOCD (Open On-chip Debugger) is a fantastic project which aims to create an open and extensible OCD solution for all, and lucky for us, this includes the hobbyist! The OpenOCD project defines interfaces between the common parts of the OCD process, such as the target board or device, the OCD device used, etc., and using these well-defined interfaces is able to create a modular system which can support many different targets and debuggers with only a configuration change. This is a simplification of how this works, but it is sufficient to understand what we want to do with it.

So back to the FT232R. This little chip can be re-configured to use the RS232 signals as bit-banged JTAG signals, and OpenOCD can drive it. Even better, once the OpenOCD agent is up and running, we can then use GDB to connect to and drive our debug efforts. This mode of operation is detailed over at their documentation site (hint: search for ft232r).

The OpenOCD tool can usually be installed with your package manager on Linux. I’m running Linux Mint, so I apt install’d openocd. When I ran the tool pointing to the ft232r config file, it complained that it was not a supported interface… so I guess we’ll build from source!

Building OpenOCD with the Right Interfaces

All we need to do is build OpenOCD from source with the right interfaces enabled and we can make it work. What follows next is my step-by-step on doing this. I’m doing this in /tmp just so I can recreate the steps I did earlier in my apps directory.

Grab the Source

Go get the source from the GitHub mirror here and drop it in a working directory. I would also read the README for any dependencies you didn’t have already on your machine.

jacob@jacob-aspire-mint:/tmp$ git clone https://github.com/ntfreak/openocd.git
Cloning into 'openocd'...
remote: Enumerating objects: 74, done.
remote: Counting objects: 100% (74/74), done.
remote: Compressing objects: 100% (53/53), done.
remote: Total 62845 (delta 36), reused 50 (delta 21), pack-reused 62771
Receiving objects: 100% (62845/62845), 24.17 MiB | 24.90 MiB/s, done.
Resolving deltas: 100% (51571/51571), done.
jacob@jacob-aspire-mint:/tmp$

Run the bootstrapper

This little piece of code essentially checks that your build environment is sane and you have all the tools needed to build OpenOCD. Output is below, you should come away with no errors. 

jacob@jacob-aspire-mint:/tmp/openocd$ ./bootstrap 
+ aclocal
+ libtoolize --automake --copy
+ autoconf
+ autoheader
+ automake --gnu --add-missing --copy
configure.ac:26: installing './compile'
configure.ac:37: installing './config.guess'
configure.ac:37: installing './config.sub'
configure.ac:16: installing './install-sh'
configure.ac:16: installing './missing'
Makefile.am:46: warning: wildcard $(srcdir: non-POSIX variable name
Makefile.am:46: (probably a GNU make extension)
Makefile.am: installing './INSTALL'
Makefile.am: installing './depcomp'
Makefile.am:23: installing './mdate-sh'
Makefile.am:23: installing './texinfo.tex'
Setting up submodules
Submodule 'jimtcl' (http://repo.or.cz/r/jimtcl.git) registered for path 'jimtcl'
Submodule 'src/jtag/drivers/libjaylink' (http://repo.or.cz/r/libjaylink.git) registered for path 'src/jtag/drivers/libjaylink'
Submodule 'tools/git2cl' (http://repo.or.cz/r/git2cl.git) registered for path 'tools/git2cl'
Cloning into '/tmp/openocd/jimtcl'...
warning: redirecting to https://repo.or.cz/r/jimtcl.git/
Cloning into '/tmp/openocd/src/jtag/drivers/libjaylink'...
warning: redirecting to https://repo.or.cz/r/libjaylink.git/
Cloning into '/tmp/openocd/tools/git2cl'...
warning: redirecting to https://repo.or.cz/r/git2cl.git/
Submodule path 'jimtcl': checked out 'a9bf5975fd0f89974d689a2d9ebd0873c8d64787'
Submodule path 'src/jtag/drivers/libjaylink': checked out 'f73ad5e667ae8b26a52b847c603fdadaabf302a6'
Submodule path 'tools/git2cl': checked out '8373c9f74993e218a08819cbcdbab3f3564bbeba'
Generating build system...
libtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, 'build-aux'.
libtoolize: copying file 'build-aux/config.guess'
libtoolize: copying file 'build-aux/config.sub'
libtoolize: copying file 'build-aux/install-sh'
libtoolize: copying file 'build-aux/ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'm4'.
libtoolize: copying file 'm4/libtool.m4'
libtoolize: copying file 'm4/ltoptions.m4'
libtoolize: copying file 'm4/ltsugar.m4'
libtoolize: copying file 'm4/ltversion.m4'
libtoolize: copying file 'm4/lt~obsolete.m4'
configure.ac:42: installing 'build-aux/ar-lib'
configure.ac:37: installing 'build-aux/compile'
configure.ac:30: installing 'build-aux/missing'
Makefile.am: installing './INSTALL'
libjaylink/Makefile.am: installing 'build-aux/depcomp'
Bootstrap complete. Quick build instructions:
./configure ....
jacob@jacob-aspire-mint:/tmp/openocd$

Run the configure script

This is where we determine that we want the FTDI FT232R to be supported. We do this by adding a flag to the configure line. Output is cut short in the middle because it’s quite long, but the important part is at the end.

jacob@jacob-aspire-mint:/tmp/openocd$ ./configure --enable-ft232r 
checking for makeinfo... no
configure: WARNING: Info documentation will not be built.
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... gawk

[ ... snip ... ]

libjaylink configuration summary:
 - Package version ................ 0.2.0-git-f73ad5e
 - Library version ................ 0:0:0
 - Installation prefix ............ /usr/local
 - Building on .................... x86_64-pc-linux-gnu
 - Building for ................... x86_64-pc-linux-gnu

Enabled transports:
 - USB ............................ yes
 - TCP ............................ yes



OpenOCD configuration summary
--------------------------------------------------
MPSSE mode of FTDI based devices        yes (auto)
ST-Link Programmer                      yes (auto)
TI ICDI JTAG Programmer                 yes (auto)
Keil ULINK JTAG Programmer              yes (auto)
Altera USB-Blaster II Compatible        yes (auto)
Bitbang mode of FT232R based devices    yes
Versaloon-Link JTAG Programmer          yes (auto)
TI XDS110 Debug Probe                   yes (auto)
OSBDM (JTAG only) Programmer            yes (auto)
eStick/opendous JTAG Programmer         yes (auto)
Andes JTAG Programmer                   yes (auto)
USBProg JTAG Programmer                 no
Raisonance RLink JTAG Programmer        no
Olimex ARM-JTAG-EW Programmer           no
CMSIS-DAP Compliant Debugger            no
Cypress KitProg Programmer              no
Altera USB-Blaster Compatible           no
ASIX Presto Adapter                     no
OpenJTAG Adapter                        no
SEGGER J-Link Programmer                yes (auto)

Build it

Finally, we build it. Again, I’m snipping the output down to size, but you should end up with an executable binary in src/ called openocd. This final step doesn’t take long (on my machine only about 45s). 

jacob@jacob-aspire-mint:/tmp/openocd$ make
Makefile:4634: warning: overriding recipe for target 'check-recursive'
Makefile:4045: warning: ignoring old recipe for target 'check-recursive'
cat src/helper/startup.tcl src/jtag/startup.tcl src/target/startup.tcl src/server/startup.tcl src/flash/startup.tcl | ./src/helper/bin2char.sh > src/startup_tcl.inc || { rm -f src/startup_tcl.inc; false; }
cp src/jtag/drivers/minidriver_imp.h src/jtag/minidriver_imp.h
make  all-recursive
make[1]: Entering directory '/tmp/openocd'
Makefile:4634: warning: overriding recipe for target 'check-recursive'
Makefile:4045: warning: ignoring old recipe for target 'check-recursive'
Making all in jimtcl
make[2]: Entering directory '/tmp/openocd/jimtcl'


[ ... snip ... ]

libtool: link: ranlib src/.libs/libopenocd.a
libtool: link: rm -fr src/.libs/libopenocd.lax src/.libs/libopenocd.lax
libtool: link: ( cd "src/.libs" && rm -f "libopenocd.la" && ln -s "../libopenocd.la" "libopenocd.la" )
depbase=`echo src/main.o | sed 's|[^/]*$|.deps/&|;s|\.o$||'`;\
gcc -DHAVE_CONFIG_H -I.   -I./src -I./src -I./src/helper -DPKGDATADIR=\"/usr/local/share/openocd\" -DBINDIR=\"/usr/local/bin\" -I./jimtcl -I./jimtcl  -Wall -Wstrict-prototypes -Wformat-security -Wshadow -Wextra -Wno-unused-parameter -Wbad-function-cast -Wcast-align -Wredundant-decls -Werror -g -O2 -MT src/main.o -MD -MP -MF $depbase.Tpo -c -o src/main.o src/main.c &&\
mv -f $depbase.Tpo $depbase.Po
/bin/bash ./libtool  --tag=CC   --mode=link gcc -Wall -Wstrict-prototypes -Wformat-security -Wshadow -Wextra -Wno-unused-parameter -Wbad-function-cast -Wcast-align -Wredundant-decls -Werror -g -O2   -o src/openocd src/main.o src/libopenocd.la  ./jimtcl/libjim.a  -ldl 
libtool: link: gcc -Wall -Wstrict-prototypes -Wformat-security -Wshadow -Wextra -Wno-unused-parameter -Wbad-function-cast -Wcast-align -Wredundant-decls -Werror -g -O2 -o src/openocd src/main.o  src/.libs/libopenocd.a -lusb-1.0 -lm ./jimtcl/libjim.a -ldl
make[2]: Leaving directory '/tmp/openocd'
make[1]: Leaving directory '/tmp/openocd'

Testing OpenOCD

Now that we have a binary, we need to test it out and see if it works. My target for today is a Raspberry Pi 3 B. We first need to gather some info about our target, i.e., the Raspberry Pi 3. We need to know which pins on the GPIO header correspond to which JTAG signals.

First let’s grab the BCM2835 pinout reference. (Side note: we use the BCM2835 reference because there is no BCM2837 reference, and it seems the pinouts are roughly the same.) This will tell us what each GPIO pin does. Some of the GPIOs are only designated for one singular function, whereas many other GPIOs are multi-function, and their function is software programmable. These alternate functions are designated ALT on the reference material. I used the reference over at e-Linux because I find the table easy to read. Searching the table, we find the JTAG signals we’re interested in (TRST, TCK, TMS, TDI, TDO) are assigned in the range of GPIOs 22-27 for the ALT4 function. Next we want to pull up the schematic of our Raspberry Pi 3 B, and see what each of those map to on the GPIO header. I’ve created the table below to keep things straight.

JTAG SignalBCM283x GPIO #Raspberry Pi 3B J8 Pin #
TRSTGPIO22P15
TCKGPIO25P22
TMSGPIO27P13
TDIGPIO26P37
TDOGPIO24P18
GNDmanyP6

Once we’ve got these figured out we’ve got to prep the Pi for JTAG usage. This is the simplest part in the whole setup. On the Pi’s SD card, add the following line to the config.txt. 

enable_jtag_gpio=1

Finally, we’re ready to hook up our JTAG debugger. Looking in the documentation for the OpenOCD FT232R configuration, we find the following table which shows us which RS232 signals correspond to which JTAG signals. We need to (powered down of course!) hook up our FT232R module/cable and Pi accordingly, and don’t forget the ground wire!


    - RXD(5) - TDI
    - TXD(1) - TCK
    - RTS(3) - TDO
    - CTS(11) - TMS
    - DTR(2) - TRST
    - DCD(10) - SRST

Once things are hooked up, we need to setup our configuration for the OpenOCD tool. The default config from the ft232r.cfg is sufficient for the interface, but I wanted to add one item and to get us debugging we need to tell OpenOCD how to connect to the Pi and its four cores. I’ve based my rpi3b.cfg config off of a fellow GitHub contributor’s config but made some modifications.

ft232r.cfg

adapter driver ft232r
adapter speed 3000
ft232r_restore_serial 0x15

I modified the ft232r.cfg to increase the adapter speed to 3M (3000 kHz) and to restore the port config when OpenOCD is done so the adapter can be used as a serial device again.

rpi3b.cfg

transport select jtag

adapter speed 3000

reset_config trst_and_srst

jtag_ntrst_delay 500

if { [info exists CHIPNAME] } {
  set _CHIPNAME $CHIPNAME
} else {
  set _CHIPNAME rpi3
}

if { [info exists DAP_TAPID] } {
   set _DAP_TAPID $DAP_TAPID
} else {
   set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME tap -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_DAP_TAPID -enable
dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.tap

set _TARGETNAME $_CHIPNAME.a53
set _CTINAME $_CHIPNAME.cti

set DBGBASE {0x80010000 0x80012000 0x80014000 0x80016000}
set CTIBASE {0x80018000 0x80019000 0x8001a000 0x8001b000}
set _cores 4

for { set _core 0 } { $_core < $_cores } { incr _core } {

    cti create $_CTINAME.$_core -dap $_CHIPNAME.dap -ap-num 0 \
        -ctibase [lindex $CTIBASE $_core]

    target create $_TARGETNAME.$_core aarch64 \
        -dap $_CHIPNAME.dap -coreid $_core \
        -dbgbase [lindex $DBGBASE $_core] -cti $_CTINAME.$_core

    $_TARGETNAME.$_core configure -event reset-assert-post "aarch64 dbginit"
}

Putting it All Together

Now we have all the pieces we need to debug using our JTAG adapter. Let’s begin!

jacob@jacob-aspire-mint:/opt/apps/openocd$ sudo ./src/openocd -f ./ft232r.cfg -f ./rpi3b.cfg 
Open On-Chip Debugger 0.10.0+dev-01047-g09ac9ab1 (2020-02-04-09:11)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
FT232R restore serial: 0x0015 (enabled)

Warn : Transport "jtag" was already selected
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 3000 kHz
Info : JTAG tap: rpi3.tap tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd.), part: 0xba00, ver: 0x4)
Info : rpi3.a53.0: hardware has 6 breakpoints, 4 watchpoints
Info : rpi3.a53.1: hardware has 6 breakpoints, 4 watchpoints
Info : rpi3.a53.2: hardware has 6 breakpoints, 4 watchpoints
Info : rpi3.a53.3: hardware has 6 breakpoints, 4 watchpoints
Info : Listening on port 3333 for gdb connections
Info : Listening on port 3334 for gdb connections
Info : Listening on port 3335 for gdb connections
Info : Listening on port 3336 for gdb connections

Now we’re cooking! You can connect GDB up to each core, debug that way, or use the OpenOCD interface, see below:

OpenOCD Interface

acob@jacob-aspire-mint:/tmp/openocd$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> halt
rpi3.a53.3 cluster 0 core 3 multi core
target halted in AArch64 state due to debug-request, current mode: EL3H
cpsr: 0x000003cd pc: 0x20001c
MMU: disabled, D-Cache: disabled, I-Cache: disabled
> targets
    TargetName         Type       Endian TapName            State       
--  ------------------ ---------- ------ ------------------ ------------
 0  rpi3.a53.0         aarch64    little rpi3.tap           running
 1  rpi3.a53.1         aarch64    little rpi3.tap           running
 2  rpi3.a53.2         aarch64    little rpi3.tap           running
 3* rpi3.a53.3         aarch64    little rpi3.tap           halted

> reg
===== Aarch64 registers
(0) x0 (/64): 0x0000000000000003 (dirty)
(1) x1 (/64): 0x00000000C1000000
(2) x2 (/64)
(3) x3 (/64)
(4) x4 (/64)
(5) x5 (/64)
(6) x6 (/64)
(7) x7 (/64)
(8) x8 (/64)

[ ... snip ... ]

GDB Interface

jacob@jacob-aspire-mint:/tmp/openocd$ aarch64-none-elf-gdb
GNU gdb (GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)) 8.3.0.20190709-git
Copyright (C) 2019 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=x86_64-pc-linux-gnu --target=aarch64-none-elf".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://bugs.linaro.org/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word".
(gdb) target remote :3333
Remote debugging using :3333
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
0x0000000000200028 in ?? ()
(gdb) si
0x000000000020002c in ?? ()
(gdb) si
0x0000000000200074 in ?? ()
(gdb) si
0x0000000000200078 in ?? ()
(gdb)

Wrapping Up

Now we have a JTAG solution that can debug many, many flavors of processors and microcontrollers given the right configuration. It becomes even more useful if your FT232R module supports selecting the logic level voltage like mine does. See below for some pros and cons of this approach.

Pros

This is a quick and dirty way to get a JTAG adapter at no cost if you’ve already got these FTDI chips laying around. It’s quick and fully configurable (check out the OpenOCD config pages for all it can do) and makes a great debugger.

Cons

Since we are bit-banging our way to success here, it is a bit on the slow side. It’s not unusable, but it is slower than a native interface. If you don’t have one of these chips already at your disposal, I’d opt for one of the FT232H or better yet the FT2232H, both of which have an MPSSE engine which greatly improves emulation.