SOC DEBUGJTAG, OpenOCD and friends

Robert Jarzmik <robert.jarzmik@free.fr>

Plan

1. JTAG1. Overview

2. Goals

3. Wirings

4. Heart : state machine

5. JTAG Instructions

2. OpenOCD1. Overview

2. Example setup

3. OpenOCD building blocks

4. Flows

5. Configuration

3. Demo

2/27

JTAG Overview, Concepts, Electronics, Flow

3/27

JTAG: Overview

• Purpose: a software tool to enable hardware debug• Initially a tool for Silicon Validation teams

• Goals :• Logic analyzer without specific equipment

• Very simple interface

• Capable of deep hardware inspection

• External to software

• Philosophy• One controller to rule them all, several analyzed devices

• Controller is omnipotent

• Devices are slaves, without any initiative possibility

4/27

JTAG: electronics vs software

• Electronics

• Boundary Scan

• Electrical Interface manipulation

• Software

• Core IP manipulation

• Break/Resume

• Register modification

• Etc …

• A “gdb” like for SoC, without common requirements :• Might have no RAM

• Might not be powered

5/27

JTAG: wires, chains and controllers

Controller: controls TCK and TMSChain: each device’s output is connected to the following device inputConcepts :- shifting in data- shifting out data at the

same time

TCK: clock signalTMS: state machine controlTDI: input dataTDO: output data

6/27

JTAG: registers IR + DR

• Only 2 registers : Instruction and Data

• At one point in time :• One and only one instruction is active (the active IR)

• All data operations (update DR, shift DR, capture DR) act on a SoCregister selected by the IR

• The Data register can be :• Updated : load operation from SoC/IP to DR

• Shifted : DR is bit by bit shifted in from TDI and shifted out on TDO=> no read possible without a write at the same time

• Captured : write operation from DR to SoC IP

• The Instruction register follows the same semantics• Updating the IR is almost never done

7/27

JTAG: state machine, the heart

8/27

JTAG: outstanding instructions (IR)

BYPASS: on next TCK cycle, TDO(n) = TDI(n-1) => enables chainIDCODE: on next Update-DR, loads JTAG id into DR => TDO(n..n+x) = IDCODE[0..x]BSCAN: on next Update-DR, loads all scan cells into DR => TDO(n..n+nb_cells) = boudary cell values

9/27

JTAG: typical debug flow

• Let’s assume :• a single device controlled

• IR length of 4 bits

• A typical JTAG flow to place a breakpoint :• Put the JTAG device in reset state (5 times TMS=1)

• Input the specific JTAG IR “IR_BREAK” (0b0010)

• Go to Capture-IR

• Do 4 times TMS=0, TDI=[0, 0, 1, 0] : stay in Shift-IR

• Go to Update-IR => IR_BREAK instruction programmed

• Input the IR_BREAK data, assuming a 32 bits address

• Go to Capture-DR

• Do 32 times TMS=0, TDI=[bits of break address]

• Go to Update-DR => breakpoint is actually programmed

10/27

OPENOCD Overview, Architecture, Examples

11/27

OpenOCD: Overview

• Free software controlling a JTAG controller (TAP)

• Offers several interfaces over TCP/IP:• telnet for low level configuration• Gdb server: for gdb “target remote”• Tcl

• Runs on a PC host (linux or windows)• Usually relies on a JTAG Dongle

12/27

OpenOCD: a usage example

MioA701Smartphone

USB Blaster

TCK

TMS

TDI

TDO

GND

USB OpenOCD

TelnetMainly reset

control

GdbMain debug

13/27

OpenOCD: architecture

• X Server: transform command into target API call

• Target driver: transform “Break” into an IR and a DR, handle target FSM

• JTAG driver: transform jtag scans (IR/DR) and JTAG FSM moves into “USB” instructions

• Core: bind it allMio A701

JTAG Abstraction (jtag.h)

JTAG hardware driverWiggler, PLD cables, FT2232, ...

JTAG

Target specific code

GDB Server Telnet Server

Target Abstraction (target.h)

GDB Telnet client

14/27

OpenOCD: initial launch

• Launching openOCD triggers :• Configuration parsing

• JTAG adapter initialization

• JTAG scan for device discovery

• Requires configuration for IR length

• Relies on IDCODE + BYPASS Irs

• Preparing incoming TCP services

• Gdb service

• telnet service (first and main interaction point)telnet localhost 3333

• Depending on configuration :• Board is reset

