OpenRISC_GNU_tool_chain.mw

OpenRISC is supported by a 32-bit GNU toolchain offering C and C++ support. The toolchain is available in several forms, depending on which C standard library they use

* or1k-elf for bare metal use, based on the newlib library
* or1k-linux-uclibc for Linux application use, based on the uClibc library.
* or1k-linux-musl for Linux application use, based on the musl library. (recommended over uClibc)

'''You can find more information about the toolchains on the [http://openrisc.io/software software overview]'''

Below you find some '''legacy''' alternatives to the currently maintained toolchains.

==== Linux (uClibc) toolchain (or1k-linux-uclibc) ====

This is a C library aimed at embedded systems. It removes a lot of the bulk that comes with a standard C library, such as the GNU C Library, but still has all the functionality needed for an operating system such as Linux, so it is ideal for embedded applications.

At present the OpenRISC port of uClibc is hosted on a git repository provided by [http://southpole.se/ South Pole], which can be browsed and downloaded from [http://openrisc.southpole.se/cgit.cgi/jonas/uClibc/ http://openrisc.southpole.se/cgit.cgi/jonas/uClibc/]

For more information about uClibc see the [http://www.uclibc.org/about.html project's homepage].

''TODO:'' Write optimized versions of routines in uClibc instead of using generic ones.

===== Initial preparations =====
 
 cd ~
 mkdir openrisc
 cd openrisc
 
 sudo mkdir /opt/or1k-toolchain
 sudo chown username:username /opt/or1k-toolchain
 
 export PATH=$PATH:/opt/or1k-toolchain/bin
 unset LD_LIBRARY_PATH

===== or1k-src =====

NOTE: on 32-bit machines --disable-werror is needed due to an enum acting as
bit mask is considered signed

 cd ~/openrisc
 git clone git://github.com/openrisc/or1k-src.git
 mkdir build-or1k-src
 cd build-or1k-src
 
 ../or1k-src/configure --target=or1k-linux-uclibc --prefix=/opt/or1k-toolchain \
 --disable-shared --disable-itcl --disable-tk --disable-tcl --disable-winsup \
 --disable-libgui --disable-rda --disable-sid --disable-sim --disable-gdb \
 --with-sysroot --disable-newlib --disable-libgloss --disable-werror
 
 make -j9
 make install

===== Linux headers =====

 export SYSROOT=/opt/or1k-toolchain/or1k-linux-uclibc/sys-root
 
 cd ~/openrisc
 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
 cd linux
 ARCH=openrisc make INSTALL_HDR_PATH=${SYSROOT}/usr headers_install

===== gcc stage 1 =====

 cd ~/openrisc
 git clone git://github.com/openrisc/or1k-gcc
 
 mkdir build-gcc
 cd build-gcc
 
 ../or1k-gcc/configure --target=or1k-linux-uclibc --prefix=/opt/or1k-toolchain --disable-libssp \
 --srcdir=../or1k-gcc --enable-languages=c --without-headers --enable-threads=single \
 --disable-libgomp --disable-libmudflap --disable-shared --disable-libquadmath \
 --disable-libatomic --disable-werror
 
 make -j9
 make install

===== uClibc =====

 export SYSROOT=/opt/or1k-toolchain/or1k-linux-uclibc/sys-root
 
 cd ~/openrisc
 git clone git://github.com/openrisc/uClibc-or1k.git
 
 cd uClibc-or1k
 make ARCH=or1k defconfig
 make -j9
 make PREFIX=$SYSROOT install

===== gcc stage 2 =====

 cd ~/openrisc
 cd build-gcc
 
 rm -rf *
 
 ../or1k-gcc/configure --target=or1k-linux-uclibc --prefix=/opt/or1k-toolchain --disable-libssp \
 --srcdir=../or1k-gcc --enable-languages=c,c++ --enable-threads=posix --disable-libgomp \
 --disable-libmudflap --with-sysroot=${SYSROOT} --disable-multilib --disable-werror
 
 make -j9
 make install

===== Hints when cross compiling with the or1k-linux-uclibc toolchain =====

Since autotools doesn't know about or1k run the following command to replace or32 with or1k

 find ./ -type f -name '*' -print | xargs sed -i 's/or32/or1k/'

Building with the following commands will work in a number of situations

 ./configure --host=or1k-linux-uclibc --prefix=/opt/or1k-toolchain/or1k-linux-uclibc/sys-root/usr
 make
 make install

Some programs embed the --prefix parameter into the binaries, but those programs usually use the DESTDIR environment variable
 ./configure --host=or1k-linux-uclibc --prefix=/usr
 make
 make DESTDIR=/opt/or1k-toolchain/or1k-linux-uclibc/sys-root install

=== Support for non-Linux systems ===

==== Microsoft Windows with Cygwin ====

At present only the older pre-compiled OpenRISC toolchains exist for Cygwin. The OpenRISC project currently does not have a maintainer for the toolchain on the Cygwin platform. Without one it is not certain that each toolchain release will be built for Cygwin.

If you would like to contribute to the project by maintaining a build script and guide for Cygwin platforms, please contact the OpenRISC team.

Alternatively, the ''orbuild'' framework is known to work under Cygwin, see above for more information.

===== Precompiled or1ksim and assembler =====

A contributor has made availble a precompiled version of or1ksim-0.4.0 and the OR1K assembler for Cygwin. 

It can be downloaded [http://j-software.dk/or1k/or32.zip here].

==== Apple Mac OS X ====

Robert Guenzel has provided an [http://chschroeder.gamiro.de/rg/or1ksim_macOS10.4.pdf application note] on building the toolchain (excluding GDB) for Mac OS 10.4. Users will find this provides valuable additional information beyond the instructions above.

It seems Guenzel was able to install the toolchain without hick-ups. This is not the case anymore, please follow the instructions below to install the newlib toolchain.  


See the following links for the appropriate development versions of the tools and libraries: [[OpenRISC_GNU_tool_chain#Development_version|binutils]], [[OpenRISC_GNU_tool_chain#Development_version_2|gcc]], [[OpenRISC_GNU_tool_chain#Development_version_3|newlib]]


The following assumes a checkout of the development repositories, which at present can be done with the following:

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

The following compile instructions will install into <code>/opt/or1k-toolchain</code> so make sure it exists and is writable by the user or whoever is running the <code>make install</code> commands.

Make a build directory each for the gnu-src tools and gcc, alongside the checkouts, we'll call them <code>bld-or1k-src</code> and <code>bld-or1k-gcc</code> respectively.
 mkdir bld-or1k-src
 mkdir bld-or1k-gcc

Requirements: 
  Apple Developer: Command Line Tools
  Brew installations: gmp libmpc mpfr cloog isl
  Variables ~/.bash_profile: export CC=cc / export CXX=c++
  Add toolchain to PATH: /opt/or1k-toolchain/bin

Build the first set of tools, binutils etc.
 cd bld-or1k-src
 
 ../or1k-src/configure --target=or1k-elf --prefix=/opt/or1k-toolchain --enable-shared \
 --disable-itcl --disable-tk --disable-tcl --disable-winsup --disable-libgui --disable-rda \
 --disable-sid --disable-sim --disable-gdb --with-sysroot --disable-newlib \
 --disable-libgloss  --disable-werror
 make
 make install

Build gcc

 Download and unpack libgmp
 Rename to gmp and move to or1k-gcc/.
 Download and unpack libmpfr
 Rename to mpfr and move to or1k-gcc/.
 Download and unpack libmpc
 Rename to mpc and move to or1k-gcc/.
 
 cd ../bld-or1k-gcc
 
 ../or1k-gcc/configure --target=or1k-elf --prefix=/opt/or1k-toolchain --enable-languages=c \
 --disable-shared --disable-libssp --disable-werror
 make
 make install

Build newlib and gdb (without or1ksim in this case)
 cd ..
 rm -rf bld-or1k-src
 mkdir bld-or1k-src  
 cd bld-or1k-src
 
 ../or1k-src/configure --target=or1k-elf --prefix=/opt/or1k-toolchain --enable-shared \
 --disable-itcl --disable-tk --disable-tcl --disable-winsup --disable-libgui --disable-rda \
 --disable-sid --disable-sim --disable-or1ksim --enable-gdb  --with-sysroot --enable-newlib \
 --enable-libgloss --disable-gdbtk --disable-werror
 make
 make install

Build gcc again, this time with newlib
 cd ..
 rm -rf bld-or1k-gcc
 mkdir bld-or1k-gcc
 cd bld-or1k-gcc
 
 ../or1k-gcc/configure --target=or1k-elf --prefix=/opt/or1k-toolchain --enable-languages=c,c++ \
 --disable-shared --disable-libssp --with-newlib
 make
 make install

See the page on the [[Newlib|newlib library port]] for details on what you've just built and installed.

Obs.: 
# We compile or1k-src without "sim". Generally it is enabled. But if you turn it on, you get compilation problems with or1k-sim. 
# We disable gdbtk (probably gdbtui). We do this to avoid tcl/tk problems that arise on OSX. Some of it can be circumvented by changing the following lines in acinclude.m4 under gdb and libgui. 
 dir=`echo ${TCL_INCLUDE_SPEC}/tcl-private/generic | sed -e s/-I//` 
 dir=`echo ${TK_INCLUDE_SPEC}/tk-private/generic | sed -e s/-I//`
to
 dir=`echo ${TCL_INCLUDE_SPEC}/Headers/tcl-private | sed -e s/-I//` 
 dir=`echo ${TK_INCLUDE_SPEC}/Headers/tk-private | sed -e s/-I//`
* Then run autoconf under gdb and libgui. But you end up still having some other problems because the variable MAC_TCL turns out not be defined by the configure script.

== Tools ==

=== 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 [http://www.gnu.org/software/binutils/ GNU homepage].

It can be found here: [https://github.com/openrisc/or1k-src https://github.com/openrisc/or1k-src]

=== 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.

More information about the official GCC releases can be found at the project's homepage.

It is currently based on gcc-4.8.0.

It is hosted here: [https://github.com/openrisc/or1k-gcc https://github.com/openrisc/or1k-gcc]

=== GDB ===

The GNU Project Debugger (GDB) is a standard debugging tool. It is used for debugging code while it is executing on any OpenRISC target, be it simulated (architectural simulator or RTL) or physical (FPGA, or ASIC.) It also provides a convenient mechanism for transferring and running code in any OpenRISC based system.

==== GDB stable version ====

GDB 7.2 has now been ported to the OpenRISC 1000 architecture and is regarded as the stable implementation.

Key new features are:
* support for DWARF2 debug format by default.
* support for GCC 4.5.1.
* support for gdbserver under [[Linux|OpenRISC Linux]].
* support for core file debugging

Known issues are:
* there are still many regression failures, which remain to be investigated.
* gdbserver relies on a range of Linux system calls, not all of which are fully implemented.
* OpenRISC Linux does not currently generate valid core files.
* Message "Value being assigned to is no longer active" is given 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 [cvs.fedoraproject.org/viewvc/devel/gdb/gdb-6.8-bz436037-reg-no-longer-active.patch?view=log patch] from the Fedora project which fixes this particular problem. 

Details of the internal workings of the GDB port for OpenRISC 1000 can be found in the application note [http://www.embecosm.com/download/ean3.html Howto: Porting the GNU Debugger: Practical Experience with the OpenRISC 1000 Architecture] published by Embecosm. Although based on GDB 6.8, much of the content is relevant to GDB 7.2.

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.

==== Backwards compatibility ====

The following compatibility issues have been noted.
* The current stable version is only compatible with OpenRISC GCC 4.5.1 and later, due to the change in global symbol handling and changes to function prologues.
* Support for the legacy OpenRISC Remote JTAG Protocol has now been dropped.
* Only version 0.3.0 or later of the architectural simulator, [[Or1ksim]] is supported.

==== Building gdbserver ====

gdbserver can be run on an OpenRISC linux system to act as a RSP client and allow remote debugging of ''applications'' on the Linux system.

gdbserver must be built by hand. The following instructions assume you have used the <tt>bld-all.sh</tt> script to build the or32-linux toolchain.

'''Note.''' You must build your tool chain with uClibc compiled with UCLIBC_HAS_THREADS=y and PTHREADS_DEBUG_SUPPORT=y.

Change to the bd-linux-gdb/gdb directory

 cd bd-linux-gdb/gdb

Create a new directory, gdbserver, and change to it.

 mkdir gdbserver
 cd gdbserver

Configure gdbserver to run on or32-linux as host

 ../../../gdb-7.2/gdb/gdbserver/configure --host=or32-linux

Build the system

 make

Copy the <tt>gdbserver</tt> executable to the target Linux system for use. There are two ways to do this:
# FTP the file to the target OpenRISC Linux system. '''Note.''' You will need to make the file executable after it has been copied using ''chmod''.
# Copy <tt>gdbserver</tt> into a suitable directory in the Linux initramfs (for example arch/openrisc/support/initramfs/bin) and rebuild Linux. The executable will then always be there.

You can run gdbserver on the target Linux system as follows (using port 51000 as an example):

 gdbserver :51000 ''my_program''

This will allow ''my_program'' to be debugged remotely via port 51000. On the host workstation, you can then connect to this target (in this example at IP address 192.168.0.37) as follows:

 $ or32-linux-gdb ''my_program''
 ...
 (gdb) target remote 192.168.0.37:51000
 (gdb) break main
 (gdb) run

Which will run the program until it hits the breakpoint at the start of <tt>main ()</tt>. '''Note.''' You must have a copy of the program both on the target Linux machine (to execute) and on the workstation running gdb (for the symbol table).

==== Using GDB with Or1ksim ====

Users often wish to use GDB with [[Or1ksim]], the architectural simulator. Here  are some simple guidelines to get started.

Take a simple program which you have compiled something like this:

 or32-elf-gcc -g HelloWorld.c -o HelloWorld

'''Note.''' Remember to use -g so debug information is included. It doesn't affect program performance, but makes for a much richer debug experience.

Simplest way to debug is to use the built in Or1ksim within GDB. By default that gives you a simple config with 8M of memory.

 or32-elf-gdb HelloWorld
 ...
 (gdb) target sim
 (gdb) load
 <set up any breakpoints etc>
 (gdb) run
 ...

If you want to use Or1ksim standalone (perhaps with a more complex configuration), then start it up, specifying a port for debug connection. You can either do this within the config file (it is the ''rsp_port'' parameter), or specify it on the command line:

 or32-elf-sim --srv=51000 ...

This sets up GDB to use port 51000 to communicate on. You can specify any value up to 65535, although you should definitely avoid values below 1024. If you don't specify a value, Or1ksim will select a port at random and tell you.

In a separate window on the same machine start up GDB

 or32-elf-gdb HelloWorld
 ...
 (gdb) target remote :51000
 (gdb) load
 <set up any breakpoints etc>
 (gdb) continue
 ...

Note that the usage is slightly different, you are connecting to a model that is already "started", so you just continue execution. Don't worry, connecting stalls the model, while loading the image sets the PC to its entry point, so you will continue at the right place.

== Testing ==

Each tool is tested using the GNU tool regression test suites. The newlib toolchain is tested using the GDB simulator (which is [[Or1ksim]]) standalone. The uClibc toolchain is tested using OpenRISC linux running on Or1ksim, using FTP and telnet through a TUN/TAP Ethernet interface.

The results are large, so there is a separate page for the [[newlib tool chain test results|newlib toolchain test results]] and the [[uClibc tool chain test results|uClibc toolchain test results]].

== Bugs ==

The project uses [http://bugzilla.opencores.org/ Bugzilla] to track all the bugs in its hardware and software. That's a good place to look for existing bugs, or to report a new bug.

=== Support ===

This is an open source project, so the community provides support (although there are companies offering commercial support as well). The various [[OR1K:Community_Portal#Mailing lists|mailing lists]] and [[OR1K:Community_Portal#IRC|IRC]] are good places to seek assistance.

Also check the [[OpenRISC_GNU_tool_chain_troubleshooting|troubleshooting page]] for details on any fixes, or to document any issues with fixes.

== Future plans ==

See [[OR1K:FutureWork|Future Work]]