Getting started with release 4.x

Installation

To use release 4.x, you need the following things:

  • The latest release 4.0 archive, which you can get from the downloads page.
  • A Linux environment. We use various versions of OpenSuSE in Delft. Cygwin may work kind of, but there’s a lot of symlinks which you would need to handle somehow, and it has not been tested in any way for over a year.
  • Several GB of storage.
  • Xilinx ISE 14.7 for the Virtex-6 platforms (older versions are known to synthesize some things incorrectly) and/or Vivado 2015.4 for the Virtex-7 platforms (other versions may work as well).
  • Modelsim. The system is tested using version SE 10.2a; older versions are known to crash when simulating the core.
  • Python 3.x
  • GNU make, GCC, diff/patch, wget, netcat, and probably some of the other usual dev tools.

If you want to be able to (re)generate the documentation, you also need:

  • LaTeX, with these nonstandard packages:
    • import.sty
    • multirow.sty
    • tabto.sty
    • todonotes.sty
  • Perl

All the ρ-VEX specific things should™ work out of the box; they either come precompiled or are simple C programs without any external dependencies. Some things (for instance grlib and various source files) are not part of the release archive itself, but will be downloaded from the TU Delft FTP automatically when needed.

Documentation

In order to incentivize keeping documentation up-to-date during research and development, our philosophy is to document as much as possible within the code itself. This is primarily true for the VHDL files of the core. While this method is good for specific things, it is of course terrible for getting the big picture. For that reason, we also have a manual. You can find it in the doc folder of the release, or you can download it here.

Both of these documentation sources are exclusively intended to document the ρ-VEX core they belong to. That is, they do not document design choices, or in general how things came to be. For more information on that subject, refer to the MSc thesis corresponding to the ρ-VEX core implementation. It is also available in the doc folder, or it can be downloaded here.

Quickstart tutorial: running your first ρ-VEX program

This section is a brief tutorial on how to run a program on the ρ-VEX. If everything works as it should, this shouldn’t take more than half an hour. We will be using the program ucbqsort from the Powerstone benchmark suite, and run it using simrvex, Modelsim, and (if you have an ML605) ml605-standalone.

Architecture simulation with simrvex

Open a terminal and run the following commands. Only type the lines starting with a $ sign, without actually typing the $, and replace <root> with the directory that contains this file.

$ cd <root>/platform/simrvex
$ make trace-ucbqsort
...
ucbqsort: success

A framebuffer window will also be opened, which is not used by this program. Press enter in the terminal to exit the simulator.

The ucbqsort: success line is produced by the ρ-VEX: specifically by the rvex_succeed("ucbqsort: success\n"); line in <root>/test-progs/src/ucbqsort.c. Aside from showing the debug output, the trace target also generates a trace file: <root>/platform/simrvex/test-progs/simtrace-ucbqsort. This is a text file with the full instruction trace of the program.

HDL simulation with Modelsim

To do a basic simulation in Modelsim, we will use the cache-test platform. We will use the program ucbqsort-fast instead of ucbqsort here to speed up simulation; ucbqsort-fast does exactly the same, but has a smaller input size. If you don’t mind waiting a little longer, you can of course use ucbqsort as well. Xilinx ISE or Vivado is needed for its unisim and unimacro simulation files.

$ cd <root>/platform/cache-test
# make sure that Modelsim is in $PATH
# source Xilinx ISE 14.7 or Vivado environment script (settings64.sh)
$ make vsim-ucbqsort-fast

This will launch the Modelsim GUI. This platform does not add any signals to the waveform view by default, so let’s add a useful signal now:

VSIM 2> add wave sim:/testbench/rvex_inst/rv2sim

This is a simulation-only signal consisting of an array of strings that represent what the ρ-VEX is doing. Its output is similar to the trace output from simrvex, except embedded in the waveform view. The timing of the status signal corresponds to the last pipeline stage of the core.

Now that we have the signal, we can run the simulation. ucbqsort-fast takes about 100 microseconds simulation-time with the default compiler configuration.

