OpenRisc-53-debugging the OpenRISC 1200

引言

or1200的调试，是玩OpenRISC绕不过去的话题，无论是硬件上的调试，软件程序的烧写，调试，还是仿真时的调试，都需要相关的调试系统的支持。鉴于debug系统的重要性，Opencores官方也开发了一个调试系统-advance debug system，这个系统包含硬件和软件的所有组件，请参考：http://opencores.org/project,adv_debug_sys
http://opencores.org/or1k/OpenOCD
通过下载和阅读advance debug system中的文档（doc/or1k_debug_sys_manual.pdf），我们可以根据自己的具体环境搭建合适的调试系统，但是，为了加快上手速度，之前也写过几篇关于debug的blog，但是还不够，所以本小节就再进一步解决这个问题。其实，real-time embedded也做过相关工作：http://www.rte.se/blog/blogg-modesty-corex/index下面就是其中一篇博文，其中详细介绍了or1200的调试系统的搭建过程。http://www.rte.se/blog/blogg-modesty-corex/debugging-openrisc-1200/2.13
内容如下：（都是比较简单易懂的语句，所以就没有翻译）虽然文中使用的硬件和软件环境也许和我们各自的有所区别，但还是有一定的参考价值的。如果你没有买ORSoC USB debugger的话，请参考：http://opencores.org/forum,OpenRISC,0,4444)

Introduction

There are different ways of performing debugging depending on the "target" (the actual representation of the OpenRISC processor and platform.) Two main categories of target exist; physical targets such as FPGA or ASIC OpenRISC implementations, and simulated targets such as a low-level event-driven simulations of RTL models (using a simulator such as Icarus Verilog) or models with greater abstraction such as the OR1ksim architectural simulator.

We will focus on debugging with the GNU debugger, GDB, as the primary user interface. The "targets" that GDB connects to will somehow support GDB with a "stub" or a component that can understand and translate GDB commands into the appropriate commands for the target. Here is some more information about using gdb for software debugging.

The four currently supported targets for debugging are:

Physical target (FPGA or ASIC)
Event-driven simulation
Cycle-accurate model simulation
Architectural simulator

Debugging a physical target

Physical implementations of OpenRISC systems can be debugged using a set of tools made available at OpenCores.org. Whether simply poking registers in IP cores or debugging complex software executing on the processor, these tools provide a useful debugging capability. The following block diagram gives a simplistic representation of the of the components involved in debugging a physical target.

JTAG TAP

The implementation of the Test Access Port (TAP) is fully IEEE 1149.1 compliant. It includes a TAP controller, a 4-bit instruction register and three test data registers: idcode register, bypass register and boundary scan register.

SoC debug interface

The Debug Interface is used for development purposes (debugging). It is an interface between the CPU(s), peripheral cores and any commercial debugger/emulator. The external debugger or BS tester connects to the core via JTAG port that is fully IEEE 1149.1 compatible. For that reason JTAG TAP needs to be used together with this core.

The GNU debugger

The GNU debugger, GDB, is a popular tool that is capable of debugging many architectures from many platforms. The OpenRISC port of GDB (or32-elf-gdb), is used as the primary debugging tool for all OpenRISC targets. It functions as, among other things, the actual user interface when debugging.

Using the ORSoC USB to JTAG debugger

ORSoC has developed an USB to JTAG debugger, aimed at debugging OpenRISC based systems. One or more OpenRISC processors can be controlled over a JTAG interface. Additionally the debugger could be used to handle a serial connection for a console. Signal level on the JTAG is user configurable by use of an external voltage. The debugger is USB 1.1 compatible for easy connection to a host. A local proxy server handles the USB connection and offers a TCP connection to a software debugger. The GNU debugger with optional graphical user interface, such as DDD, is supported. It connects to the board under test with a ribbon cable. The cable has a 2×5 pin header with 0,1″ spacing using the following pinout:

Pin	Connects To	Description
1	JTAG TCK	JTAG Test Clock
2	GND	Ground
3	JTAG TDO	JTAG Test Data Out
4	VCCIO JTAG	External Reference Voltage JTAG Port
5	JTAG TMS	JTAG Test Mode Select
6	VCCIO UART	External Reference Voltage UART
7	UART RX	UART Receive
8	UART TX	UART Transmitt
9	JTAG TDI	JTAG Test Data Input
10	GND	Ground

Contact pin numbering

Connecting to the Atlys board

