Setting up a mor1kx development and verification environment
This is a guide to setting up an environment to work with the mor1kx OpenRISC processor.
There is a newer guide to getting FuseSoC and mor1kx environments up and running, courtesy of the legendary Stafford Horne, here: http://stffrdhrn.github.io/hardware/embedded/openrisc/2019/06/11/or1k_marocchino.html
I would recommend following that than anything that follows.
This page will detail a set up which allows the development and verification of the mor1kx processor.
The set up will use the mor1kx-generic reference design provided by FuseSoC along with the orpsoc-cores respository of systems, to compile and simulate an mor1kx-based system. A suite of tests (or1k-tests) can then be run on this system to help validate the core's functionality. This will require further tools such as an OpenRISC cross compiler tool chain and other tools such as simulators and waveform viewers.
To be clear, this is not the only way to simulate and verify the mor1kx core, but it's the development set up that some of the developers use. It's worth noting that it's also allbased on open source projects and tools.
This guide will not outline how to implement and use an mor1kx-based system on FPGA. For that, follow this guide over on the Embecosm wiki which was used at chiphack 2014.
Follow the guide found on the Embecosm chip-hack github wiki page for how to prepare the required tools on your system.
Specifically:
- General system tools
- OpenRISC compiler tool chain from source (or precompiled)
- FuseSoC source
- orpsoc-cores source
- Icarus Verilog simulator and GTKWave waveform viewer
First, an explanation of what we're about to use.
The command-line interface and automation is the job of FuseSoC. FuseSoC provides a neat way of implementing systems (processor(s) and peripherals) based on open source IP cores. It is, by itself, just a set of scripts, however it can be combined with a compatible set of system descriptions and RTL top-levels to automate the aggregation of the IP core components (from wherever they may lie all over the Internet) and compilation and simulation of the whole system.
Once FuseSoC runs a simulation, which will run in batch-mode (where we'll see only messages printed to the console), we have the ability to inspect the various log files it creates. Some of these files are plain text, and others are intended to be viewed graphically, such as a value change dump (VCD) file in a waveform viewer tool like GTKWave.
If you've set up the source code and tools as per the instructions then you'll be able to go into your or1k directory and prepare to run our first simulation.
We'll need to compile a program to run on the processor, first.
Copy the following into a file called hello.c:
#include <stdio.h>
int main(void)
{
printf("Hello world, from an OpenRISC system!\n");
return 0;
}Now compile it using the OpenRISC software tool chain which you should have already installed
or1k-elf-gcc hello.c -o hello.elf
With the software compiled and ready, we can now run the simulation of the mor1kx-generic system:
fusesoc sim mor1kx-generic --elf-load hello.elf
The output will look like so:
$ fusesoc sim mor1kx-generic --elf-load hello.elf orpsoc_tb.dut.mor1kx0.bus_gen.ibus_bridge: Wishbone bus IF is B3_REGISTERED_FEEDBACK orpsoc_tb.dut.mor1kx0.bus_gen.dbus_bridge: Wishbone bus IF is B3_REGISTERED_FEEDBACK Program header 0: addr 0x00000000, size 0x00006BEC Program header 1: addr 0x00008BEC, size 0x00000A00 elf-loader: /home/jules/git/fusesoc/hello.elf was loaded Loading 9595 words Hello world, from an OpenRISC system! Closing RSP server
Re-run the simulation now and get fusesoc to enable dumping of a waveform and the CPU's execution trace.
fusesoc sim mor1kx-generic --elf-load hello.elf --trace_enable --vcd
The log files of the run (and everything which is compiled to run the sim) can be found under
build/mor1kx-generic/sim-icarus/
In particular, inspect the CPU's instruction trace in the file:
build/mor1kx-generic/sim-icarus/mor1kx-trace.log
The beginning of the file looks like so:
S 00000100: 18000000 l.movhi r0,0x0000 r0 = 00000000 flag: 0 S 00000104: 18200000 l.movhi r1,0x0000 r1 = 00000000 flag: 0 S 00000108: 18400000 l.movhi r2,0x0000 r2 = 00000000 flag: 0 S 0000010c: 18600000 l.movhi r3,0x0000 r3 = 00000000 flag: 0 S 00000110: 18800000 l.movhi r4,0x0000 r4 = 00000000 flag: 0 S 00000114: 18a00000 l.movhi r5,0x0000 r5 = 00000000 flag: 0 S 00000118: 18c00000 l.movhi r6,0x0000 r6 = 00000000 flag: 0 S 0000011c: 18e00000 l.movhi r7,0x0000 r7 = 00000000 flag: 0
Each line contains details of an instruction executed by the processor.
The snippet above shows the processor starting up at it's reset address 0x100 and running initialisation code (clearing registers). The S indicates it is in supervisor mode (as opposed to user mode), and the program counter (PC) is next, followed by the binary value of the instruction at that PC, and then disassembly (l.movhi r0,0x0000, for instnace moves 0 into the top half of register r0, and clears the rest of it, too). The next is the result after the execution of the instruction (r0 contains 0), and then the status of the CPU's flag bit.
The graphical representation of the operation of the system can be viewed via the VCD file dumped out by the simulator.
This file is:
build/mor1kx-generic/sim-icarus/testlog.vcd
Open it with GTKWave:
gtkwave build/mor1kx-generic/sim-icarus/testlog.vcd
In the hierarchy browser window in the top left-hand corner of the window, expand `orpsoc_tb` and then dut (this is an acronym of design under test, a commonly used term for the thing we're testing). Highlight the mor1kx0 instance to get a list of its signals in the window below.
Select the signals beginning with iwbm... (click then shift+click) and click the Insert button below that pane. Do the same again for the dwbm... signals. This should make some signals appear in the waveform frame on the right. These signals are the instruction bus and data bus of the processor. They are separate buses, showing off the Harvard architecture of the processor, that is they have separate access buses for instruction and data.
Click the zoom out button (minus sign icon) to zoom out and show the first
The above screenshot shows the first few accesses on the instruction bus, with the processor fetching the first number of instructions. Zooming out further will show the processors activity becomes less regular eventually. This is due to the processor executing from its cache and performing things like data accesses.