Advanced Debug System

Description

The Advanced Debug Interface is a suite of IP cores and software programs designed to allow a developer to download code to a target CPU in a System-on-Chip, then perform source-level debugging of that code. In particular, target systems using the OpenRISC 1200 processor and a WishBone bus are currently supported by the Advanced Debug Interface.

This system includes four components. The first component, the "adv_dbg_if" core, is a hardware core designed to interface directly to the OR1200 CPU and a WishBone bus, controlling the CPU and reading and writing data to both the CPU registers and memory addresses on the bus.

The second component is a JTAG TAP; this relatively small hardware core acts as a connection between the adv_dbg_if core and the external pins of the target chip (ASIC or FPGA). Four different versions of the JTAG TAP core are included, targeting four different types of system.

The third component is a software program called "adv_jtag_bridge," which is designed to run on the user's workstation. This component acts as a communication bridge between a source-level debugger program (GDB, not included in this package) and the JTAG TAP. Communication is performed via a JTAG cable, which adv_jtag_bridge drives.

The fourth important component of the system is the documentation. This suite includes a top-level document explaining the workings of the debug system and each of its components, including information to help the user choose the best components for his or her target system, and information on how to connect them. Documents describing each component individually are included (under doc/ in each component's subdirectory) as secondary material.

Features

• Supports multi-device JTAG chains. This configuration is often found on Xilinx reference hardware, and was not supported by previous debug hardware.


• Supports Altera sld_virtual_jtag interface. This allows the user to connect to the advanced debug unit via the same JTAG port which is used to program the FPGA, similar to the way the Altera Nios II processor debugger works.


• Supports Xilinx BSCAN_* virtual JTAG interface. This is the Xilinx equivalent of the Altera sld_virtual_jtag interface, it allows a user to connect to the advanced debug unit through the main FPGA JTAG connection.


• Support for Actel UJTAG TAP interface. This is the Actel equivalent of the Altera sld_virtual_jtag or the Xilinx BSCAN TAP, it allows a user to connect to the advanced debug unit through the main FPGA JTAG connection.


• Cables supported: Altera USB-Blaster, Xilinx Platform Cable USB (DLC9 and DLC10), various FT2232-based cables, various FT245-based cables, Xilinx Parallel Cable III (IV in compatibility mode), Altera ByteBlaster II, XESS parallel interface


• Includes full support for OR1200 hardware watchpoints/breakpoints and counters, including a GUI client program "AdvancedWatchpointControl"


• Includes a "JTAG serial port," a device which looks like a UART on the SoC WishBone bus, but which transfers data via JTAG to the jtag bridge program, where it can be viewed via telnet. This allows users to get logging from their programs without the need for a dedicated, external RS-232 link.


• Includes support for simulator connection. Programs can now be downloaded and executed on simulated hardware (in ModelSim, Icarus, etc.). Communication can be done via the filesystem, or via network sockets if VPI is supported by the simulator.


• Includes overview document explaining the complete debug system, component selection, and component interconnections. No more guessing which version of the debug unit works with which JTAG core or GDB interface program. All components used in the debug system are bundled together.


• JTAG chain auto-enumeration and BSDL parsing keeps command-line options to a minimum when running the adv_jtag_bridge program. Even complex systems can be debugged using only two command-line parameters.


• Uses less hardware than older "dbg_interface" core: 48% less logic, 28% fewer registers under Altera Quartus v7.0.


• Advanced JTAG Bridge program uses RSP to communicate with GDB, making it compatible with GDB 6.8.


• Advanced JTAG Bridge program can be compiled to support the legacy debug hardware unit (dbg_interface). This allows legacy hardware systems to be debugged using GDB 6.8 via RSP.


• Modular software design allows new JTAG cables to be easily added.


• Modular hardware design allows new busses and processors to be supported.

Status

The adv_dbg_if core, all of the JTAG cores, the JTAG serial port, and the adv_jtag_bridge software program have all been tested and shown to work in both ModelSim simulation and in FPGA hardware (Altera Cyclone II, Xilinx Spartan 3, Xilinx Virtex4). Drivers for the Altera USB-Blaster and the FTDI FT245 have been tested by the developer. The FT2232 and XPC3 drivers have also been reported to work by users, as has the ByteBlasterII driver. Bit-bang support for the Xilinx Platform Cable USB (DLC9) was developed and tested by the author, but this has been superseded by a driver with high-speed support, which has been minimally tested. The USB-Blaster is currently the fastest-performing cable tested by the developer, with a transfer rate of around 88k/sec. Support for the parallel 'XESS' cable was taken from the older 'jp2' program, and has not been tested in its new environment.

Hardware watchpoint support has been tested and is known to work using the OR1200v1 and the patch distributed with the Advanced Debug System. Watchpoint counters are also tested and known to work using this patch. The OR1200v1, v2, and v3 as found in SVN (as of this writing) are known NOT to work.

The 3.0.0 release of the Advanced Debug Interface was tested with minsoc v0.9. Release 2.5.0 was tested with the or1200 core as downloaded on 5/14/2008, the wb_conbus WishBone bus core as downloaded on 3/16/2008, and or32-uclinux-gdb version 6.8 (with one added patch, listed in "Known Bugs").

Tested ADI configurations:

• Xilinx Virtex-4, access via Xilinx Platform Cable USB (DLC9) and BSCAN_VIRTEX4 virtual JTAG TAP
• Xilinx Spartan 3A, access via Xilinx Parallel cable III and BSCAN_SPARTAN3A virtual JTAG TAP
• Xilinx Spartan 3A, access via Xilinx Parallel cable IV (in XPCIII compatibility mode) and BSCAN_SPARTAN3A virtual JTAG TAP
• Xilinx Spartan 3A, access via Xilinx Platform Cable USB (DLC9) and BSCAN_SPARTAN3A virtual JTAG TAP
• Altera Cyclone II, access via Altera USB-Blaster cable and stand-alone JTAG TAP
• Altera Cyclone II, access via USB-Blaster clone and altera_virtual_jtag TAP (usbblaster and ft245 drivers)
• Altera Cyclone IV, access via USB-Blaster clone and altera_virtual_jtag TAP (usbblaster and ft245 drivers)
• Altera Stratix II, access via USB-Blaster (with FT245 driver) and altera_virtual_jtag TAP
• Actel A3P1000, access via USB-Blaster clone and actel_ujtag TAP (usbblaster and ft245 drivers)
• Simulation in ModelSim, File IO communication
• Simulation in ModelSim, network sockets (via VPI) connection
• Simulation in Icarus, VPI connection ("minsoc" project)

Untested features:

• Some Xilinx BSCAN devices
• XESS parallel interface support
• The boundary scan cell HDL included with the "jtag" TAP has not been tested with the modified TAP

Dependencies

The adv_jtag_bridge software relies on libUSB to drive the USB-Blaster and XPC-USB/DLC9 cables. This Free/Open Source library can be downloaded from http://libusb.wiki.sourceforge.net. Note that adv_jtag_bridge uses the older v0.1 libUSB interface; as of December 2008, libUSB changed its interface to version 1.0. Be sure to install the "compatibility layer" of libUSB on your system if you use Linux; the libUSB-Win32 version still used the v0.1 interface as of Dec. 2008.

Support for FT2232-based cables depends on libftdi. This LGPL library may be found at http://www.intra2net.com/en/developer/libftdi. Adv_jtag_bridge version 1.2.0 was tested with libftdi version 0.16, this is the last time the author had access to a DLC9 cable. Release 3.0.0 is known to compile against libftdi version 0.19. Note that in some Linux distributions (Ubuntu 10.04 for example) you must install both the libftdi and the libftdi-dev packages from your OS provider's software repository.

To Do

• Test other BSCAN_x interfaces
• Port adv_jtag_bridge to use libUSB v1.0
• Port the adv_jtag_bridge cable drivers and BSDL parsing to use the UrJTAG project, once it is available as a library
• More testing and verification is always needed, improved testbenches, etc!

Known Bugs

• GDB 6.8 has a bug which prevents it from working when no stack frame is present (such as at start-up on a bare-metal debugger, as we are doing here). A simple patch applied to GDB 6.8 will work around the problem (a general solution is not yet available). This patch can be found in the Patches/GDB6.8/ directory.


• The OR1200v1 hardware breakpoint implementation is broken. A patch which fixes the support is distributed with the Advanced Debug System in the Patches/OR1200v1/ directory. Support for other versions of the OR1200 is not yet available.
• There is a bug in the OR1200v3 which affects the debug unit. This version will not pass the adv_jtag_bridge self-test, but will instead lock the processor (and debugger). The bug also manifests itself during single-stepping.
• GDB versions 7.0 and 7.2 have bugs which prevent them from working correctly with the Advanced Debug System (and probably other debug units and well).

Changelog

• 5/18/2009 Version 1.0 released (OpenCores SVN tag ADS_RELEASE_1_0_0)
• 6/16/2009 Version 1.1 released (tag ADS_RELEASE_1_1_0). Added support for the legacy debug unit (dbg_interface) to adv_jtag_bridge. Changed TDI/TDO signal names in TAP cores for clarity. Updated docs.
• 7/23/2009 Version 1.2 released (tag ADS_RELEASE_1_2_0). Added support for FT2232-based JTAG cables (thanks to Jose Villar). Fixed critical bugs in XPC3 and XESS parallel cable drivers (thanks to Raul Fajardo).
• 1/17/2010 Version 2.0. Changes to the communication protocol, allowing an order-of-magnitude speed improvement for USB-Blaster cables. Added alternate USB-Blaster cable driver as compile-time option (thanks to Xianfeng Zeng). Fixed BSDL parsing directory bug. Other minor improvements. Updated docs to reflect new hi-speed mode.
• 3/31/2010 Version 2.5. Added actel_ujtag core. Added JTAG Serial Port feature. More speed improvements for USB cables.
• 12/29/2011 Version 3.0. Autotools support, thanks to R. Diez. High-speed DLC9 support, thanks to Raul Fajardo. Non-priviledged parallel port access, also thanks to Raul Fajardo. Altera ByteBlasterII support. Bugfixes and minor speed improvements.