We will use the available Pmod connector on the Atlys board to connect the USB-JTAG debugger cable.The Pmod connector is a 2x6 right-angle, 100-mil female connector that mates with standard 2x6 pin headers available from a variety of catalog distributors. The 12-pin Pmod connector provides two VCC signals (pins 6 and 12), two Ground signals (pins 5 and 11), and eight logic signals. VCC and Ground pins can deliver up to 1A of current. Jumper JP12 selects the Pmod Vcc voltage (3.3V or 2.5V) in addition to selecting the VHDC voltage. Pmod data signals are not matched pairs, and they are routed using best-available tracks without impedance control or delay matching.


From the schematics.

Connecting the JTAG port to the Pmod connector

To physically connect the JTAG module input and output pins to the Pmod connector we will modify the atlys.ucf file. From the file orsoc_top.v we can find out the port names of the JTAG module.



Here is the modified atlys.ucf file. We put the TCK clock on a clock input pin (JA-CLK-P).

Reduild the design

We will rerun the complete design flow after the changes we have made. See: Using ORPSoC. Just remember to run: <make clean> before the new make commands.

Pmod to FPGA to JTAG debugger

The Pmod connector is connected to the follow pins on the Spartan-6 FPGA and the JTAG debugger.

Pmod Connector	FPGA pin	JTAG Debugger
JA1	T3	3 TDO
JA2	R3	5 TMS
JA3	P6	9 TDI
JA4	N5
JA5 GND		2 GND
JA6 VCC		4 VCC
JA7	V9
JA8	T9	1 TCK
JA9	V4
JA10	T4
JA11 GND
JA12 VCC

Building a connection board

We need to build a small board to connect the USB-JTAG ribbon cable to the Pmod contact. It looks like this:

The debug proxy

The debug proxy controls the link between GDB and the physical target. It implements a GDB stub, and provides support for most GDB commands. Physical connection to the board is made with the use of a USB debug cable. The ORSoC USB Debug Cable is one supported USB cable but there are other solutions. The proxy first establishes a connection with the target and stalls the processor. Next it waits for a connection with GDB via network sockets, and then begins translating received GDB commands into JTAG transactions with the debug interface via the USB cable. Transactions such as reading and writing registers, or downloading executables to memory are done through this interface. The OpenRISC Debug Proxy (or_debug_proxy) can be downloaded from the OpenRISC project's subversion repository using the following command:

svn co http://opencores.org/ocsvn/openrisc/openrisc/trunk/or_debug_proxy
The README included with the source provides detailed installation and usage instructions but a brief step-by-step guide for installation and compilation under Linux.




We can use a simple make to compile the program (or_debug_proxy). Before we compile the program we have to make sure the lftd2xx library is available. For more information read the README file.

Downloading FTD2xx library

After failing to connect to the board I found out that the new version FTD2XX (1.0.5) did not work together with the or_debug_proxy. We have to download the old library (0.4.16) from the FTDI web page.

Compiling OpenRISC Debug Proxy

There are two ways to compile the proxy - one linked to the dynamic library, and one linked to the static library. There is no difference in performance or functionality, it is a little easier to compile against the static library as there are more steps involved to install the dynamic library. To compile the proxy application against the static library, simply go into the source directory and run a "make static", note that this requires the static driver library is located in the lib/ directory in the proxy source code.




Here are all the files involved.

Installation

The OR debug proxy application runs on multiple platforms only requiring slightly different driver configurations on each. Currently, Cygwin Windows, several Linux distros and Mac OS X (10.4 and above) are supported. Use with the ORSoC debug cable requires installation of some form of the FTDI Chip FTD2XX driver. It is required that the Linux distribution have a version 2.4 kernel, or above. This is due to the USB driver libraries by FTDI Chip used to interface with the USB debug device..

These USB to serial devices typically trigger the loading of another FTDI driver when they're attached to the system. This is the ftdi_sio driver and now comes standard in newer kernels. This is of use to us, as one of the two serial devices will remain is a standard UART under /dev/ttyUSBx. However, to enable a high-speed JTAG interface with our hardware we require newer, specialised drivers from FTDI called the D2XX drivers. As seen above they are already installed in our system.

ORSoC USB debug cable device permissions

To avoid having to run the proxy with sudo or as root user, permissions on the USB should be set permitting regular users access to the device. An example of setting the permissions on recent udev systems (almost all 2.6 kernel distributions use udev) is presented here. The ORSoC USB debug cable is identified from its USB vendor and product IDs (0x0403 and 0x6010, respectively) by the system when it is connected. Use the command lsusb to locate the connected USB-JTAG Debugger (Bus 005 Device 015).



We can insert a rule which allows user read and write permissions on this device when it is connected.This rule should be inserted in a file in the udev rules directory, /etc/udev/rules.d. It is easiest to create a new file, called 90-permissions.rules in the udev rules directory, which should contain the following:





