Newlib

From OR1K

Contents

Introduction

The OpenRISC 1000 port of the newlib library aims to provide a library to provide support for running on bare-metal hardware without an operating system. It is also used when running the GNU toolchain regression suite.

The library is automatically linked when using the newlib version of the GCC compiler (or32-elf-gcc). The target board is specified by -mboardname. If no board is specified, the default (-mor1ksim) is suitable for use with Or1ksim.

Port acknowledgements

This original port was for newlib 1.13.0 by Jacob Bower, then of Imperial College, London.

The port was completely rewritten and tested for newlib 1.18.0 by Jeremy Bennett of Embecosm.
Further information is availble in Embecosm Application Note 9Howto: Porting Newlib: A Simple Guide, which explains in full detail how the port for the OpenRISC 1000 architecture was done.

The port was subsequently extended by Julius Baxter to make support of multiple boards much more flexible.

Once again the port was rewritten mostly by Stefan Wallentowitz and is now a part of the official newlib library since 2.2.0

OpenRISC support library

To assist with using features of the OpenRISC processor such as exceptions, interrupts and timers, a support library has been implemented.

This library also provides support for particular boards in ORPSoC.

Support library functions

These functions are implemented in the or1k-support.c and or1k-support-asm.S files in the newlib/libc/machine/or32 path in the newlib port directory. The header, or1k-newlib-support.h is found in the newlib/libc/machine/or32/include path. Note that this header and the OR1K spr-defs.h header are installed also in the /install_path/or32-elf/include path.

TODO

Board support details

The OpenRISC portion of libgloss provides a simple way of adding support for boards by way of linking in a small library containing some values used at run-time to configure the system. Each board has its own path and libboard.a in the /install_path/or32-elf/lib/boards/boardname directory. The boardname above should correspond to a directory under this path.

Libgloss also implements system calls, and at present only read and write system calls are supported via the UART.

In the version currently in the repository, a handful of boards and the or1ksim architectural simulator are supported.

Board

Description

or1ksim

or1ksim simulator, no peripherals

or1ksim-uart

or1ksim simulator with a UART

ordb1a3pe1500

ORSoC development board 1, A3PE1500 part, as in ORPSoC

ml501

Xilinx ML501 board, as in ORPSoC

orpsocrefdesign

ORPSoC reference design

de0_nano

Terasic DE0 Nano

ordb2a

ORSoC development board 2

atlys

Digilent Atlys board

For example, to compile with support for the de0_nano board, one would pass the following options at compile-time.

or32-elf-gcc -mboard=de0_nano

Each libboard.a defines the following symbols:

Symbol

Description

_board_mem_base

Base of main memory

_board_mem_size

Size of main memory

_board_clk_freq

Frequency in hertz of CPU clock, also presumed as UART clock

_board_uart_base

Base address of a UART 16550 peripheral

_board_uart_baud

Desired buad rate for UART

_board_uart_IRQ

IRQ number of UART

_board_exit

A board exit function (weak, may be overriden in C)

Adding support for a new board

Adding additional boards (without recompiling and installing the toolchain) is as simple as creating a creating a libboard.a with the appropriate symbols set to the right values and placing it in the /install_path/or32-elf/lib/boards/boardname directory. The boardname should be the same as the one used when passing the -mboard=boardname to the compiler.

To create this libboard.a see examples of the existing boardname.S files in the newlib-1.x.0/libgloss/or32 path in the newlib port source.

For example, the ml501 board's code is in the newlib-1.x.0/libgloss/or32/ml501.S file and is as follows: