Electria suomeksi


OpenRISC Tutorial – Linux on DE0-Nano. Part I: Simulator.

Introduction

This tutorial is essentially an expanded version of OpenRISC tutorial from Kevin Mehall. We are covering the latest tools and code as of November 2013. Our tutorial is divided into the following sections:

Our tutorial is divided into parts. Each part should take about one day from the reader. We suggest working step by step, covering one part at a time. Following is the first part of the tutorial. After completing this part, the reader will know:

  1. Why we need a cross-compilation toolchain
  2. How to build one from the latest sources
  3. How to build the simulator
  4. How to build a Linux kernel targeted at the OpenRISC platform
  5. How to run Linux in the simulator

Prerequisites

We assume that our reader has access to a Debian workstation and the DE0-Nano development board from Terasic. Our workstation runs Debian 7.1 and we guarantee that our instructions are suitable for that version. We believe that other recent Debian-based Linux distributions should be suitable, but YMMV. You will save yourself a lot of trouble when using a 32-bit Linux. It is still possible to use 64-bit Linux, but it can be a tricky and inconvenient road.

In order to successfully complete this tutorial, you should be comfortable with Linux desktop environment and command line. Some understanding of Linux software development, including building software from source, will also be helpful.

Before we begin, please install the following packages:

$ sudo apt-get install build-essential flex bison patch \
texinfo libncurses5-dev libmpfr-dev libgmp3-dev \
libmpc-dev libzip-dev python-dev libexpat1-dev dejagnu

Toolchain

For those of our readers who have never worked with embedded systems, we should mention that in order to compile software for platforms other than what your desktop in running, you need a cross-compilation toolchain. In our case, your desktop machine (the host platform) is most probably an Intel or AMD-based PC, while the target platform is an OpenRISC. Therefore, we need a cross-toolchain, and we build one from scratch in the beginning of this part of our tutorial.

A toolchain is required to build both the operating system and the application software. In the embedded Linux world there is usually a separate toolchain for each purpose. In this part we will build the one needed for the operating system (in other words, kernel).

Starting

We will be keeping all our work in its own directory, which we’ll call the working directory from now on. Let this directory be $HOME/openrisc, so create it:

$ mkdir $HOME/openrisc; cd $HOME/openrisc

The OpenRISC project keeps their sources in their own Git repositories, which we will need to clone:

$ git clone git://github.com/openrisc/or1k-src.git
$ git clone git://github.com/openrisc/or1k-gcc.git

We will not alter the source directories, but rather build in different “build” directories. This allows us to easily clean the built files and start over again if something goes wrong. Create two build directories for auxiliary tools and for the GCC, respectively:

$ mkdir build_src; mkdir build_gcc

Finally, we create a directory for the toolchain:

$ mkdir toolchain

Remember that we still are in the $HOME/openrisc directory.

Now the working directory looks as follows:

$ ls -la
total 28
drwxr-xr-x 7 dmvo dmvo 4096 Nov 21 13:49 .
drwxr-xr-x 14 dmvo dmvo 4096 Nov 21 13:46 ..
drwxr-xr-x 2 dmvo dmvo 4096 Nov 21 13:48 build_gcc
drwxr-xr-x 2 dmvo dmvo 4096 Nov 21 13:48 build_src
drwxr-xr-x 35 dmvo dmvo 4096 Nov 21 13:02 or1k-gcc
drwxr-xr-x 44 dmvo dmvo 4096 Nov 21 12:33 or1k-src
drwxr-xr-x 2 dmvo dmvo 4096 Nov 21 13:49 toolchain>

Before we proceed with the actual build, we should add the path to our future toolchain binaries to PATH. To do that, we add the following to our $HOME/.profile:

$ PATH=$PATH:$HOME/openrisc/toolchain/bin

For the changes to take effect, you should log in again to your Gnome session (easy) or source the .profile (advanced).

If you would rather keep the modified PATH variable in your current shell session only, then simply export it:

$ export PATH=$PATH:$HOME/openrisc/toolchain/bin

Build the auxiliary tools

The set of tools includes binutils, GDB debugger, GNU profiler, C library and a number of other libraries and utilities. First we change to the build directory:

$ cd $HOME/openrisc/build_src

Then we run the configuration script:

$ ../or1k-src/configure --target=or1k-elf \
--prefix=$HOME/openrisc/toolchain --enable-shared \
--disable-itcl --disable-tk --disable-tcl \
--disable-winsup --disable-gdbtk \
--disable-libgui --disable-rda --disable-sid \
--disable-sim --disable-gdb --with-sysroot \
--disable-newlib --disable-libgloss \
--disable-werror

And then we build and install:

$ make; make install

Build the bootstrap compiler

The Gnu Compiler Collection, the GCC, consists of many parts, all but one of which require the C library as prerequisite, the C compiler being an exception. For that reason, in the context of embedded toolchains GCC is normally built in three steps:

  1. Build C compiler (the “bootstrap” compiler)
  2. Use C compiler to build the C library
  3. Build the rest of GCC.

In this step we build the bootstrap compiler. As usual, we use an empty directory, in this case the one we created previously:

$ cd $HOME/openrisc/build_gcc

We run configure, then make and install:

$ ../or1k-gcc/configure --target=or1k-elf \
--prefix=$HOME/openrisc/toolchain --enable-languages=c \
--disable-shared --disable-libssp

$ make; make install

The make command will take considerable time.

If everything was good, you should be able to check that the C compiler is indeed available:

$ or1k-elf-gcc --version
or1k-elf-gcc (GCC) 4.9.0 20130930 (experimental)
Copyright (C) 2013 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Build newlib and gdb

Now that we have an OpenRISC-targeted C compiler available, we can use it to build the C library and the GNU debugger gdb.

We need a new, clean build directory, so create one:

$ cd $HOME/openrisc
$ rm -rf build_src; mkdir build_src; cd build_src

At this point it is very important that the PATH variable is updated as mentioned above. This is because the newlib will be compiled by the cross-compiler for the or1k target. This cross-compiler was built in the previous step.

Now configure, make and install:

$ ../or1k-src/configure --target=or1k-elf \
--prefix=$HOME/openrisc/toolchain --enable-shared \
--disable-itcl --disable-tk --disable-tcl \
--disable-winsup --disable-gdbtk --disable-libgui \
--disable-rda --disable-sid --enable-sim \
--disable-or1ksim --enable-gdb --with-sysroot \
--enable-newlib --enable-libgloss

$ make; make install

Again, the make command should take significant time to complete.

Build full GCC

We are almost done with the toolchain. In this step we will build GCC now including C++ compiler. Also, GCC will be aware of the C library. Again, we want to have a clean build directory:

$ cd $HOME/openrisc
$ rm -rf build_gcc; mkdir build_gcc; cd build_gcc

Standard process implies configuration and building the compiler:

$ ../or1k-gcc/configure --target=or1k-elf --prefix=$HOME/openrisc/toolchain --enable-languages=c,c++ --disable-shared --disable-libssp --with-newlib
$ make
$ make install

The make command will take even more time than it did in previous steps. Be patient.

When make install is over, let’s check if we indeed installed the new compiler:

$ or1k-elf-g++ --version
or1k-elf-g++ (GCC) 4.9.0 20130930 (experimental)
Copyright (C) 2013 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Build simulator

The simulator, or1ksim, simulates an OpenRISC-based computer in the same manner as VMware simulates an Intel-based desktop. The simulator can therefore run binaries that have been compiled for OpenRISC without the need for an OpenRISC hardware. The simulator can therefore be used, for example, as a reference for a hardware implementation or for quick testing of the software without running it in a real FPGA.

In this section we will take the development version of or1ksim:

$ cd $HOME/openrisc
$ git clone --branch or1k-master git://github.com/openrisc/or1ksim.git

Once again, we are using a separate directory to build the simulator:

$ cd $HOME/openrisc
$ mkdir build_sim; cd build_sim
$ ../or1ksim/configure --target=or1k-elf \ --prefix=$HOME/openrisc/simulator
$ make all
$ make install

Finally, we should make the simulator binary available in our path:

$ export PATH=$HOME/openrisc/simulator/bin:$PATH

It would be wise to change your .profile accordingly.

Check that we indeed have the simulator available in our shell:

$ or1k-elf-sim --version
Seeding random generator with value 0x5ba287bf
OpenRISC 1000 Architectural Simulator, version 2012-04-27

Obviously, your random number seed will differ from ours!

Build Linux

This is the last section for this part. When you are done with it, you’ll have a full Linux system up and running on simulated hardware.

As in the previous sections, we want to use the latest and greatest version of Linux. To do that, follow the steps below:

$ cd $HOME/openrisc
$ git clone git://openrisc.net/jonas/linux
$ cd linux

While the latest release as of us writing this, is still expecting an old version of GCC compiler. Fortunately, switching to new compiler is easy. Open the following file in your favourite text editor (our favorite editor is vi):

$ vi arch/openrisc/kernel/vmlinux.lds.S

Navigate to line 33, which should read

OUTPUT_FORMAT("elf32-or32", "elf32-or32", "elf32-or32")

and change it to the following one:

OUTPUT_FORMAT("elf32-or1k", "elf32-or1k", "elf32-or1k")

Save the file and close the editor.

The following two commands should produce a working kernel:

$ make ARCH=openrisc defconfig
$ make ARCH=openrisc CROSS_COMPILE=or1k-elf- vmlinux

The latter command will produce a numbers of warning messages, which are benign, so you shouldn’t worry about them. After the command has finished, please check that you have the kernel image built:

$ ls -la vmlinux
-rwxr-xr-x 1 dmvo dmvo 5263003 Nov 27 15:27 vmlinux

The size for your binary might differ. This is normal.
By default, the Linux console is pointed to a telnet server built into the simulator. This isn’t what we want right now, so let’s switch this setting to use a terminal window for the console. Open the file arch/openrisc/or1ksim.cfg in your favourite text editor, and look for the section called “uart”. You should find it around line 640 of that file. Comment out the line:

channel = "tcp:10084"

And remove the comment around the line that reads:

channel = "xterm:"

This is how the uart section looks like in our setup:

section uart
enabled = 1
baseaddr = 0x90000000
irq = 2
/* channel = "file:uart0.rx,uart0.tx" */
/* channel = "tcp:10084" */
channel = "xterm:"
jitter = -1 /* async behaviour */
16550 = 1
end

This completes building the operating system.

Run Linux in simulator

This is the easiest section of this part. If you have changed directory since the previous step, navigate back to the Linux source tree:

$ cd $HOME/openrisc/linux

and issue the following command:

$ or1k-elf-sim -f arch/openrisc/or1ksim.cfg vmlinux

In a short while, you should see a new X terminal window showing Linux boot, similar to the one shown in our video.

Congratulations, now Part I is complete. In Part II, we will run Linux using real hardware, an OpenRISC-based system-on-chip programmed to the DE0-Nano development board.