15/27

OpenOCD: reset control

• Most important thing to master in openOCD

• A “reset halt” commands does several things :• Reset the board (usually through nSRST signal)

• Hold the reset

• Do things while in reset

• Especially upload a debug handler !!!

• And trap vectors !!!

• Release reset

• If no “reset” command passed, debugging doesn’t work

• ARM Vector can be a headache (low vectors versus high vectors)

16/27

OpenOCD: telnet interface

• Target state manipulation• poll, halt, resume, step, reset

• Memory access

• md[bhw], mw[bhw]

• load_binary

• dump_binary

• Breakpoint/Watchpoint handling

• [r]bp, [r]wp

• Flash handling

• probe, erase, write, erase_check, protect_check

• JTAG control

• var, field

• irscan, drscan, statemove, runtest, endstate, jtag_reset

• Reset modes

• run, halt, init, run and halt

• JTAG configuration

• interface, jtag_device, reset_config, jtag_speed

17/27

OpenOCD: typical initialization

• Launch openocd• Let’s suppose your configuration file is already set

• The JTAG adapter is detected

• All JTAG devices are identified by JTAG scan

• At least one target takes control of a JTAG device

• telnet localhost 3333• Reset halt

• Target halted state must be reached

• If not, amend your config

• Don’t forget : your DRAM is not functional yet !!!

• Mww 0x4130004 0x10 (clock the SRAM)

• Load_image /tmp/barebox.bin 0xc0000000 bin (into SRAM)

• Resume 0xa0000000

• halt

18/27

OpenOCD: JTAG configuration

• File openocd.cfg• First step: declare the JTAG

dongle• /usr/share/openocd/scripts/interfac

e• Your dongle should be there• If not, become an openocd

contributor !

• Launch openocd :• Openocd –d3 –f openocd.cfg• Nothing exciting yet

## USB-Blaster II clone setup#source [find interface/altera-usb-blaster.cfg]usb_blaster_pin pin6 1usb_blaster_pin pin8 1usb_blaster_lowlevel_driverlibusbusb_blaster_lowlevel_driver ftdi# Now #SRST is soldered to usb_blaster pin6, use it.usb_blaster_pin pin6 susb_blaster_pin pin8 t

19/27

OpenOCD: target configuration

• Add a target• Sets up the JTAG IR-length for this

target• Sets up the IDCODE for this target• Enables the JTAG discovery

## USB-Blaster II clone setup#source [find interface/altera-usb-blaster.cfg]usb_blaster_pin pin6 1usb_blaster_pin pin8 1usb_blaster_lowlevel_driver libusbusb_blaster_lowlevel_driver ftdi# Now #SRST is soldered to usb_blaster pin6, use it.usb_blaster_pin pin6 susb_blaster_pin pin8 treset_config trst_and_srstsource [find target/pxa270.cfg]

source [find target/pxa270.cfg]

set _CHIPNAME pxa270if { [info exists CPUTAPID ] } {

set _CPUTAPID $CPUTAPID} else {set _CPUTAPID 0x49265013}set _TARGETNAME $_CHIPNAME.cpu

jtag newtap $_CHIPNAME cpu -irlen 7 -ircapture 0x1 -irmask 0x7f -expected-id $_CPUTAPID

target create $_TARGETNAME xscale -endian $_ENDIAN -chain-position $_TARGETNAME -variant pxa27x

20/27

OpenOCD: reset configuration

• Reset_config• Configure nSRST usage• Configure nTSRT usage• Relies on JTAG dongle wiring

(ie. is nSRST pulled down to ground, floating, etc …)

• Relies on board wiring (ie. is nSRST pulled down, etc …)

• Events• Enable additional actions

upon reset• Typically when action should

be perfomed upon reset init(clocks ungating, might even be DRAM init, …)

## USB-Blaster II clone setup#source [find interface/altera-usb-blaster.cfg]usb_blaster_pin pin6 1usb_blaster_pin pin8 1usb_blaster_lowlevel_driver libusbusb_blaster_lowlevel_driver ftdi# Now #SRST is soldered to usb_blaster pin6, use it.usb_blaster_pin pin6 susb_blaster_pin pin8 tsource [find target/pxa270.cfg]

reset_config srst_only srst_push_pull

# Configure reset init$_TARGETNAME configure -event reset-init {# Enable GPIO reset all timemww 0x40f0001c 0x00000030 ;# PCFR:

PCFR_GPR_EN}

