ORCONF2013_Workshop_ORPSoC_On_DE0_Nano.mw

= Introduction =

This page contains the guide for the workshop being held during [[ORCONF#ORCONF_2013|ORCONF 2013]].

It will go through setting up the tools to build an ORPSoC system for the [http://www.terasic.com.tw/cgi-bin/page/archive.pl?No=593 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 [[OpenRISC_GNU_tool_chain#Newlib_toolchain_.28or1k-elf.29|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 [[OpenRISC_GNU_tool_chain#Prerequisites|appropriate prerequisites installed]] to compile a GNU tool chain.

=== Pre-compiled ===

Some pre-compiled tool chains are available (thanks to Stefan Kristiansson!) on the [[OpenRISC_GNU_tool_chain#Prebuilt_versions|GNU tool chain page]], too.

Extract these somewhere like <tt>/opt</tt>.

=== Add to PATH ===

Be sure to add the tool chain's <tt>/<installation_dir>/bin</tt> directory to your $PATH variable in your <tt>.bashrc</tt> 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 [http://download.altera.com/akdlm/software/acdsinst/13.0sp1/232/ib_tar/Quartus-web-13.0.1.232-linux.tar this link] will download the installer directly, without requiring you to go to the Altera website. 

Otherwise, visit the [http://www.altera.com/products/software/quartus-ii/web-edition/qts-we-index.html 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 <tt>setup.sh</tt> 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 <tt>ia32-libs</tt> package on Ubuntu, or similar.

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

Altera provide [http://www.altera.com/download/faq/dnl-v130-download-installation-faq.html this installation FAQ] and [http://dl.altera.com/static/quick_start_guide/quick_start_guide_13.0_en.pdf this quick start guide in PDF].

=== Add to PATH ===

Be sure to add the <tt>/<quartus_install_path>/quartus/bin</tt> directory '''to the end''' your $PATH variable in your <tt>.bashrc</tt> 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 <tt>make install</tt>.

=== Troubleshooting ===

==== Missing packages required for <tt>bootstrap</tt> ====

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 <tt>quartus/bin</tt> 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 (<tt>orpsoc</tT>) and one is the systems and IP cores (<tt>orpsoc-cores</tt>).

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

=== ORPSoC build system ===

For this workshop, we will be using the <tt>orpsoc-3.1</tt> release of the scripts. You can download them here: [ftp://ocuser:ocuser@openrisc.opencores.org/orpsoc/orpsoc-3.1.tar.gz 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 <tt>/path/to/orpsoc-3.1/bin</tt> 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 <tt>orpsoc-3.1</tt> 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|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 <tt>orpsoc-build</tt> along side the <tt>orpsoc-cores</tt> and <tt>orpsoc</tt> checkouts.

 mkdir orpsoc-build
 cd orpsoc-build

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

Create a file which tells <tt>orpsoc</tt> where these directories are. The following should be sufficient if your <tt>orpsoc-build</tt> directory is alongside the <tt>orpsoc-cores</tt> directory. So in your <tt>orpsoc-build</tt> directory create a file called '''<tt>orpsoc.conf</tt>''' 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, <tt>build/de0_nano/bld-quartus/de0_nano.sof</tt> 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: [https://www.dropbox.com/s/s7djpgtgbxmdhyi/de0_nano_orconf2013.sof 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 <tt>quartus_pgm</tt> 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 <tt>jtagd</tt> 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 <tt>/your/altera/install/dir/'''quartus/bin'''</tt> 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 <tt>quartus_pgm</tt> 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 0x020'''f'''30dd

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  ==

[[File:De0-nano-embecosm-uart.png|thumb|UART attached to DE0 Nano‎]]

[http://www.embecosm.com Embecosm] have graciously provided some [http://www.embecosm.com/resources/hardware/#EHW1 USB UART adapters] which can be attached to the DE0 nano.

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

A pinout for the DE0 nano can be found [http://semilleroadt.upbbga.edu.co/Archivos_Generales/DE0-Nano%20pinout.pdf 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 <tt>screen</tt> 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 <tt>/dev/ttyUSB0</tt>, 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 [[#Demo_bare_metal_software_for_ORPSoC|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 <tt>orconf2013/sw/</tt> and build with a simple <tt>make</tt>. 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 <tt>timerled</tt> program, download it here: [https://www.dropbox.com/s/8em2rzuzvn136pd/timerled timerled] (OR1K ELF file).

== Download and run OpenRISC software on SoC ==

Once the [[#Attach_the_debug_proxy|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 <tt>help</tt>.

[[#Compiling_demo_bare_metal_software|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 <tt>timerled</tt> 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:

[https://www.dropbox.com/s/bi5vx8kmqnjdldx/vmlinux-de0_nano vmlinux-de0_nano]

Load it with the following method via [[#Telnet|telnet]]:

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

Once booted, the image contains a [http://www.eembc.org/coremark/ <tt>coremark</tt>] executable in the root directory which can be run.