GNU toolchain
Introduction
This project aims to maintain a set of easy to use development tools for the OpenRISC processor platform.
The included tools are currently:
- GNU binutils-2.18.50
- GNU GCC-4.2.2
- GNU GDB-6.8
- uClibc-0.9.29
- Linux-2.6.24
- BusyBox-1.7.5
- or1ksim-0.3.0
Installation
Script download
The normal method of installation for the GNU toolchain uses a script which will download and install the latest versions of all tools. The script can be downloaded here.
The latest version of the toolchain, version 5a, has finally been released. It is a significant upgrade the previous version, including a new version of GCC, the Linux kernel, GDB and or1ksim. Also note the prefix of the resulting executables is now or32-elf rather than or32-uclinux as it was under the previous toolchain version.
Toolchain installation for Linux
System setup
Compiling the OpenRISC toolchain from sources requires that some standard development tools are already installed. Most of these tools are pre-installed in modern Linux distributions. However, some may still require installation before the OpenRISC toolchain can be built.
The specifics of installing these required tools differs from distro to distro. The example given here uses the apt-get package management tool common among Debian and Ubuntu distros (among others,) however it should be easy enough to perform this installation using the package management tool your system uses.
# sudo apt-get update
# sudo apt-get -y install build-essential make gcc g++ flex bison patch texinfo libncurses-dev
Once these tools are installed on the system, the toolchain script can be downloaded and run.
Perform the installation
Save the script in a new directory. Open a console, change path to where the script is located and run:
# sh MOF_ORSOC_TCHN_v5c_or32-elf.sh
Follow the prompts given by the script. It will automatically attempt to install the toolchain under the current directory, but it can be targeted to install anywhere on the current system. For instance, setting the install path as /opt will result in the toolchain being installed under /opt/or32-elf however in most cases installation to any path outside of the user's home directory will require root access, or the script being with sudo.
Please ensure that at least 2 gigabytes of storage is available on the local harddisk before attempting to build the toolchain. Compile time can be anywhere from 30 minutes to 2 hours, depending on the host machine.
Precompiled Toolchains
Here we provide precompiled toolchains for those who wish to use them in environments where they cannot perform the installation. These have not been tested on any other platform than the ones they were compiled on. To test which version you should get, run uname -m.
Installation of precompiled toolchain
Change to the directory where you wish the toolchain to be installed, and extract the package with the following command:
# tar xjf or32-elf-linux-x86.tar.bz2
This will create a new directory, or32-elf/, containing the toolchain. Add the executable path to your shell's PATH variable by adding the following line to your ~/.bashrc file:
export PATH=$PATH:⟨place where package was extracted⟩/or32-elf/bin
Toolchain installation for Cygwin Windows
System setup
The Cygwin Unix-like shell environment for Windows is required to build and use the toolchain. See the Cygwin website for instructions on how to install the basic Cygwin package.
There are some applications and libraries which must be installed in addition to the basic Cygwin packages. These are installed by running Cygwin's setup.exe, and continuing to the package "chooser" window, which, by default, presents all available packages sorted by category. Follow the list below, expand the appropriate category and mark the listed programs for install.
Category: Devel
- autoconf
- automake
- binutils
- bison
- gcc (gcc:C compiler upgrade helper)
- gettext-devel
- libiconv
- libncurses-devel
- make
Category: Utils
- bzip2
- patch
Category: Web
- wget
Once these applications and libraries are marked for installation continue with setup.exe until it is finished. The Cygwin system should now be capable of compilation of the OpenRISC toolchain.
Perform the installation
Save the script in a new directory. Open a console, change path to where the script is located and run:
# sh MOF_ORSOC_TCHN_v5c_or32-elf.sh
Follow the prompts given by the script. It will automatically attempt to install the toolchain under the current directory, but it can be targeted to install anywhere on the current system. For instance, setting the install path as /opt will result in the toolchain being installed under /opt/or32-elf. Please note that the BusyBox applications built in the script cannot be installed into the ramdisk due to ext2 filesystem support issues under Cygwin.
Precompiled Toolchains
Here we provide precompiled toolchains for those who wish to use them in environments where they cannot perform the installation.
Installation of precompiled toolchain
Change to the directory where you wish the toolchain to be installed, and extract the package with the following command:
# tar xjf or32-elf-cygwin-1.7.tar.bz2
This will create a new directory, or32-elf/, containing the toolchain. Add the executable path to your shell's PATH variable by adding the following line to your ~/.bashrc file:
export PATH=$PATH:⟨place where package was extracted⟩/or32-elf/bin
Toolchain installation for Mac OS X
At present the script does not compile the toolchain completely under Mac OS X. The core components such as binutils, GCC with uClibc and GDB, can be compiled seperately. See the section on doing this by hand, below.
Precompiled Toolchains
Here we provide precompiled toolchains. Note that this first one, for Mac OS X 10.6 (Snow Leopard), will probably only work on Snow Leopard (and potentially Leopard) and not on OS X 10.4 (Tiger).
Installation of precompiled toolchain
Change to the directory where you wish the toolchain to be installed, and extract the package with the following command:
# tar xjf or32-elf-linux-x86_64-OSX-10.6.tar.bz2
This will create a new directory, or32-elf/, containing the toolchain. Add the executable path to your shell's PATH variable by adding the following line to your ~/.bashrc file:
export PATH=$PATH:⟨place where package was extracted⟩/or32-elf/bin
Robert Guenzel has provided an application note on building the tool chain (excluding GDB) for Mac OS 10.4: chschroeder.gamiro.de/rg/or1ksim_macOS10.4.pdf. Users will find this provides valuable additional information beyond the instructions above.
Toolchain installation by hand
Embecosm Application Note 2 outlines manually compiling and installing the individual components of the OpenRISC toolchain. This is useful for those who wish to customise the components included in the toolchain, or those who experience trouble with the provided install script.
Script download
The normal method of installation for the GNU toolchain uses a script which will download and install the latest versions of all tools. The script can be downloaded here.
The latest version of the toolchain, version 5, has finally been released. It is a significant upgrade the previous version, including a new version of GCC, the Linux kernel, GDB and or1ksim. Also note the prefix of the resulting executables is now or32-elf rather than or32-uclinux as it was under the previous toolchain version.
Feedback, Bugs and Assistance
To participate in development, or discuss and report success/failure building the toolchain, go to the OpenRISC forum.
Or keep up to date with the goings on of the toolchain by subscribing to the OpenRISC mailing list. Enable the subscription by going to your OpenCores account page (click My Account in the top left of the page) and check the openrisc box under Subscriptions.
This set of tools, or toolchain, is based around the GNU binutils and GNU Compiler Collection (GCC) packages, which provide the basic compilation related functions of the toolchain. Also included are libraries and specialised software for the OpenRISC platform. Included are OpenRISC targeted versions of the uClibc library, the Linux 2.6 kernel and BusyBox. In addition there are some tools aimed at assisting development on the OpenRISC platform. The GNU Debugger (GDB) is included and can be used to debug code running on the OpenRISC architectural simulator, or the or1ksim tool, which is also included in this project. To ensure an easy installation process, and automated install script is provided.
GNU binutils
This is a collection of tools for the manipulation of object code in various object file formats. Among its many tools, it provides the assembler and linker.
More information about the GNU project's release of binutils can be found at its homepage.
GNU GCC
A version of GCC targeted at the OpenRISC platform is provided here. Known as a cross compiler, it is a version which will create code that is executable on an OpenRISC processor.
For more information about the official GCC releases can be found at the project's homepage.
Known issues:
-
Backwards compatibility issue: The old GCC 3.4.4 for OpenRISC defined three constants, OR1K, __or1k__ and __OR1K__, allowing users to bracket OpenRISC dependent code with #ifdef __OR1K__. These are not at present defined in the current GCC 4.2.2 by default, so users must explicitly set them by hand
-
Backwards compatibility issue: The old GCC 3.4.4. for OpenRISC assumed the availability of hardware multiplication, but not hardware division by default (i.e. -mhard-mul, -msoft-div), which was consistent with the default Verilog configuration. The current GCC 4.2.2 appears to assume neither hardware multiplication nor hardware division are present (i.e. -msoft-mul, -msoft-div). The old behavior can be restored by using -mhard-div on the GCC command line of in the CFLAGS within Makefiles.
GNU GDB
The GNU Project Debugger (GDB) is a standard debugging tool. It is used for debugging code whilse it is executing on any OpenRISC target, be it simulated (architectural simulator or RTL) or physical (FPGA, or ASIC.) At early stages of development it is the easiest way of transferring and running code in an OpenRISC based system.
GDB 6.8 has now been ported to the OpenRISC 1000 architecture. The latest version (2.1) of the source code patch for the standard GDB 6.8 distribution is available in the OpenRISC 1000 Downloads section here.
This latest version supports the GDB Remote Serial Protocol (RSP), which will ensure ongoing compatibility with GDB in future releases. The legacy OpenRISC Remote JTAG Protocol is still supported for backwards compatibility, but is now deprecated. All new users and applications should adopt the RSP interface.
This version of GDB works directly with Or1ksim 0.3.0, the current stable release of The OpenRISC 1000 Architectural Simulator, Or1ksim. It is not suitable for earlier versions of the simulator.
To date this release has been tested on the architectural simulator, Or1ksim, a cycle accurate Verilator model of ORPSoC and on the ORSoC FPGA board. Feedback from users on experience with other hardware (via the tracker) will be appreciated.
Details of the internal workings of the GDB 6.8 port for OpenRISC 1000 can be found in the application note Howto: Porting the GNU Debugger: Practical Experience with the OpenRISC 1000 Architecture published by Embecosm.
Details of the implementation of the RSP server functionality for Or1ksim can be found in the application note Howto: GDB Remote Serial Protocol: Writing a RSP Server published by Embecosm.
This version of GDB works with the graphical user interface DDD. It has also been tested with the Insight graphical debugger and appears to work.
Known issues:
-
Message "Value being assigned to is no longer active" when trying to alter a register immediately after loading a new program image. This is a known bug in GDB. It is one feature of a complex problem with the way GDB represents stack frames.
One workaround is to set a breakpoint on the first instruction of the loaded image, run to that breakpoint (which will do nothing), and then GDB will allow registers to be set. However user nyawn has found a small patch from the Fedora project which fixes this particular problem. It can be found at:
cvs.fedoraproject.org/viewvc/devel/gdb/gdb-6.8-bz436037-reg-no-longer-active.patch?view=log
uClibc
This is a C library aimed at embedded Linux systems. It removes a lot of the bulk that comes with a standard C library, such as the GNU C Library, making it more suitable for compiling embedded applications against.
For more information about uClibc see the project's homepage.
Linux kernel
An operating system kernel. It is ported to the OpenRISC architecture and features preemptive multitasking, virtual memory and threading to name just a few things.For more information about the Linux kernel sources see the project's homepage.
BusyBox
BusyBox combines tiny versions of many common UNIX utilities into a single small executable. It provides replacements for most of the utilities you usually find in GNU fileutils, shellutils, etc.Although version 1.7.5 is included here, versions up 1.16.0 are known to work in the RAMdisk in the OpenRISC port of the Linux kernel.
For more information about BusyBox see the project's homepage.
OpenRISC architectural simulator
A simulator of the generic OpenRISC 1000 architecture simulator capable of emulating OpenRISC based computer systems. It provides high level, fast architectural simulation that allows early code analysis and system performance evaluation.For more information see the project's homepage here at OpenCores.
GNU toolchain with newlib
There is also available a port of the GNU toolchain using newlib 1.17.0 instead of uClibc. This library provides a better development platform for bare-metal applications.
For information about newlib, please visit its site: http://sourceware.org/newlib/
Installations steps
At some point in the future an alternative toolchain script, installing newlib instead of uClibc and Linux, will be made available. For now we will provide some basic steps for getting GCC built with newlib, and a simple outline of how to modify any parts of newlib as desired.
Do the following steps in the same working directory:
- Download binutils-1.18.50 sources from here, extract and apply this patch.
- Download GCC-4.2.2 sources from here, extract and apply this patch.
- Download newlib-1.17.0 sources from here, extract and apply this patch.
- Create the directory where we'll install the tools. A good choice is /opt/or32-newlib. Create this directory and either set permissions for all to have write access to it (sudo mkdir /opt/or32-newlib; sudo chmod a+rwx /opt/or32-newlib) , or do the following steps as the root user with sudo.
- Make a directory in the work path alongside the extracted sources called b-b, short for build-binutilities, and change into it.
- Configure binutilities with the following: ../binutils-2.18.50/configure --target=or32-elf --prefix=/opt/or32-newlib --disable-checking making sure to set the --prefix option to whatever install path you used if it's not /opt/or32-newlib. Once it is configured do a make all install.
- Export your install path's bin directory to the shell's PATH variable: export PATH=$PATH:/opt/or32-newlib/bin - you should probably set this in a shell init script somewhere for the future.
- Be sure that any other OpenRISC toolchain directories are not in your shell's PATH variable before building GCC.
- Link the newlib and libgloss directorys, from inside the newlib source directory, into GCC's source directory. Change into the GCC source directory (cd gcc-4.2.2) and create symbolic links with the following two commands ln -s ../newlib-1.17.0/newlib and ln -s ../newlib-1.17.0/libgloss
- Make a directory in the work path alongside the extracted sources called b-gcc and change into it.
- Configure GCC with the following: ../gcc-4.2.2/configure --target=or32-elf --prefix=/opt/or32-newlib --with-gnu-as --with-gnu-ld --disable-libssp --verbose --with-newlib --enable-languages=c of course altering the --prefix path if it's not what we use here. Once it is configured to a make all install
- The author found the resulting GCC would not work properly until a GCC spec file was created under /opt/or32-newlib/lib/gcc/or32-elf/4.2.2. To do this, cd to /opt/or32-newlib/lib/gcc/or32-elf/4.2.2 and type or32-elf-gcc -dumpspecs > specs, this file also needs some customisation. Read the section below on editing the gcc specs file.
newlib is great for writing standalone, so-called bare-metal, applications. This means programs that will run without an underlying operating system layer such as the Linux kernel. newlib provides many basic libraries such as stdio for printf'ing and string for malloc etc.
The configuration of the library is important for generating that will work on your system. For instance, all printf, and similar character I/O calls communicate directly with the UART in the OpenRISC port. This means the UART configuration must be included in the OpenRISC-specific parts of libgloss inside newlib. It is a similar situation with calls such as malloc, in that it depends on the included linker script for sections of memory that are allowed to be malloced. This configuration set by the way syscall handling is performed by the OpenRISC-specific code.
In the OpenRISC port of newlib, syscall handlers are implemented in files under the libgloss/or32 path. To understand how the syscalls should be handled in newlib, read the relevant section of the FAQ on the newlib website. In particular, read the comments in newlib/libc/include/reent.h for an explanation of choices regarding syscall implementation.
To change the configuration for your OpenRISC system, edit the appropriate files in libgloss/or32. Once these files are updated, newlib and GCC should be compiled again to generate the updated library. This is a simple case of re-running make all install inside the b-gcc, so long as it is kept after installation.
Each time GCC and the library are recompiled the GCC specs file must be re-generated also. See the following section for further information.
GCC's specs file and linker script
As mentioned in the installation steps, a GCC spec file (called specs, containing spec strings) should be created in order to configure a couple of aspects of GCC's behaviour. See this page for information about GCC spec files.
Using this file we will configure GCC, by default, to use a specific linker script and set some link-time options which will call libraries in a specific order.
Open the spec file we creating during the install (or create one in /opt/or32-newlib/lib/gcc/or32-elf/4.2.2 by cding to that path and running or32-elf-gcc -dumpspecs > specs) for editing.
We will edit the *endfile and *link sections to look like the following:
*endfile:
-lor32 -lc -lgcc -lc -lor32
*link:
/opt/or32-newlib/or32-elf/lib/or32.ld
The *endfile section specifies object files to include at the end of the link command. Here we specify certain libraries and the order in which they should be used. They are in this order, from left to right becuase libor32 requires things from the newlib libc, which requires things from the inbuilt libgcc, which utlimately needs a couple of calls (sbrk, exit) from libor32.
The *link section is for passing options to the linker, but we use it to simply specify which linking script to use.
Unfortunately it appears that each time GCC and newlib are re-compiled and installed this spec file must be re-generated and updated.
newlib Port Acknolwedgement
This port is based on the newlib-1.13.0 port by Jacob Bower, found here.
Wishlist
The following is a list of future work for the GNU toolchain port.
If you want to help, send an email to openrisc_team@opencores.org
- A nice tutorial, showing off the installation and use of the new toolchain.
- Port of the toolchain enabling the 64-bit features of the OpenRISC spec.
- Write optimized versions of routines in uClibc instead of using generic ones.
- Testing the script and resulting toolchain on other platforms.
Feel free to post any suggestions to the OpenRISC forum or an email to openrisc_team@opencores.org
Developers
The team working on the GNU Toolchain port:
- Jeremy Bennett, jeremybennett@opencores.org (GDB, Or1ksim)
- Rich D'Addio, rich_daddio@opencores.org (GCC, Linux)
- Marcus Erlandsson, marcus.erlandsson@opencores.org
- Julius Baxter, julius@orsoc.se (install script)