OpenCores

ORCONF2013 Workshop ORPSoC On DE0 Nano

From OR1K

Contents

Introduction

This page contains the guide for the workshop being held during ORCONF 2013.

It will go through setting up the tools to build an ORPSoC system for the Terasic DE0 Nano board, and get code running on that system.

Requirements

This workshop will need to be run on a machine which has

  • a relatively recent Linux distribution (up to 2-3 years old?)
  • around 10GB of disk space free for the development tools
  • an internet connection

On that system the following will be required

  • repository control software git and subversion
  • an OpenRISC software tool chain for compiling code
    • if building from source this will require a number of software development packages installed on your system
  • the Altera Quartus EDA software for compiling RTL for the FPGA
  • the OpenOCD debug proxy
  • Python 2.7 (or above)

Tool installation

Repository control software

Both git and subversion should be easily installed via your distribution's package management system. These will be needed to download the source for the tools which are compiled.

OpenRISC GNU tool chain

The OpenRISC software tool chain consists of all the tools require to compile and manipulate software for the platform. Specifically, the tool chain which is considered the development version will be used to compile code to run on the "bare metal" system. That is, with no underlying operating system.

There are two options for obtaining the OpenRISC tool chain. One is to download a set of pre-compiled binaries for your platform, or compiling from source.

Building from source

See the instructions on building the "newlib" tool chain from source on the GNU tool chain page on this wiki.

Note: be sure to ensure your system has the appropriate prerequisites installed to compile a GNU tool chain.

Pre-compiled

Some pre-compiled tool chains are available (thanks to Stefan Kristiansson!) on the GNU tool chain page, too.

Extract these somewhere like /opt.

Add to PATH

Be sure to add the tool chain's /<installation_dir>/bin directory to your $PATH variable in your .bashrc file or similar after installation.

Altera Quartus

This is the software which compiles RTL and ultimately generates an FPGA programming file.

Unfortunately this software is closed source, extremely large, and requires registration to download. However, it is required.

It's possible that this link will download the installer directly, without requiring you to go to the Altera website.

Otherwise, visit the Quartus II Web Edition page and click on the "Download Software Web Edition - Free" button. Register and then download the installer.

It is 4.5GB in size and will obviously take a while to download.

Once it is downloaded, extract it and run the setup.sh file in there.

They mention that "64-bit operating systems must install 32-bit compatibility libraries before installing the Quartus II software". Presumably this is the ia32-libs package on Ubuntu, or similar.

Note: Make sure you select to include the Cyclone IV E device families during installation.

Altera provide this installation FAQ and this quick start guide in PDF.

Add to PATH

Be sure to add the /<quartus_install_path>/quartus/bin directory to the end your $PATH variable in your .bashrc file or similar after installation. Failing to add this to the end of your $PATH variable will cause issues when running #OpenOCD.

OpenOCD

This is a debug proxy program and will initially talk to the system on the FPGA before we attach a software debugger.

Download the source with

git clone git://repo.or.cz/openocd.git

Once cloned, the source in the repository must be bootstrapped before it is configured the first time only. Do this with

./bootstrap

Now configure and build

./configure --enable-ftdi --enable-usb_blaster_libftdi --enable-maintainer-mode
make

You may also choose to install it with make install.

Troubleshooting

Missing packages required for bootstrap

Your system will require

  • autoconf
  • pkg-config
  • automake
  • libtool

Missing packages during configure

Install

  • libusb-1.0-0-dev
  • libtclcl1-dev
  • libftdi-dev

TCL error message during configure

If you have already installed the Altera Quartus suite and its quartus/bin directory is in your $PATH then remove it while you configure and build OpenOCD.

ORPSoC

ORPSoC is the system-on-chip build infrastructure which will be used for this workshop.

It is made up of 2 parts - one is the build scripts (orpsoc) and one is the systems and IP cores (orpsoc-cores).

See the ORPSoC page here on the OpenCores wiki for further details.

ORPSoC build system

For this workshop, we will be using the orpsoc-3.1 release of the scripts. You can download them here: orpsoc-3.1.tar.gz or with

wget ftp://ocuser:ocuser@openrisc.opencores.org/orpsoc/orpsoc-3.1.tar.gz

Once downloaded extract this archive somewhere sensible with

tar xzf orpsoc-3.1.tar.gz

