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<\/em><\/strong> 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<\/a> shipped, but the full featured J-Link is still ~$400, which is more than I want to pay as a hobbyist.<\/p>\n\n\n\n The JTAG TAP port consists of a few standard signals which essentially give you complete control over the systems in the JTAG chain<\/em>. 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<\/a> for a visual representation.<\/p>\n\n\n\n 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!<\/p>\n\n\n\n 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<\/a> 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. <\/p>\n\n\n\n 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).<\/a> <\/p>\n\n\n\n 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!<\/p>\n\n\n\n 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. <\/p>\n\n\n\n Go get the source from the GitHub mirror here<\/a> and drop it in a working directory. I would also read the README for any dependencies you didn’t have already on your machine.<\/p>\n\n\n 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. <\/p>\n\n\n 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.<\/p>\n\n\n 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). <\/p>\n\n\n 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<\/em>, i.e., the Raspberry Pi 3. We need to know which pins on the GPIO header correspond to which JTAG signals. <\/p>\n\n\n\n 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.<\/em>) 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 <\/a>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<\/a>, and see what each of those map to on the GPIO header. I’ve created the table below to keep things straight.<\/p>\n\n\n\nWhat does it do?<\/h3>\n\n\n\n
JTAG for the Hobbyist<\/h2>\n\n\n\n
Enter OpenOCD<\/h3>\n\n\n\n
Building OpenOCD with the Right Interfaces<\/h3>\n\n\n\n
Grab the Source<\/h4>\n\n\n\n
\njacob@jacob-aspire-mint:\/tmp$ git clone https:\/\/github.com\/ntfreak\/openocd.git\nCloning into 'openocd'...\nremote: Enumerating objects: 74, done.\nremote: Counting objects: 100% (74\/74), done.\nremote: Compressing objects: 100% (53\/53), done.\nremote: Total 62845 (delta 36), reused 50 (delta 21), pack-reused 62771\nReceiving objects: 100% (62845\/62845), 24.17 MiB | 24.90 MiB\/s, done.\nResolving deltas: 100% (51571\/51571), done.\njacob@jacob-aspire-mint:\/tmp$ \n\n<\/pre><\/div>\n\n\n
Run the bootstrapper<\/h4>\n\n\n\n
\njacob@jacob-aspire-mint:\/tmp\/openocd$ .\/bootstrap \n+ aclocal\n+ libtoolize --automake --copy\n+ autoconf\n+ autoheader\n+ automake --gnu --add-missing --copy\nconfigure.ac:26: installing '.\/compile'\nconfigure.ac:37: installing '.\/config.guess'\nconfigure.ac:37: installing '.\/config.sub'\nconfigure.ac:16: installing '.\/install-sh'\nconfigure.ac:16: installing '.\/missing'\nMakefile.am:46: warning: wildcard $(srcdir: non-POSIX variable name\nMakefile.am:46: (probably a GNU make extension)\nMakefile.am: installing '.\/INSTALL'\nMakefile.am: installing '.\/depcomp'\nMakefile.am:23: installing '.\/mdate-sh'\nMakefile.am:23: installing '.\/texinfo.tex'\nSetting up submodules\nSubmodule 'jimtcl' (http:\/\/repo.or.cz\/r\/jimtcl.git) registered for path 'jimtcl'\nSubmodule 'src\/jtag\/drivers\/libjaylink' (http:\/\/repo.or.cz\/r\/libjaylink.git) registered for path 'src\/jtag\/drivers\/libjaylink'\nSubmodule 'tools\/git2cl' (http:\/\/repo.or.cz\/r\/git2cl.git) registered for path 'tools\/git2cl'\nCloning into '\/tmp\/openocd\/jimtcl'...\nwarning: redirecting to https:\/\/repo.or.cz\/r\/jimtcl.git\/\nCloning into '\/tmp\/openocd\/src\/jtag\/drivers\/libjaylink'...\nwarning: redirecting to https:\/\/repo.or.cz\/r\/libjaylink.git\/\nCloning into '\/tmp\/openocd\/tools\/git2cl'...\nwarning: redirecting to https:\/\/repo.or.cz\/r\/git2cl.git\/\nSubmodule path 'jimtcl': checked out 'a9bf5975fd0f89974d689a2d9ebd0873c8d64787'\nSubmodule path 'src\/jtag\/drivers\/libjaylink': checked out 'f73ad5e667ae8b26a52b847c603fdadaabf302a6'\nSubmodule path 'tools\/git2cl': checked out '8373c9f74993e218a08819cbcdbab3f3564bbeba'\nGenerating build system...\nlibtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, 'build-aux'.\nlibtoolize: copying file 'build-aux\/config.guess'\nlibtoolize: copying file 'build-aux\/config.sub'\nlibtoolize: copying file 'build-aux\/install-sh'\nlibtoolize: copying file 'build-aux\/ltmain.sh'\nlibtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'm4'.\nlibtoolize: copying file 'm4\/libtool.m4'\nlibtoolize: copying file 'm4\/ltoptions.m4'\nlibtoolize: copying file 'm4\/ltsugar.m4'\nlibtoolize: copying file 'm4\/ltversion.m4'\nlibtoolize: copying file 'm4\/lt~obsolete.m4'\nconfigure.ac:42: installing 'build-aux\/ar-lib'\nconfigure.ac:37: installing 'build-aux\/compile'\nconfigure.ac:30: installing 'build-aux\/missing'\nMakefile.am: installing '.\/INSTALL'\nlibjaylink\/Makefile.am: installing 'build-aux\/depcomp'\nBootstrap complete. Quick build instructions:\n.\/configure ....\njacob@jacob-aspire-mint:\/tmp\/openocd$ \n<\/pre><\/div>\n\n\n
Run the configure script<\/h4>\n\n\n\n
\njacob@jacob-aspire-mint:\/tmp\/openocd$ .\/configure --enable-ft232r \nchecking for makeinfo... no\nconfigure: WARNING: Info documentation will not be built.\nchecking for a BSD-compatible install... \/usr\/bin\/install -c\nchecking whether build environment is sane... yes\nchecking for a thread-safe mkdir -p... \/bin\/mkdir -p\nchecking for gawk... gawk\n\n[ ... snip ... ]\n\nlibjaylink configuration summary:\n - Package version ................ 0.2.0-git-f73ad5e\n - Library version ................ 0:0:0\n - Installation prefix ............ \/usr\/local\n - Building on .................... x86_64-pc-linux-gnu\n - Building for ................... x86_64-pc-linux-gnu\n\nEnabled transports:\n - USB ............................ yes\n - TCP ............................ yes\n\n\n\nOpenOCD configuration summary\n--------------------------------------------------\nMPSSE mode of FTDI based devices yes (auto)\nST-Link Programmer yes (auto)\nTI ICDI JTAG Programmer yes (auto)\nKeil ULINK JTAG Programmer yes (auto)\nAltera USB-Blaster II Compatible yes (auto)\nBitbang mode of FT232R based devices yes\nVersaloon-Link JTAG Programmer yes (auto)\nTI XDS110 Debug Probe yes (auto)\nOSBDM (JTAG only) Programmer yes (auto)\neStick\/opendous JTAG Programmer yes (auto)\nAndes JTAG Programmer yes (auto)\nUSBProg JTAG Programmer no\nRaisonance RLink JTAG Programmer no\nOlimex ARM-JTAG-EW Programmer no\nCMSIS-DAP Compliant Debugger no\nCypress KitProg Programmer no\nAltera USB-Blaster Compatible no\nASIX Presto Adapter no\nOpenJTAG Adapter no\nSEGGER J-Link Programmer yes (auto)\n\n<\/pre><\/div>\n\n\n
Build it<\/h4>\n\n\n\n
\njacob@jacob-aspire-mint:\/tmp\/openocd$ make\nMakefile:4634: warning: overriding recipe for target 'check-recursive'\nMakefile:4045: warning: ignoring old recipe for target 'check-recursive'\ncat 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; }\ncp src\/jtag\/drivers\/minidriver_imp.h src\/jtag\/minidriver_imp.h\nmake all-recursive\nmake[1]: Entering directory '\/tmp\/openocd'\nMakefile:4634: warning: overriding recipe for target 'check-recursive'\nMakefile:4045: warning: ignoring old recipe for target 'check-recursive'\nMaking all in jimtcl\nmake[2]: Entering directory '\/tmp\/openocd\/jimtcl'\n\n\n[ ... snip ... ]\n\nlibtool: link: ranlib src\/.libs\/libopenocd.a\nlibtool: link: rm -fr src\/.libs\/libopenocd.lax src\/.libs\/libopenocd.lax\nlibtool: link: ( cd "src\/.libs" && rm -f "libopenocd.la" && ln -s "..\/libopenocd.la" "libopenocd.la" )\ndepbase=`echo src\/main.o | sed 's|[^\/]*$|.deps\/&|;s|\\.o$||'`;\\\ngcc -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 &&\\\nmv -f $depbase.Tpo $depbase.Po\n\/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 \nlibtool: 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\nmake[2]: Leaving directory '\/tmp\/openocd'\nmake[1]: Leaving directory '\/tmp\/openocd'\n<\/pre><\/div>\n\n\nTesting OpenOCD<\/h3>\n\n\n\n