Newlib.mw

= 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 -m''boardname''. If no board is specified, the default (-mor1ksim) is suitable for use with [[Or1ksim]].

= Port acknowledgements =

This [http://www.doc.ic.ac.uk/~jab00/or32-newlib/ 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 [[User:Jeremybennett|Jeremy Bennett]] of [http://www.embecosm.com Embecosm].
Further information is availble in [http://www.embecosm.com/download/ean9.html Embecosm Application Note 9] ''Howto: 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 [[User:Julius|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 <code>newlib/libc/machine/or32</code> path in the newlib port directory. The header, <code>or1k-newlib-support.h</code> is found in the <code>newlib/libc/machine/or32/include</code> path. Note that this header and the OR1K <code>spr-defs.h</code> header are installed also in the <code>/install_path/or32-elf/include</code> path.

They are accessible via the inclusion of the following header.

 <code>#include <or1k-support.h></code>

The following functions are provided

{| border="1" align="center" style="text-align:center;"
|'''Function Name'''
|'''Arguments'''
|'''Description'''
|'''Return value'''
|-
|<code>or1k_interrupt_handler_add</code>
|<code>int irq, void(*function_name)(void)</code>
|Install function_name as handler for interrupt at IRQ <code>irq</code>
|none
|-
|<code>or1k_interrupt_enable</code>	
|<code>int irq</code>	
|Enable generation interrupt at IRQ irq in PICMR	
|none
|-
|<code>or1k_interrupt_disable</code>	
|<code>int irq</code>	
|Disable generation of interrupt at IRQ irq in PICMR	
|none
|-
|<code>or1k_exception_handler_add</code>	
|<code>int vector, void(*function_name)(void*)</code>	
|Install function_name as handler for vector at address (vector*0x100)	
|none
|-
|<code>or1k_mtspr</code>	
|<code>unsigned long int spr, unsigned long int value</code>	
|Write SPR[spr] = value	
|none
|-
|<code>or1k_mfspr</code>	
|<code>unsigned long int spr</code>	
|Read SPR[spr]	
|SPR[spr]
|-
|<code>or1k_report</code>	
|<code>unsigned long int value</code>	
|Simulator report function with l.nop 0x2	
|none
|-
|<code>or1k_icache_enable</code>	
|<code>void</code>	
|Enable instruction cache in SR	
|none
|-
|<code>or1k_icache_disable</code>	
|<code>void</code>	
|Disable instruction cache in SR	
|none
|-
|<code>or1k_icache_flush</code>	
|<code>unsigned long addr</code>	
|Flush addr from instruction cache	
|none
|-
|<code>or1k_dcache_enable</code>	
|<code>void</code>	
|Enable data cache in SR	
|none
|-
|<code>or1k_dcache_disable</code>	
|<code>void</code>	
|Disable data cache in SR	
|none
|-
|<code>or1k_dcache_flush</code>	
|<code>unsigned long addr</code>	
|Flush addr from data cache	
|none
|-
|<code>or1k_immu_enable</code>	
|<code>void</code>	
|Enable instruction MMU in SR	
|none
|-
|<code>or1k_immu_disable</code>	
|<code>void</code>	
|Disable instruction MMU in SR	
|none
|-
|<code>or1k_dmmu_enable</code>	
|<code>void</code>	
|Enable data MMU in SR	
|none
|-
|<code>or1k_dmmu_disable</code>	
|<code>void</code>	
|Disable data MMU in SR	
|none
|-
|<code>or1k_timer_init</code>	
|<code>unsigned int hz</code>	
|Initialise timer to count at hz hertz, reset tick counter, install handler	
|none
|-
|<code>or1k_timer_enable</code>	
|<code>void</code>	
|Start timer, enable timer interrupt in SR	
|none
|-
|<code>or1k_timer_disable</code>	
|<code>void</code>	
|Stop timer interrupts	
|none
|-
|<code>or1k_timer_get_ticks</code>	
|<code>void</code>	
|Read tick counter value	
|tick counter
|-
|<code>or1k_timer_reset_ticks</code>	
|<code>void</code>	
|Reset tick counter value	
|none
|}

Contributions are welcome to help fix and improve this support library.

Feel free to post any suggestions or offers to assist the project to the [http://opencores.org/forum,OpenRISC OpenRISC forum] or the [[OR1K:Community_portal#Mailing_lists | mailing lists]].

=== TODO ===

Functions still missing: interrupt acknowledge/clear function to clear bit in PICSR, cache region flush, MMU map function.

== 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 <code>libboard.a</code> in the <code>/install_path/or32-elf/lib/boards/''boardname''</code> 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.

{| border="1" align="center" style="text-align:center;"
|'''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.

 <code>or32-elf-gcc -mboard=de0_nano</code>

Each <code>libboard.a</code> defines the following symbols:

{| border="1" align="center" style="text-align:center;"
|'''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 <code>libboard.a</code> with the appropriate symbols set to the right values and placing it in the <code>/install_path/or32-elf/lib/boards/''boardname''</code> directory. The ''boardname'' should be the same as the one used when passing the <code>-mboard=''boardname''</code> to the compiler.

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

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

 #include "or1k-asm.h"
 
 /*
  * Define symbols to be used during startup - file is linked at compile time
  *
  */
 .global _board_mem_base
 .global _board_mem_size
 .global _board_clk_freq 
 
 _board_mem_base:	.long	0x0
 _board_mem_size:	.long	0x800000
 
 _board_clk_freq:	.long	66666666 
 
 /* Peripheral information - Set base to 0 if not present*/
 .global _board_uart_base
 .global _board_uart_baud
 .global _board_uart_IRQ
 	
 _board_uart_base:	.long	0x90000000
 _board_uart_baud:	.long	115200
 _board_uart_IRQ:	.long	2
 
 .weak _board_exit
 _board_exit:
         OR1K_DELAYED_NOP(l.j _board_exit)


This file should be assembled and archived, and then placed into the correct install path as mentioned above.