You may then simply add the /path/to/orpsoc-3.1/bin directory onto your PATH variable, or you can install it with

./configure
make
make install

ORPSoC cores

This must be cloned from the github repository. It is easiest if this resides alongside the orpsoc-3.1 directory.

git clone https://github.com/openrisc/orpsoc-cores.git

The code we will actually build is slightly different from the upstream version. You'll need to add a remote repository containing this modified version.

cd orpsoc-cores
git remote add orconf2013 https://github.com/juliusbaxter/orpsoc-cores.git 
git remote update
git checkout orconf2013/master

Demo bare metal software for ORPSoC

Software is not handled by ORPSoC, yet. Some basic bare metal software, which will build against our newlib-based tool chain.

Clone this repository alongside the others:

git clone https://github.com/juliusbaxter/orconf2013.git

Building ORPSoC for the DE0 nano

Create build area

ORPSoC requires a separate directory be created as its work area. Create this directory, something like orpsoc-build along side the orpsoc-cores and orpsoc checkouts.

mkdir orpsoc-build
cd orpsoc-build

The build directory needs a config file, which simply tells the scripts where the cores and systems are.

Create a file which tells orpsoc where these directories are. The following should be sufficient if your orpsoc-build directory is alongside the orpsoc-cores directory. So in your orpsoc-build directory create a file called orpsoc.conf with the following contents:

[main] 
cores_root   = ../orpsoc-cores/cores
systems_root = ../orpsoc-cores/systems

We are now ready to build

Build FPGA image

The image is simply built by running

orpsoc build de0_nano

This will handle the downloading (yes, you will need internet connectivity) of all the source, generation of parts of the system and scripts and launching of FPGA tools.

If your environment has not been set up correctly, this step will likely error out.

Once it is complete, you will end up with an image, build/de0_nano/bld-quartus/de0_nano.sof which you can program on the DE0 nano. You are then ready to program your FPGA board.

If you are having problems building the image, or suspect yours isn't correct, you can download a known-good one here: de0_nano_orconf2013.sof

Running ORPSoC on DE0 Nano

Programming the FPGA

ORPSoC doesn't handle this automatically (yet...) but it's simple enough to do on the command line.

Plug your board into your PC via the provided USB cable and a blue LED should light up, indicating it's powered.

We will use the quartus_pgm tool to do this with:

quartus_pgm --mode=jtag -o p\;build/de0_nano/bld-quartus/de0_nano.sof

If this worked you'll see a message like:

Info (209017): Device 1 contains JTAG ID code 0x020F30DD
Info (209007): Configuration succeeded -- 1 device(s) configured
Info (209011): Successfully performed operation(s)

You are now ready to connect to the SoC with a debug proxy

If not, see the troubleshooting section.

Troubleshooting

Error (213019): Can't scan JTAG chain. Error code 89.

If you see this (red) error message, then you have not started the Altera JTAG daemon.

First, kill any other jtagd processes which may be running

sudo killall jtagd

Now check the Altera one is installed and available

which jtagd

One should be available in the /your/altera/install/dir/quartus/bin directory

If so, now run it with

sudo `which jtagd`

And try to program again.

Another solution... save below as "/etc/udev/rules.d/51-usbblaster.rules, and reboot!!

# USB-Blaster
SUBSYSTEMS=="usb", ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6001", MODE="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6002", MODE="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6003", MODE="0666"
# USB-Blaster II
SUBSYSTEMS=="usb", ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6010", MODE="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6810", MODE="0666"

Error (213019): Can't scan JTAG chain. Error code 36.

This is caused by the debug proxy, OpenOCD, still being attached to the device while you're attempting to program the board.

Exit OpenOCD before re-running the quartus_pgm command.

Attach the debug proxy

It is time to run OpenOCD, the debug proxy program which will talk to the ORPSoC system now implemented on the FPGA.

It will use the same cable which programs the board, so the DE0 nano must be connected and programmed with the image we generated.

Go to the OpenOCD directory in which everything was compiled and run

sudo ./src/openocd -s ./tcl -f ./tcl/interface/altera-usb-blaster.cfg -f ./tcl/board/or1k_generic.cfg

This should attach to the board and not report any errors, looking like:

