full-install

Exhaustive Installation instructions

This page describes the complete instructions for installing Rabbits from scratch.

Prerequisites

First, you will have to check that all the following prerequisites are installed on your system before going any further.

For sources:
git (required version above 1.6.5.8, preferred version 1.7.0 and above).
For compilation of the whole stuff:
gcc and g++, version 4.7.2 and above are fine
For qemu:

For Rabbits

You are definitely encouraged to use the package manager of your GNU/Linux distribution to install these packages.

Rabbits sources

Once you are sure that your version is correct (git --version gives you a result above 1.6.5.8, which is quite sure if you have updated your distro in the last decade), you can launch the following command to retrieve the Rabbits framework sources.

If you are a Rabbits user external to the development team

Using the ‘git’ protocol doesn’t grant you write access, but you can still  contribute patches to the team!

If you develop simulation models or tools included into the framework

Using ssh (but you need then to be known by the system by giving the admin a public key) allows you to pull and push from the repos.

In both cases, the command will create a directory named rabbits containing the Rabbits framework.

Rabbits Installation

Before trying to compile any platform in the Rabbits framework, you will have to accomplish a few steps.

SystemC installation

As we rely on a vanilla SystemC version, you will have to install it by your own. You can download it from OSCI website.
For all installation errors during the installation of SystemC, please refer to the OSCI website.

    • Note that vanilla SystemC-2.2.0 emits lots of “mutated” warning (use -fpermissive to ignore these if you write your own Makefile for a Rabbits Platform)
  • SystemC-2.3.1 is the current version and should be preferred. If you fall into linking problems, which arise here and then but usually not anymore on recent linux distros (some issue with sc_main being a hidden symbol that you don’t even want to know about) when building platforms, compile only the static version of the systemc library, by invoking

    And it should go smooth.

Rabbits Environment setup

The following step in the Rabbits framework setup is to set up the environment variables.
For this, please use the rabbits_env.example file to create a correct rabbits_env file in the root directory of Rabbits.

Rabbits installation

The last step of Rabbits installation is accomplished by running the installation script.

Note that this script should produce a clean output. If it is not the case, something went wrong. Please refer to the FAQ section of this site.

Platform building

After having installed the Rabbits framework, you can now use it, and for example compile virtual platforms.
Rabbits comes with a set of example platforms. In order to give an example of the usage of Qemu, we will describe the procedure to use the roger example platform.

First, you can find this platform in the directory platforms/roger.

If your Rabbits environment is correctly installed, all you have to do to build the virtual platform is to type the make command.
Beware that before any action on the rabbits platforms, you have to source the rabbits_env file with:

This will produce an output like the following one (if not please go back to previous step).

Now the virtual platform is ready for usage. The executable file is run.x, but in order to pass the correct arguments you will find a script named frame_roger in the platform directory.

Building trial software for Roger

Before trying to launch the roger platform, you will have to build the trial software provided by the Rabbits framework in roger/soft.

Cross toolchain

Roger is an ARM based virtual platform. To build its software, you need an ARM targeted compiler.
Note that for other platforms, other cross-dev environments may be necessary, we shall try to maintain READMEs given the information on what is required on a platform per platform basis.

The recommended way of building a cross-development environment is by using the opensource project crosstool-ng. You can also download a cross-dev environment from CodeSourcery (thas has been acquired by Mentor Graphics since) here, or use any method you’d like.
However, as the Rabbits software uses a specific Linux version, libc.a versions issues are likely to arise.

Crosstool-ng requires to compile the environment and every version may have slight differences in installation, leading to unexpected headaches. Using version 1.17.0 of crosstoolng is known to work with the following configuration file config_cng_1.17.0, to be copied into the crosstoolng directory under the name .config. (Note that version 1.18.0 has issues with Rabbits). Here is the procedure:

And fetch some coffee and readings, …

The CodeSourcery solution is a binary one, making things faster and easier if it works well on your system, and also provided that is it compatible with the current linux distro in Roger, which as time goes by is less and less probable.

Environment setup

As for Rabbits framework, you have to setup a software environment. To do so, use the soft_env.example example file to create a soft_env file.

For example, for the CodeSourcery toolchain proposed before:

Trial software building

Once you have sourced the soft_env file, you can build the trial software by running the build_soft.sh script.

Running the Roger platform

Once you built the platform and the trial software, you can launch the platform using the frame_roger script.

You should have the platform running, booting a Linux kernel and then proposing a prompt. If you wish to run the h264 video decoder, you need to perform the following steps under the simulated prompt that is available in the simulated tty.

That’s all. Enjoy the Rabbits framework.