I want to program the Programmable Real-Time Unit (PRU) [r22] available on the Texas Instruments Sitara™ AM335x processors via a JTAG debug connection. I use a "bare metal" BeagleBone Black (BBB) without a bootloader and therefore without running Linux. The goal is to use the BBB in unit testing embedded software on microcontrollers (MCU) where the BBB and the MCU under test are both controlled via Code Composer Studio in a common debug session. The PRU allows for deterministic and fast stimulus since it does not use caching or interrupts that could affect the timing behavior. In the following notes, I cover the steps required to start a debug session on the PRU, the unit testing strategy will be discussed in a separate document.

The project files can be cloned from the compagnion repo.

1. Introduction

The Beagle Bone Black, revC (13/2017), described in detail in the System Reference Manual SRM, comes with the Sitara AM3358BZCZ100 processor, a SoC (system on chip) that includes a 1-Ghz Cortex A8 processor and two independent PRUs (Programmable Realtime Unit). These are independent cores, specifically designed for real-time requirements. In particular, they allow for deterministic digital I/O operations.

The BBB can provisioned in two different ways:

  1. installing a bootloader to boot and run a suitable Linux distribution, like TI’s Proessor SDK for AM335x processors,

  2. opening a JTAG debug connection for example (but not restricted to) with TI’s Code Composer Studio (CCS) IDE.

The latter is the focus of this document.

2. Preparing the hardware

In order to program and debug a PRU, I need:

  • The BBB itself, from one of the distributors here [r5] or from reichelt.

  • The BBB comes without a JTAG header connector. It must be purchased separately (see also [r2], [r3]) and soldered on the bottom side of the BBB.

  • A compatible debug probe like the XDS110 JTAG Debug Probe which comes with the required cables.

a more powerful alternative is the XSD200.

In addition, I purchased the following optional items:

BOM - optional items
  • The PRU Cape is an extension board to get started with PRU programming.

  • The USB to Serial cable mentioned in the [r1], Fig. 54, can be used to establish a serial communication with the host. It is not suitable for simultaneous usage with the PRU Cape, because the Cape will render the header on the BBB inaccessible.

I made sure to get a 3.3 V version of the FTDI connector to match the voltage on the BBB.
  • a standard RS232 serial monitor cable. This can be connected to the UART of the PRU cape (rather than the hidden serial header on the BBB) and allows for serial communications with the host PC.

Before soldering the fine pitch JTAG header, I wanted to refresh my soldering skills. I found the video tutorials by John Gammel most helpful:

  1. don’t worry about shorts until finished,

  2. to remove shorts, don’t use solder wig, use flux.

testing for shorts with an ohmmeter will apply a small voltage to the pins of the Sitara processor. Strictly speaking, this voids the warranty as explained in the [r1].

The complete hardware setup:

debug configuration
Figure 1. Debug configuration

A closeup showing the key (missing pin on the JTAG header):

JTAG connector
Figure 2. The JTAG header with the missing pin (key)

2.1. Preventing Linux from booting

The BBB comes with Linux flashed to the onboard eMMC. To prevent Linux from booting I hold the boot switch pressed when applying power. This switch is not easily accessible with the PRU Cape mounted. I check that the heartbeat indicator LED does not flash as this would mean that the board is still booting.

The are many tutorials available on how not to boot from the eMMC, none of which worked for me. So I settled for the brute force approach and erased the eMMC.

This will completely erase the device mmcblkx, where x depends on the configuration. With no SDCard inserted x is probably 0. I use fdisk -l to discover the available devices.
Erase the boot device - x is configuration dependent
$ dd if=/dev/zero of=/dev/mmcblkx bs=2M count=2048

Now, when I apply power, only the power LED is permanently on.

it seems as if this is still not enough. When I connect the BBB to the host, the Network Manager App periodically shows "Connection failed" notifications. Apparently, the BBB tries to open a Ethernet-over-USB connection, which means that at least the bootloader is still present. TODO.

3. Installing the software development environment

I installed CCS 9.2 from Code Composer Studio Downloads on Linux Mint 19.2.

From the CCS App Center, I installed the PRU C compiler option.

I cloned the PRU Software Support Package as a git submodule into the compagnion repo.

$ cd <compagnion repo dir>
$ git submodule add https://git.ti.com/cgit/pru-software-support-package/pru-software-support-package

Therefore, if I clone the companion repo, I need to say;

$ git clone --recurse-submodules https://github.com/vittali/vittali.ch-bbb-jtag

3.1. Getting started with the Hand-on Labs

Based on Lab1 from PRU Training: Hands-on Labs:

  1. When importing the project, I unchecked Copy project into workspace. If the project gets copied in the workspace the include definitions will be wrong and the project won’t compile without modifiation.

  2. I did create a target configuration BBB.ccxml.

  3. I did not change the initialization script as explained in (8).

  4. I created a default Debug Configuration by starting a first debug session. This session fails because the initialization script is missing.

  5. I open the newly created Debug Configuration and select the initialization script bbb_pru_startup.js provided in the compagnion repo:

init script
Figure 3. Selecting the initialization script

I can now debug and test the Lab1 demo,

4. Test

I start a second debug session, this time with the correct initialization script. After downloading the project to the BBB, the debugger will stop at main. Running the project will make the LEDs on the PRU Cape blink.

Since I did not copy the project files into the workspace ( to maintain the include paths), I created files directly in the submodule directories. Since I can’t push to the submodule repo, I could now add a new git remote to which I can push my changes.

A complete and ready to debug project PRU_LED0 is available in the compagnion repo.

5. References

Beagle Bone Black (BBB)

Sitara Processor

PRU (Programmable Realtime Unit)

  • [r21] PRU Cape Getting started. A short guide presenting the hardware on the cape.

  • [r22] PRU-ICSS. The Programmable Real-Time Unit Subsystem and Industrial Communication SubSystem (PRU-ICSS) wiki. This is the main entry point to PRU related resources.

  • [r23] Hands-on Labs. Practical examples on PRU programming. Not sure if outdated ??

  • [r24] PRU C code . A very good introduction to C programming on the PRU.

  • [r25] Debug PRU with CCS.

  • [r26] wiki page. Dedicated to bare bones PRU programming on the Sitara processor. Very useful to get started.

  • [r27] Debug PRU with CCS. Audio presentation, very useful to get started.

Debug hardware

5.1. JTAG debugging

Some launchpads contain debug probes that can be isolated. Such a launchpad (< 15 USD) could thus be used as a super-low cost debug probe for the BBB. But this requires a set of expensive fine pitch connectors and ribbon cable (not tested) : 1, 2, 3, 4.

I would also need to design and order a couple of printed circuit board adapters. Here are a couple of useful links: