OpenRISC Debugging

Introduction

There are many ways to debug systems based around the OpenRISC processor. This page will give an overview of the different models of the OpenRISC-based designs and how debugging on each of them is performed.

Overview

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.

It should be noted that this guide focuses 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. This is explained further in the sections on each "target".

The four currently supported targets for debugging are:

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

In-Depth Debugging Guides

These guides go into detail regarding debugging specific targets.

Debugging physical targets (FPGA/ASIC)

The Debug Interface Module

Currently all available OpenRISC designs (like the ORPSoC) use the SoC Debug Interface developed by the original OpenRISC team. This module provides the ability to perform accesses to OpenRISC CPUs the system's Wishbone Bus. The interface to the OpenRISC CPU is via the CPU's debug unit and provides support for actions such as stalling the processor, and accessing internal registers . The debug interface's Wishbone port allows it to access other cores on the system bus. This is useful for things such as loading memory with program code and accesses to peripherals.

The following is a simple block diagram representing the layout and interconnections of the JTAG TAP, Debug Unit, OpenRISC CPUs and Wishbone Bus.

Communication With Targets

The path that commands issued from GDB take to reach a target varies depending on the target. The following section gives some idea of this path for each of the different targets.

The following diagram displays the basic communication paths between GDB and the different debugging targets.

Physical Targets (FPGA, ASIC)

Like all physical targets, implemented on either FPGA or ASIC, some form of external communication with the hardware is required. Currently the solutions available for the OpenRISC platform are communication via the serial port and USB. A debug proxy is used to translate requests from GDB into transactions with the target over the external medium. The debug proxy communicates with GDB using a single protocol for all targets. It then uses different means of communication with the target, depending on the external medium, and could potentially use a separate protocol for each supported serial port or USB cable. The latest version of GDB for the OpenRISC uses the Remote Serial Protocol (RSP) to communicate with the debug proxy.

Debug Proxy For Physical Targets

Communication with FPGA and ASIC implementations can be achieved via the debug proxy which provides a GDB stub and translates commands from GDB into transactions with the debug interface on the target.

The following block diagram gives a simplistic representation of the components involved when debugging a physical target.

The OpenRISC Debug Proxy

This proxy application 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. Currently the ORSoC USB Debug Cable is the only supported USB cable, however support for additional cables will be added.

The proxy first establishes a connection with the target and stalls the processor. Next it waits for a connection with GDB over network sockets, and then begins translating received GDB commands into JTAG transactions with the debug interface via the USB cable. Transactions such as reading a single register or downloading megabytes of programs are done through this interface.

The Advanced JTAG Bridge

There is alternative debug proxy software available in the Advanced Debug System project, new to OpenCores. However, this requires that the project's Advanced SoC Debug Interface module is used in the OpenRISC design (this module replaces the original SoC Debug Interface). Currently this module is not used by the example OpenRISC designs, so this proxy will no work with things like the ORPSoC.

This proxy software supports several cables, serial port and communication with simulations via the Verilog Procedural Interface (VPI), which is explained in the event-driven simulation section.

This debug interface module differs slightly from the original design, so is not compatible with the existing OpenRISC Debug Proxy. It is the intention of the OpenRISC maintainers to migrate to the use of this module in the example designs such as ORPSoC. This information will be updated when this occurs.

Simulated Targets

Debugging with simulated models of OpenRISC-based designs is now explained.

Event-Driven Simulation

Event-driven simulators are applications which interpret RTL descriptions of designs, and produce models which execute according to an event scheduler. The simulation runs according to a list of events that occur as time progresses. A scheduling engine or algorithm manages the list of events that should take place. An "event" as used in this context refers to something like a clock edge, or a value propagating along a wire or through a combinatorial logic block to its output. Simulators such as Icarus Verilog and Cadence's NC-Verilog are examples of event-driven simulators.

The following block diagram gives a simplistic representation of the components involved when debugging an OpenRISC design running in an event-driven simulator.

It is possible to add additional C-language functions which can be linked into the event-driven simulations using the Verilog Procedural Interface (VPI). This interface provides the ability to add hooks for the C functions in the Verilog code, allowing custom code to be run inside the simulator. This enables useful functionality such as providing a way to communicate with a debugger which provides stimulus input to the simulation.

Please check back later for further information on running event-driven simulations of OpenRISC based systems.

Cycle-Accurate Simulation

Cycle-accurate simulation refers to the method of modeling a system where signal values are calculated at fixed time resolution increments. This fixed resolution is typically the period of the fastest clock in the design. This method of simulation has the benefit of running at a constant rate, and is typically faster than event-driven simulations for very active (ie. a lot of switching activity), complex designs. The trade-off is accuracy, for example propagation delays through interconnect or logic is not modeled.

The following block diagram gives a simplistic representation of the components involved when debugging a SystemC based cycle-accurate model of an OpenRISC design.

Some examples of building and running cycle-accurate models of the OpenRISC processor are available. An application note on Embecosm detailing the generation and profiling of a cycle-accurate SoC models (using the OpenRISC as an example) can be found here.

Included in the OpenRISC Reference Platform SoC version 2 (ORPSoCv2) are scripts that build and run a model based on the Embecosm application note. More information about this can be found on the ORPSoC page.

As these models are typically C or C++ based it is relatively simple to incorporate a GDB stub into them. This stub combined with another module to either "bit-bang" or perform discrete transactions with the model of the debug interface, implements the debugging capability.

Please check back later for further information on running GDB with cycle-accurate simulations of OpenRISC based systems. It is envisaged that a GDB stub will be incorporated into the latest ORPSoC in the near future.
However, in the meantime, Jeremy Bennett of Embecosm has documented implementing support for the GNU debugger here.

Architectural Level Simulation

This simulation is performed at the greatest level of abstraction. The model is written in C, making it very fast and configurable, but not so accurate in terms of representing anything below the instruction or transaction level.

Please see the OR1ksim project page for further information.