Software for JTAG Boundary Scan
Street View for Circuit Boards, Part Two
In Part One, we looked at JTAG boundary scan as a way to see into circuit boards, much like Street View in Google Maps lets you peer into neighborhoods and look at streets and buildings. Now, in Part Two, we’ll install some software for JTAG boundary scan.
Combining the utilitarian software presented here into a custom suite can earn you the right-to-repair. Commercially available boundary scan software is purpose-driven. Text-based software, often written in Python or TCL/Tk, is for downloading firmware to programmable devices on your board. Graphical tools available from IC manufacturers display waveforms and timing diagrams. Full-featured software, such as Corelis ScanExpress, checks for shorted or unconnected wiring (common circuit board flaws), but comes at a premium price covering support for the shop floor.
If you are an end user looking for a graphical tool similar to Street View that can fully visualize the traffic and infrastructure of the board, there are no complete options. The community needs developers to take up that cause — maybe you’ll help with that?
So what are the software components you’ll need on this journey? You’ll be using four open source packages: OpenFPGALoader, Viveris JTAG Boundary Scanner, PyOCD, and OpenOCD.
A Quick Round Trip
Whichever board you choose to purchase and whichever software suite supports it, your first experience will be to connect the JTAG probe and detect the ICs on the development board. Think of this as a mapping exercise.
Maps are made so that the person who discovers a place can return with forehand knowledge. JTAG boundary scan software will allow you to follow breadcrumbs along a JTAG chain; you’ll leave no footprints, but you’ll learn a little about the things to see along the way. Record what you discover with the tools you’ll learn about in this article.
Your job on your first visit is simply to return. What you learn on your first trip is the number of chips that use JTAG on your device, and an ID code for each. Then, each time you visit, you’ll find a path to add more detail to what you know.
OpenFPGALoader
You may remember from Part One of this series that I used the Lattice MachXO3L Starter Kit. One open-source project you can use to communicate with this board is OpenFPGALoader. You can clone this repository from GitHub.
git clone https://github.com/trabucayre/openFPGALoaderOpenFPGALoader is a full-featured, well-documented, object-oriented code-base in C++ and licensed under Apache version 2.0. You’ll find the complete guide in the gh_pages branch of the GitHub repository or here.
You can build and run the software without installing. I’ve summarized the instructions for Linux here:
sudo apt -y install \
libftdi1-2 \
libftdi1-dev \
libhidapi-hidraw0 \
libhidapi-dev \
libudev-dev \
zlib1g-dev \
cmake \
pkg-config \
make \
g++
pushd openFPGALoader
mkdir -p build
cd build
cmake ..
cmake --build .After a successful build, you’ll see the executable named openFPGALoader at the top of the build folder.
You’ll find a complete list of all the boards you can access with OpenFPGALoader online or you can generate this list from the executable you just built using the command ./openFPGALoader --list-boards.
Most of these boards connect to your computer via USB. Under Linux, you’ll need to set up UDEV rules to allow non-root access to the devices. From the build folder, you’ll need the following commands to configure these rules.
sudo useradd -G plugdev $USER
sudo cp ../99-openfpgaloader.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm triggerThe first command in that list adds you to the Linux group plugdev if you are not already a member. Being added to a group and being granted the privileges thereof are not necessarily the same: if in doubt, log back in after you first log out.
With the group membership and udev rules configured as above, you can use OpenFPGALoader to perform boundary scan exercises. The process is as simple as connecting the board and issuing the following command:
./openFPGALoader --detectHere’s the response that comes back when I have the MachXO3L Starter Kit attached:
Jtag frequency : requested 6.00MHz -> real 6.00MHz
index 0:
idcode 0x12bd043
manufacturer lattice
family MachXO2
model LCMXO2-7000HC
irlength 8The response above says, in so many words, the following:
- The program found the JTAG probe attached to the computer.
- It communicated with the attached hardware at a speed of 6 Mb per second.
- It found one chip on the attached hardware: that chip was identified by an ID code of 0x12bd043 as being the Lattice LCMXO2–7000HC. That’s not exactly right, but it’s the ID code that matters, as you’ll see shortly.
- The IR length is reported as 8-bits. This is the number of bits that you’d send across the TDI lines when the instruction register (IR) is selected.
Planning Your Next Tour
In the previous section, OpenFPGALoader set a route through the JTAG circuitry in order to find the ID codes of all connected ICs on your board.
You can tour many routes any number of times while JTAG is active. Each tour begins by selecting between the instruction register (IR) or a data register. The instruction register is like JTAG’s tour guide. Any message flowing from TDI to TDO when the instruction register is selected sets the route that the tour will follow.
The tour starts when you select the data register; TDI and TDO will return the bits snapped at all the places visited along the virtual route. To help interpret the bitstream returned, you’ll want what’s called a BSDL parser.
BSDL stands for boundary scan definition language. Just like doorways and windows are at the boundaries of sky scrapers, pin pads and logic cells are at the boundaries of chips. If you think of chips as buildings, then BSDL files are the floor maps. They tell you how many floors (or data registers) are in each building (or chip) and how many rooms (or serial bits) on on each floor. They’ll also tell you how to ask your tour guide (the IR) to get you to the right destination.
The BSDL file contains everything you need to interpret the payload returned on the JTAG serial interface. In the file are the instruction opcodes you can send: these set the route through which the data-register passes for each chip. Besides IDCODE(the opcode sent by openFPGALoader — detect), three other mandatory opcodes you will see in all BSDL file are EXTEST, SAMPLE and PRELOAD. When either of those three are selected, the length of the data register in bits will be determined by the BOUNDARY_LENGTH attribute of the BSDL file.
Here’s where you’ll end your introduction to OpenFPGALoader. Return to the top-level folder.
popdAs you spend time viewing the BSDL files you’ll appreciate the importance of the BSDL parser provided by the next software repository, Viveris.
Viveris JTAG Boundary Scanner
The next code repository in the list is the Viveris JTAG Boundary Scanner. It’s also available from GitHub.
git clone https://github.com/viveris/jtag-boundary-scannerIf you cloned the repository using the commands I suggested, then you should have a working copy in the folder named jtag-boundary-scanner.
This code is organized in a way that makes it easy to understand. Licensed under the GNU LGPL Version 2.1, it is written in C and comes with build scripts for Linux and Windows.
The repo provides a set of core JTAG routines in the aptly named subdirectory lib_jtag_core. You can build it simply enough under Linux using the following instructions:
pushd jtag-boundary-scanner
cd lib_jtag_core
cd build
cd linux
makeTo reveal features of the library use find ../../src -type d. You should see a listing that roughly matches the following:
../../src/os_interface
../../src/os_interface/win32
../../src/bus_over_jtag
../../src/drivers
../../src/drivers/jlink_jtag
../../src/drivers/ftdi_jtag
../../src/drivers/ftdi_jtag/ftdi
../../src/drivers/lpt_jtag
../../src/drivers/linux_gpio_jtag
../../src/bsdl_parser
../../src/scriptThe file structure makes it clear where to find the code for the operating system interface, whether that OS be Windows or not. It provides drivers to facilitate communication with two ubiquitously supported probes named FTDI and Segger J-LINK. You’ll also see drivers for parallel port (LPT) probes as well as those that access the pins using custom pinouts (GPIO).
Most importantly, you’ll find a BSDL parser. It’s a great starting point to learn how to walk through the layers of information that chip manufacturers release about their technology. In Part 3, you’ll use this library to work directly with BSDL files you download from the BSDL clearing house. (the BSDL file can also be downloaded individually for each chip from the chip manufacturer’s official website).
In addition to drivers and BSDL parsers, the authors of the Viveris software included a scripting language. This bonus feature means that you can use a high-level language to automate common tasks. That’s as deep as we’ll cover Viveris in this article.
Return to your original folder by issuing the following command:
popdFor a further discussion of putting the Viveris code base to full use, checkout Colin O’Flynn’s article on Circuit Cellar. If you are a Python programmer, you’ll also want to make use of his repository.
More Open Sourcery
It’s time to gather more magic ingredients. Use the following to clone the next software repositories:
git clone https://github.com/pyocd/pyOCD
git clone https://github.com/openocd-org/openocd/With the source code at your disposal, let’s take a closer look.
PyOCD
The next program makes the list for its ease of installation and use, as well as the fact that it is based on the popular Python language. You won’t need the source code for PyOCD, but it is available under the Apache Version 2.0 license should you wish to extend it. You’ll also find udev rules under sub-directory of the working folder named udev. We discussed the need for those a little earlier.
With Python version 3 already installed, complete the following steps to install PyOCD and get a list of supported boards:
pip3 install pyocd
pyocd list --targets
pyocd list --boards
pyocd list --pluginsSupported manufacturers and boards include Arm, Cypress, NXP, OnSemiconductor, Nordic Semiconductor, STMicro, and Maxim. If you opt for a development board supported by these manufacturers, PyOCD will be your first step into open source development with JTAG.
Many of the boards with PyOCD are supported thanks to the CMSIS-DAP pack plugin. You’ll find an extensive list of chips that you can communicate with using PyOCD by entering the following command:
pyocd pack find '*' | moreLater on, if you purchase a development board supported by PyOCD, you’ll narrow down the chip that runs on it. You can use CMSIS packs to communicate with the chip. To give you an example, I’ve had good success using PyOCD for Atmel SAML devices. To install the packs use these commands:
pyocd pack find 'atsaml' # prints a list that includes ATSAML21J18B
pyocd pack install ATSAML21J18BText-based software written in Python is often used to program devices over JTAG. PyOCD is an open-source example. For example, you’ve just installed the CMSIS DAP PACK for the ATSAML21J18B. If you needed to upload firmware to a board that hosts that chip, you would use a command like : pyocd load -t atsaml21j18b ./firmware.elf (where you can get that file, named firmware.elf, is a topic for another day).
TCL and OpenOCD
TCL (pronounced tickle by enthusiasts) is a language that integrates well with Python through the python module tkinter. It is extensible, and many IC manufacturers include a TCL interface in their development tool-suites. OpenOCD, which we’ll use next, is a full-featured JTAG library written in TCL and licensed under the GNU General Public License version 2.
You’ll find the definitive list of probes and boards supported by the software using the following directory listing:
pushd openocd
find tcl/interface -name '*.cfg' | more
find tcl/board -name '*.cfg' | moreYou can install OpenOCD using the package manager sudo apt install openocd, but that often comes without the interactive features that help make openocd more approachable.
You can build a current version from source using the following instructions:
./bootstrap
./configure
make
sudo make installWhile OpenOCD comes with support for lots of hardware, you need to have the hardware in hand to experiment and learn the software. For that reason, OpenOCD is best left as a tool to learn after you have some experience with JTAG.
Wrapping Up
JTAG boundary scan, a hardware feature that manufacturers rely on, can help you repair your personal electronics. The four repositories you’ve cloned give you the algorithms you’ll need to get started.
If Python is your language of choice, PyOCD may offer you the best starting point. You should also checkout Colin O’Flynn’s thin wrapper of the Viveris JTAG boundary scan tool. C/C++ programmers may prefer to start with the OpenFPGALoader code base. You’ll soon be using supported JTAG probes to identify what chips are present on the hardware you are debugging. Once you have an ID code for the chips, parse the BSDL files you’ll find online at BSDL.info to interpret the serial data that you recover from the JTAG serial I/O.
Whether you use C or Python, you’ll possibly benefit from TCL code as a scripting engine. It’s got a long history of use with boundary scan and integrates well with both high-level languages.
Decide if writing software for JTAG is for you. If this article piqued your interest, choose a tool chain you like and have in hand a developers kit that it supports.