Open On-Chip Debugger 0.8.0-dev-00195-g4e79b48 (2013-09-30-21:08)
Licensed under GNU GPL v2
For bug reports, read http://openocd.sourceforge.net/doc/doxygen/bugs.html
Warn : Adapter driver 'usb_blaster' did not declare which transports it allows; assuming legacy JTAG-only
Info : only one transport option; autoselect 'jtag'
Info : vjtag tap selected
Info : adv debug unit selected
Info : Option 1 is passed to adv debug unit adapter speed: 3000 kHz
Info : No lowlevel driver configured, will try them all
Info : usb blaster interface using libftdi
Info : This adapter doesn't support configurable speed
Info : JTAG tap: or1200.cpu tap/device found: 0x020f30dd (mfg: 0x06e, part: 0x20f3, ver: 0x0)
Info : adv debug unit is configured with option ADBG_USE_HISPEED
Halting processor
Chip is or1200.cpu, Endian: big, type: or1k
Target ready...

If so, you are ready to communicate with the SoC and download some software

Otherwise, see the troubleshooting section

Troubleshooting

Error: JTAG tap: or1200.cpu expected 1 of 1: 0x020b30dd

The default OpenRISC target config file in OpenOCD expects to talk to a different JTAG TAP than is on the DE0 nano. We must change one line in a file.

If you haven't already, exit OpenOCD with ctrl+c.

Open the following file from the OpenOCD tree in a text editor

tcl/board/or1k_generic.cfg

Change the following line (second line of the file)

set FPGATAPID 0x020b30dd

to

set FPGATAPID 0x020f30dd

Basically, set the b to a f in the FPGATAPID value.

Save and close the file, and re-run OpenOCD with the same command as before.

Physically attach the UART

UART attached to DE0 Nano‎

Embecosm have graciously provided some USB UART adapters which can be attached to the DE0 nano.

These should be attached so that the GND pin is on pin 12 of header JP2.

A pinout for the DE0 nano can be found here.


Open a UART terminal

This will open a terminal attached to the UART device.

There are several terminal programs we could use to attach to the UART but we will use screen here. The essential information, however, is that it's the default (?) UART protocol (8-bits data, 1 stop bit, no parity) at 115200 baud.

It is assumed there is only 1 USB-UART attached, and is mounted as /dev/ttyUSB0, so alter the following instructions if it appears somewhere else on your machine.

Attach with

screen /dev/ttyUSB0 115200

If this didn't work, check the troubleshooting section

Troubleshooting

Permissions problems

Unless you have a rule to allow these USB-UART devices to be read/write by the user you will need to change the permissions on it. Do this with

sudo chmod a+rwx /dev/ttyUSB0

Compiling demo bare metal software

Make sure you have downloaded the demo bare metal software.

This software is all very simple bare metal examples of using the OR1K timers, flashing the LEDs and performing UART I/O.

Go into any of the directories under orconf2013/sw/ and build with a simple make. For example:

cd orconf2013/sw/timer
make

The result executables are named the same as the directory, and can be downloaded to the board.

If you are having issues compiling software, try this precompiled version of the timerled program, download it here: timerled (OR1K ELF file).

Download and run OpenRISC software on SoC

Once the debug proxy is attached it can be used to download and execute code on the board in a couple of ways.

Telnet

OpenOCD runs a telnet server which can be used to issue commands to halt, download and image and set the processor running.

It runs a telnet server on port 4444. Connect to it in a terminal with

telnet localhost 4444

Once connected, the list of commands the proxy supports may be listed with help.

Compile some software to download on the board and get the full path to this file.

To download and run a program, the following line may be used (replace the path here with the appropriate executable path).

halt; load_image /<path to your>/orconf2013/sw/timer/timer; reg npc 0x100; resume

It may be required to reset the board once the software has been downloaded this can be done with

reset

This will usually halt the processor, and it can be set running again with

resume

The timerled software will output to the UART, and be interactive.

Run Linux

Of course, we wouldn't hold a workshop without booting our Linux system :)

Download a pre-compiled Linux kernel with BusyBox here:

vmlinux-de0_nano

Load it with the following method via telnet:

halt; load_image /work/orpsoc-build/vmlinux-de0_nano; reset

Once booted, the image contains a coremark executable in the root directory which can be run.

© copyright 1999-2017 OpenCores.org, equivalent to ORSoC AB, all rights reserved. OpenCores®, registered trademark.