-
Notifications
You must be signed in to change notification settings - Fork 0
OpenOCD Getting Started Manual
- This document uses term "Digilent HS" to refer to both HS1 and HS2 cables. Statements, which are applicable only to the selected cable, mention it explicitly. Digilent HS3 hasn't been tested with OpenOCD for ARC.
- There is NO Flash support in ARC OpenOCD.
Install prerequisites for Ubuntu:
sudo apt-get install libtool git-core build-essential autoconf \
automake texinfo libusb-1.0-0 libusb-1.0-0-dev \
pkg-configInstall prerequisites for RHEL/CentOS 7:
sudo yum install libtool gcc autoconf automake texinfo libusb1 libusb1-devel \
git make whichDownload OpenOCD sources and checkout the latest release:
git clone -b arc-2021.09 https://github.com/foss-for-synopsys-dwc-arc-processors/openocd
cd openocd
Configure OpenOCD (use your own --prefix path):
./bootstrap
./configure --enable-ftdi --disable-werror \
--disable-doxygen-html --prefix=/tools/openocd
Also, you can pass --enable-verbose and --enable-verbose-jtag-io options for development activities.
Build and install:
make
make install
Configure your environment (use your own installation path):
export PATH=/tools/openocd/bin:$PATH
Finally you need to configure udev rules in such way that OpenOCD would be able
to claim your JTAG debug cable. In common case for ARC this is an FTDI-based
device. If you already have libftdi package installed on your system, then
required rules are already provided to udev. Otherwise create file
/etc/udev/rules.d/99-ftdi.rules with the following contents:
# allow users to claim the device
# Digilent HS1 and similiar products
SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0664", GROUP="plugdev"
# Digilent HS2
SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", MODE="0664", GROUP="plugdev"
You also can use file contrib/99-openocd.udev supplied with OpenOCD sources,
however this file doesn't work with Digilent HS2, though on the other hand it
mentions many other FTDI-based devices.
Then either reboot your system or reload udev configuration and reconnect debug cable to the host computer:
$ sudo udevadm control --reload-rules
# Disconnect JTAG cable from host, then connect again.
It is possible to use OpenOCD on Windows with FTDI-based debug cables using a
ftdi interface and libusb driver (further down called ftdi/libusb). Note,
however that this requires replacing the original FTDI proprietary drivers with
open source ones. This will render Digilent cable unusable by Digilent tools,
like Adept.
Install the same prerequisites like for Linux build (except for libusb-dev) and MinGW on your system:
$ sudo apt-get install libtool git-core build-essential autoconf automake
texinfo pkg-config
Install MinGW cross-compiler to your system:
$ sudo apt-get install gcc-mingw-w64
Download libusb sources sources. Configure and build them with MinGW compiler. It is recommended to build only static libusb, so that OpenOCD will not need this library's dll file to be copied around:
$ tar xaf libusb-1.0.20.tar.bz2
$ cd libusb-1.0.20
$ ./configure --host=i686-w64-mingw32 --build=x86_64-linux-gnu \
--prefix=</libusbx/install/path> --disable-shared --enable-static
$ make
$ make install
Download OpenOCD sources:
$ git clone https://github.com/foss-for-synopsys-dwc-arc-processors/openocd
$ cd openocd
$ ./bootstrap
Configure OpenOCD. Consult configure --help and generic OpenOCD documentation
for details. This command line is recommended for ARC with libusb/ftdi:
$ PKG_CONFIG_PATH=</libusb/install/path>/lib/pkgconfig ./configure \
--enable-ftdi --host=i686-w64-mingw32 --build=x86_64-linux-gnu \
--disable-werror --prefix=<openocd/install/path>
Note that it is required to set PKG_CONFIG_PATH, otherwise configure script will detect host libusb installation, instead of the one cross-compiled for Windows.
Build and install:
$ make
$ make install
If your application uses libusb and is being linked dynamically (this is by default), copy </libusbx/install/path>/bin/libusb-1.0.dll to the OpenOCD bin directory. Copy OpenOCD installation to Window host.
Connection host is a host that is connected to the debug target via USB cable and runs OpenOCD. Debug host is a hsot that runs GDB, which connects to the OpenOCD with TCP connection. Ehily typically it is the same host, they actually can be different host and it is important to distinguish them.
Connect debug target to the connection host. AXS10x products and EM Starter Kit have built-in debug cable, the don't require a separate Digilent HS cable. HS is required only for other debug targets like ML-509 board, etc.
Run lsusb application to ensure that FTDI device is there:
$ lsusb
In case of HS1, EM Starter Kit and AXS10x there should line like this:
Bus 001 Device 002: ID 0403:6010 Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC
In case if HS2 there should be line like this:
Bus 001 Device 003: ID 0403:6014 Future Technology Devices International, Ltd FT232H Single HS USB-UART/FIFO IC
Note that exact lines could differ from host to host.
Run OpenOCD:
$ openocd -f <openocd.cfg>
Valid openocd.cfg files are installed into
/usr/local/share/openocd/scripts/board/:
- snps_em_sk_v2.3.cfg - ARC EM Starter Kit verison 2.3
- snps_axs101.cfg - ARC AXS101 Software Development platform
- snps_axs103_hs36.cfg - ARC AXS103 in configuration with ARC HS36 core
- snps_hsdk.cfg - ARC HSDK
On the debug host (PC with GDB) start an ELF32 GDB debugger:
$ arc-elf32-gdb ./<elf_app_to_debug>
Make the connection between arc-elf32-gdb and OpenOCD:
(gdb) target remote <connection host ip address>:3333
Load image to be debugged (./<app_to_debug>.elf) into the target memory:
(gdb) load
Set breakpoints at functions main and exit:
(gdb) break main
(gdb) break exit
Start the execution on target of the image to debug, to reach function main:
(gdb) continue
Resume execution to reach function exit:
(gdb) continue
WinUSB driver should be used to allow OpenOCD to connect to debug cable and that driver would replace FTDI proprietary drivers for Digilent cables or EM Starter Kit with it. Refer to this page or this page for details. In a nutshell, download Zadig, run it and use it to install WinUSB driver for FTDI device. If FTDI device is not shown by Zadig, then tick "List all devices" in "Options". Note that antivirus might complain about driver files created by Zadig. After installing the driver everything is the same as on Linux: run OpenOCD, connect to it with GDB, etc.
Connection host is a host that is connected to the debug target via USB cable and runs OpenOCD. Debug host is a hsot that runs GDB, which connects to the OpenOCD with TCP connection. Ehily typically it is the same host, they actually can be different host and it is important to distinguish them.
Connect debug target to the connection host. AXS10x products and EM Starter Kit have built-in debug cable, the don't require a separate Digilent HS cable. HS is required only for other debug targets like ML-509 board, etc.
Run ioreg application to ensure that FTDI device is there:
$ ioreg -p IOUSB -l -w 0
There should be output like this: Digilent USB Device@14100000 <class AppleUSBDevice, id 0x1000015f7, registered, matched, active, busy 0 (5 ms), retain 21> { ... }
Note that exact output could differ from host to host.
If you're using a USB adapter and have a driver kext matched to it, you will need to unload it prior to running OpenOCD. E.g. with Apple driver (OS X 10.9 or later) for FTDI run: sudo kextunload -b com.apple.driver.AppleUSBFTDI for FTDI vendor driver use: sudo kextunload FTDIUSBSerialDriver.kext
Run OpenOCD:
See for tag Run OpenOCD at How to use OpenOCD on Linux.
With the GDB "monitor" command, you have "direct" access to the core without any interference from GDB anymore! With other words, GDB has no notion of changes in core state when using the so called monitor commands (but it is very powerful). In GDB, connect to the OpenOCD target and type following command to get a list of available monitor commands:
(gdb) monitor help
To get a list of some ARC-specific commands, run:
(gdb) monitor help arc
Those are actually internal OpenOCD commands which are also available in
configuration scripts and can be passed in OpeOCD command line with -c ...
options. Those command allow to enabled some extra features of OpenOCD
(disabled by default for one or another reason) or perform some low-level
actions bypassing GDB or even OpenOCD. For example it is possible to write/read
core and aux registers. However some command for register access will be
removed in future, when ARC OpenOCD will fully support flexible register
configurations.
Automake makefile entry starts from: src/target/Makefile.am
In src/target is the ARC specific code base:
Top and bottom interfaces into OpenOCD:
arc.c main hook into OpenOCD framework (target function body)
arc.h main include (gets everywhere included)
arc_jtag.c + .h ARC jtag interface into OpenOCD
Supporting functions/modules as used by above interface into OpenOCD
arc32.c + .h generic ARC architecture functions
arc_core.c + .h ARC core internal specifics
arc_dbg.c + .h ARC debugger functions
arc_mem.c + .h ARC memory functions
arc_mntr.c + .h GDB monitor functions
arc_ocd.c + .h ARC OCD initialization
arc_regs.c + .h ARC register access
arc_trgt.c + .h target/board system functions
OpenOCD doesn't use Digilent drivers to communicate with Digilent debug cables, instead it uses it's own implementation of FTDI MPSSE protocol, which us compatible with virtually any other FTDI x232 cable. However to use some features of Digilent cables you might need to install their drivers and utilities. Following are instructions on how to do that.
Download appropriate version of runtime and utilities from Digilent site: http://www.digilentinc.com/Products/Detail.cfm?Prod=ADEPT2 .
Untar and install products:
$ tar xzfv digilent.adept.runtime_2.10.2-i686.tar.gz
$ cd digilent.adept.runtime_2.10.2-i686
$ sudo ./install.sh
$ cd ftdi.drivers_1.0.4-i686
$ sudo ./install.sh
$ cd ../..
$ tar xvzf digilent.adept.utilities_2.1.1-i686.tar.gz
$ cd digilent.adept.utilities_2.1.1-i686
$ sudo ./install.sh
$ cd ..
Below is an example given of how to program a Xilinx ML509 FPGA developers board. NOTE: make sure the Digilent HS cable is connected to the right JTAG connector on the board (programming the FPGA and not the memory). So, it should be connected to PC4 JTAG and not to J51 BDM. Further more, Device 4: XC5VLX110T is the FPGA to program, device 4 in the JTAG scan chain.
> djtgcfg enum
Found 1 device(s)
Device: JtagHs2
Product Name: Digilent JTAG-HS2
User Name: JtagHs2
Serial Number: 210249810909
> djtgcfg -d JtagHs2 init
Initializing scan chain...
Found Device ID: a2ad6093
Found Device ID: 0a001093
Found Device ID: 59608093
Found Device ID: f5059093
Found Device ID: f5059093
Found 5 device(s):
Device 0: XCF32P
Device 1: XCF32P
Device 2: XC95144XL
Device 3: XCCACE
Device 4: XC5VLX110T
> djtgcfg -d JtagHs2 prog -i 4 -f <fpga bit file to progam>.bit
Programming device. Do not touch your board. This may take a few minutes...
Programming succeeded.
There is a set of internal test for ARC and OpenOCD (consisting of just a
single test at the moment of this writing, though...). This testsuite aim is to
catch some issues with OpenOCD, JTAG or hardware. To run test suite: source
tcl/test/arc.cfg then run arc_test_run_all procedure, or run tests
individually.