Test this rule by unplugging and reconnecting the USB debug cable, and looking at the permissions of the two /dev/ttyUSB devices. The permissions should look like the following when listed with ls -l:



If the permissions do not have rw- in the final three characters, then the user is not able to access it. It is possible the rules file was not setup properly. Check the README for solutions to setting permissions on the cable for other platforms.

The final setup

Here is what the debug solution looks like.

Connecting to the target

Once the tools are setup, a connection to the system must be established. This connection occurs in two steps. The first step is to establish the connection between the proxy and the JTAG tap controller via the USB debug cable. Next, GDB connects to the proxy, and the debugging session can begin.

Connecting the proxy to the target

Connecting the proxy to the target is the first step to setting up the debugging chain. The proxy attempts to create the connection automatically when it is run. When the proxy is launched it automatically performs some actions, these are: reading of the JTAG TAP controller ID and check it's sensible, set the TAP to debug mode, stall the CPU, read back a few registers (PC, NPC, GPR1), and finally open a socket for the connection from GDB. The port for GDB to connect to is specified on the command line when launching the proxy with the -r option. In the following example port 55555 is used.

./or_debug_proxy -r 55555

Because we haven't connect the JTAG debugger to the Atlys board we get the following error message:



We will figure out how to connect to the board and make the small connection board. Is is fixed now. We have a debug connection with the Atlys board.

Connecting GDB to target

Once the proxy is running, the next step is connecting to the proxy from GNU Debugger GDB (or32-elf-gdb). Since GDB 6.8, communication between the proxy and GDB uses the remote serial protocol (RSP). The following commands show an example of starting GDB and connecting to the proxy. If the proxy is running on the same machine as GDB is being run on, then the following commands will work, otherwise substitute the IP of the machine running the proxy for localhost:

or32-elf-gdb
target remote localhost:55555

Compiling program for debugging

Use this command to compile the LEDtest.c program for debugging (-g option to generate debug information) :

or32-elf-gcc -g mboard=atlys LEDtest.c -o LEDtest.elf

Loading and running a program

Here are the commands to load and run a C-program (LEDtest.elf) from GDB.

file LEDtest.elf (Load symbol table)
load (Load program to target)
c (run program)




GDB connecting through RSP with target remote is connecting to a target which is already executing, but has stalled. Thus it is inappropriate to use the run command (which specifies a new program to run). Instead the continue and step commands are used. The load command will reset the program counter to the entry point of the program. So a subsequent continue will cause the newly loaded program to execute from its entry point.

Debugging OpenRISC with gdb

The document: "Debugging with gdb: the gnu Source-Level Debugger for gdb" can be read here.

The people at Embecosm Limited has written a manual called "Debugging the OpenRISC 1000 with GDB". This manual describes how to use GDB to debug C programs cross compiled for and running on processors using the OpenRISC 1000 architecture. In addition the info command is extended to allow inspection of OpenRISC 1000 Special Purpose registers, and a new command “spr” is added to set the value of a Special Purpose Register. See section OpenRISC 1000 Specific Commands.

All the normal GDB commands should work, although hardware watchpoints are not tested at present. The info registers command will show the 32 general purpose registers, while the info registers all command will add the program counter, supervision register and exception program counter registe For those who like their debugging graphical, the gdbtui command is available (or32-elf-gdbtui). GDB for OpenRISC 1000 can also be run under DDD as follows: ddd --debugger or32-elf-gdb

Debugging examples

Loading a program (LEDtest.exe) and single stepping the code:



Displaying all the CPU's special purpose registers: info spr sys

Using Data Display Debugger DDD

DDD is a graphical front-end for command-line debuggers such as GDB, DBX, WDB, Ladebug, JDB, XDB, the Perl debugger, the bash debugger, or the Python debugger. DDD displays data structures as graphs and plots.Here is the User's Manual.

OpenOCD

OpenOCD is a program that we can use to talk to our debug interface on our hardware via JTAG, over a variety of cables, in a realtively flexible manner. We can script up things in TCL to control the system, or we can run a GDB RSP server and do things from GDB. OpenOCD will replace or_debug_proxy as the future debug interface.

The OpenOCD code with basic OpenRISC 1000 support is found on the openrisc.net git tree: git clone git://openrisc.net/julius/openocd

Using the advanced debug interface

There is also another solution available for debugging our board. It is called the advanced debug interface. To use this interface we have to modify our SOC design.

Connecting to the Atlys board

I don't have a solution today. If someone can provide me with one I would be more than happy. Can we use this box together with the Advanced Debug System?





We will find out next week. While we are waiting we can study the document "Debugging System for OpenRISC 1000-based Systems" written by Nathan Yawn.