VSIM 2> run 100 us
# ucbqsort-fast: success

As you can see, the debug output of the program is piped to the Modelsim transcript, just like how the debug output is piped to the console when using simrvex.

Running the program on the hardware

The release comes with ISE/Vivado projects and prebuilt bitstreams for the Xilinx ML605 and VC707 development boards. If you don’t have these boards, it should be fairly easy to get something basic working, but this is nevertheless out of the scope of this tutorial. For now, we will just use the ml605-standalone or vc707-standalone bitstream, depending on which board you have.

The first step is, of course, to program the bitstream. There are various ways to do this, and I assume that you’ve done this before if you’re reading this, so I won’t go into detail. The files are here:

<root>/versions/release-ml605-standalone.bit
<root>/versions/release-vc707-standalone.bit

The next step is to get rvsrv up and running. rvsrv is a tool that bridges the debug serial port peripheral to two TCP server sockets. This allows multiple applications to essentially access the serial port simultaneously, and it also allows you to use a boardserver easily. First, let’s go to the right platform
directory in a terminal:

$ cd <root>/platform/ml605-standalone
  OR
$ cd <root>/platform/vc707-standalone

Before starting the server, you need to know what device file the UART bridge of the development board is mapped to. Usually this will be /dev/ttyUSB0. This is a system-specific thing, so I will leave this to you. To start the server, run the following; of course replacing the serial port device file with whatever
it’s called on your system if necessary.

$ make server SERIAL_PORT=/dev/ttyUSB0

You should see these things, among other things:

# Successfully opened serial port /dev/ttyUSB0 with baud rate 115200.
# Trying to open TCP server socket at port 21078 for application access...
# Now listening on port 21078.
# Trying to open TCP server socket at port 21079 for debug access...
# Now listening on port 21079.
# Daemon process running now, moving log output to /var/tmp/rvsrv/rvsrv-p21079.log.

As the output implies, the tool daemonizes itself (i.e. runs in the background) so you can use the same terminal for other things. If you want to stop the server at some point, run make stop or something like killall rvsrv.

rvsrv by itself doesn’t do anything – you need rvd to send debug commands to the core. Again, rvd by itself does not have any knowledge of the target platform, so you need to feed it configuration files that we colloquially call memory maps, although they’re more like a pattern-matching script. Don’t worry though: the makefiles will handle all this for you. All you need to do is:

$ make debug
$ source debug

This will set up an alias to rvd that contains all the necessary flags to tell rvd what kind of platform it is talking to. To see it in action, run:

$ rvd ?

This will give you a state dump of context 0, which should mostly be a lot of zeros. So let’s run the program now. make can handle this for you:

$ make run-ucbqsort

You should first see the compilation steps, then the software upload to the core, then the makefile will wait for program termination (it checks every second; ucbqsort runs much faster than it looks from the makefile), and finally dump the performance counters:

# Performance counters for context 0:
#
#            Active cycles = 0x0000000003F9E6 =  260582 cycles
#           Stalled cycles = 0x00000000000000 =       0 cycles
#   Committed bundle count = 0x0000000002DBBA =  187322 bundles
# Committed syllable count = 0x0000000006D9F8 =  449016 syllables
#      Committed NOP count = 0x00000000018E87 =  102023 syllables

You’ll notice that the debug output is nowhere to be found. For that, you need a second terminal, where you run:

$ cd <root>/platform/<board>-standalone
$ make monitor
...
# Connecting you to the rvex now, ctrl+c to exit. If you get an error, the server is probably not running.

All this does is run netcat for the “application” port of rvsrv. This TCP socket emulates the serial port as the program sees it, with all the debug packets filtered out. It works in both directions: if you type something in the monitor and press enter the serial port peripheral will receive it. Most of the
programs don’t use this though.

If you now go back to the other terminal and run make run-ucbqsort again, you should see the debug output appear in the monitor.

# ucbqsort: success