21/27

OpenOCD: custom functions

• Define your own shortcuts• TCL based• Telnet mode functions available• Don’t type 10x the same thing !

• Automate vectors trickeries• Know your target debug

handler• Know how interrupts/aborts are

trapped• Know how vector table is

handled by target debug handler (openocd target handling code)

## USB-Blaster II clone setup#source [find interface/altera-usb-blaster.cfg]usb_blaster_pin pin6 1usb_blaster_pin pin8 1usb_blaster_lowlevel_driver libusbusb_blaster_lowlevel_driver ftdi# Now #SRST is soldered to usb_blaster pin6, use it.usb_blaster_pin pin6 susb_blaster_pin pin8 tsource [find target/pxa270.cfg]reset_config srst_only srst_push_pull

# Configure reset init$_TARGETNAME configure -event reset-init {

# Enable GPIO reset all timemww 0x40f0001c 0x00000030 ;# PCFR: PCFR_GPR_EN

}

proc kernel_prep {} {reset initmww 0x40f0001c 0x00000030 ;# PCFR:

PCFR_GPR_ENxscale vector_catch reset irqresumewait_halt 80000xscale vector_catch resetresume

}

22/27

OpenOCD: misc configuration

23/27

OpenOCD: typical bootloader flow

reset initxscale vector_catch reset dabt pabtundef

mww 0x4130000 0x20 # Provide clock to SRAMload_image /tmp/barebox.bin0xa0000000 binresume 0xa0000000…

haltbp 0xa3001234 4 hwresume… SoC halts …

regresume

• Put the board in a known initial state, and prepare to halt on any trap

• Power on the SRAM• Load the bootloader into the

SRAM

• Place a breakpoint on a function which is known to misbehave

• Dump ARM registers• Connect gdb : target remote

localhost:3333, bt

Initialize

Load

Prepare

Debug

24/27

OpenOCD: typical kernel flow

reset initxscale vector_catch reset irqresume

… barebox> boot kernel… wait for IRQ trap

xscale vector_catch reset…halt

regresume

• Put the board in a known initial state, and prepare to halt on first interrupt (install openocd vector traps)

• Rely on typical bootloadercapabilities to load the kernel

• Remove IRQ trap• Let the kernel run• Stop

• Dump ARM registers• Connect gdb : target remote

localhost:3333, bt

Initialize

Load

Prepare

Debug

25/27

OpenOCD: logs of success/failures

Success

:~$ openocdOpen On-Chip Debugger 0.9.0-dev-00131-gbd0409a (2014-08-31-11:59)Licensed under GNU GPL v2For bug reports, read

http://openocd.sourceforge.net/doc/doxygen/bugs.htmlWarn : Adapter driver 'usb_blaster' did not declare which transports it allows; assuming legacy JTAG-onlyInfo : only one transport option; autoselect 'jtag'trst_and_srst separate srst_gates_jtag trst_push_pullsrst_open_drain connect_deassert_srstadapter_nsrst_delay: 260jtag_ntrst_delay: 250Info : pxa270.cpu: hardware has 2 breakpoints and 2 watchpointskernel_prepInfo : usb blaster interface using libftdiInfo : This adapter doesn't support configurable speedInfo : JTAG tap: pxa270.cpu tap/device found: 0x79265013 (mfg: 0x009, part: 0x9265, ver: 0x7)

Failure

:~$ openocdOpen On-Chip Debugger 0.9.0-dev-00131-gbd0409a (2014-08-31-11:59)Licensed under GNU GPL v2For bug reports, read

http://openocd.sourceforge.net/doc/doxygen/bugs.htmlWarn : Adapter driver 'usb_blaster' did not declare which transports it allows; assuming legacy JTAG-onlyInfo : only one transport option; autoselect 'jtag'trst_and_srst separate srst_gates_jtag trst_push_pullsrst_open_drain connect_deassert_srstadapter_nsrst_delay: 260jtag_ntrst_delay: 250Info : pxa270.cpu: hardware has 2 breakpoints and 2 watchpointskernel_prepInfo : usb blaster interface using libftdiInfo : This adapter doesn't support configurable speedError: JTAG scan chain interrogation failed: all zeroesError: Check JTAG interface, timings, target power, etc.Error: Trying to use configured scan chain anyway...Error: pxa270.cpu: IR capture error; saw 0x00 not 0x01Warn : Bypassing JTAG setup events due to errors

26/27

Thanks for attending.

27/27