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:
1 2 3 |
pkg-config zlib1g-dev libglib2.0-dev |
For Rabbits
1 2 3 4 |
libgtk2.0-dev libdrm-dev libsdl1.2-dev libelf-dev |
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
1 |
git clone --recursive git://git-sls.imag.fr/Rabbits.git rabbits |
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
1 |
git clone --recursive ssh://git-sls.imag.fr/Rabbits.git rabbits |
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 invoking1systemc-2.3.1 $ ./configure --disable-sharedAnd 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.
1 2 3 4 5 6 7 8 9 10 |
rabbits$ cp rabbits_env.example rabbits_env rabbits$ rabbits$ cat rabbits_env # Place here the Path to this dir export RABBITS_DIR=; # Place here the Path to your SystemC install export RABBITS_SYSTEMC=; export PATH=$PATH:${RABBITS_DIR}/rabbits/tools [... skipped ...] |
Rabbits installation
The last step of Rabbits installation is accomplished by running the installation script.
1 |
rabbits$ ./install.sh |
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:
1 2 |
roger$ source /rabbits_env roger$ make |
This will produce an output like the following one (if not please go back to previous step).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
Compiling interconnect.cpp ... Compiling interconnect_master.cpp ... Compiling interconnect_slave.cpp ... Compiling mwsr_ta_fifo.cpp ... Compiling mem_device.cpp ... Compiling cpu_fvs.cpp ... Compiling cpu_logs.cpp ... Compiling qemu_cpu_wrapper.cpp ... Compiling qemu_wrapper.cpp ... Compiling qemu_wrapper_request.cpp ... Compiling ramdac_device.cpp ... Compiling sem_device.cpp ... Compiling slave_device.cpp ... Compiling master_device.cpp ... Compiling tg_device.cpp ... Compiling timer_device.cpp ... Compiling tty_serial_device.cpp ... Compiling main.cpp ... Compiling system_init.cpp ... Building run.x ... |
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:
1 2 3 4 5 6 7 8 9 10 11 |
#assuming you are into crosstool-ng-1.17.0 as a result of untaring the #crosstool-ng archive $ ./configure --enable-local $ make #assuming you have saved the configuration file into $HOME/Downloads $ cp ~/Downloads/config_cng_1.17.0 .config $ ./ct-ng menuconfig #set the install path ":Path and misc options -> Prefix directory" if you #do not want to use the default /opt/toolchains (as you need to be root to #install into it). Alternatively, you can edit the .config directly. $ ./ct-ng build |
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
roger/soft$ cp soft_env.example soft_env roger/soft$ roger/soft$ cat soft_env # Place here the path to the toolchain export RABBITS_XTOOLS= # Place here the prefix of the toolchain # arm-none-linux-gnueabi- for a arm-none-linux-gnueabi-gcc export RABBITS_CROSS_COMPILE=<prefix_of_the_toolchain> # Version of libc and ld (file should be named ld-${RABBITS_LIBC_VERSION}.so) export RABBITS_LIBC_VERSION=<toolchain_libc_version> [... skipped ...] |
For example, for the CodeSourcery toolchain proposed before:
1 2 3 4 5 6 7 8 9 |
# Place here the path to the toolchain export RABBITS_XTOOLS=/arm-2008q1 # Place here the prefix of the toolchain # arm-none-linux-gnueabi- for a arm-none-linux-gnueabi-gcc export RABBITS_CROSS_COMPILE=arm-none-linux-gnueabi # Version of libc and ld (file should be named ld-${RABBITS_LIBC_VERSION}.so) export RABBITS_LIBC_VERSION=2.5 [... skipped ...] |
Trial software building
Once you have sourced the soft_env
file, you can build the trial software by running the build_soft.sh
script.
1 2 |
roger/soft$ source soft_env roger/soft$ ./build_soft.sh |
Running the Roger platform
Once you built the platform and the trial software, you can launch the platform using the frame_roger
script.
1 |
roger$ ./frame_roger |
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.
1 2 3 |
/$ cd h264 /h264$ ./load_drvs /h264$ ./run_arm_dbf |
That’s all. Enjoy the Rabbits framework.