Subversion Repositories openrisc_2011-10-31

                                Project software

                                ================

The paths here contain a set of software that is for use on an OR1200 processor

in conjunction with  memory mapped peripherals. The exception is the utils/ path

which contins tools to run on the host system to help create different formats

of the software images.

The applications are designed to run "bare metal", ie without an underlying OS,

and provide little functionality other than testing the modules, or providing

diagnostic functionality on target.

The OR1200 software is setup so that there is a support library, providing a set

of general utility and driver functions, that each software test can use.

The following is a description of each path's contents:

support/:

Generic support software functions, and drivers for various hardware modules

include/:

The software include files (headers) path

utils/:

Tools to help format the software images - compiled and run on host

spiflash/:

Application, allowing programming of flash memory attached by SPI bus

eth/:

Tests for ethernet MAC functionality, for simulation and target

flashrom/:

Test for Actel devices' UFR

or1200/:

Tests for OR1200 in C, for simulation

or1200asm/:

Tests for OR1200 in assembly, for simulation

sdram/:

Tests for SDRAM controller, simulation and target

spi/:

Tests for SPI controller core, simulation

uart/:

Tests for 16550 UART, simulation and target

Files to take note of

include/board.h:

This file contains overall 'board' settings for the software. Namely, core

frequency (primarily for UART divisor calculation), cache size definition,

bootloader program selection, and module memory mappings. Be sure to clean the

project and rebuild it after modifying this file before changes will take

effect.

include/design_defines.h:

This file is automatically generated from rtl/verilog/include/design_defines.v

and contains all the same defines as the verilog file. This file is not updated

automatically whenever rtl/verilog/include/design_defines.v changes, the

software library must be cleaned and rebuilt for changes to take effect.

Adding drivers:

Driver code should be added into support/ and the Makefile under support/ should

have its SUPPORT_MODULES variable updated to include the name of the new driver

to ensure it is compiled into the library. An appropriate header should be

placed under the include/ path, as per the others. Be sure to clean and rebuild

the software before using the new driver.

For example, to add a CAN protocol controller module driver, it's best to first

decide on a unique name for  the CAN module, ie. if from OpenCores call it the

can-oc driver. Naming the driver uniquely helps if alternate controller modules

for the same protocol are implemented in the future - the RTL for these modules

is uniquely identified, so it helps to uniquely identify the driver, too. Place

the driver source in support/can-oc.c and the header in include/can-oc.h, and

add can-oc to the SUPPORT_MODULES variable in support/Makefile. Whenever the

support libary is compiled, this will then be compiled and included in the

support lib.

Adding tests:

The format of names and tests for the software, if adhered to, will be picked up

automatically by simulation scripts, meaning adding software to test modules

is very easy. Simply create a path with the name of the module

For example for a CAN controller, create a new path called can/ under sw/ and

name any software test source under sw/can in the format can-testname.c . When

running simulation, the test can-testname can be added to the list of tests

to run and the software will automatically be compiled and loaded appropriately.

Writing a program to test a module:

The support library includes basic reset code, to initialise the processor and

its caches and then jump to the user application. Inspecting any other test

program should give a good idea of how the program should be structured. In

short, there should be a main() function, and the test software should make use

of the simulation control mechanisms, which will now be explained.

   Software test mechanisms:

   These are a set of special functions that invoke specific instructions that

   signal things to the processor monitor during RTL simulation only. These do

   not work in gatelevel simulation. They are accessed via functions in the

   support library, but are essentially inserting an Or1k NOP instruction with

   an immediate value that does not effect the processor, but is interpreted by

   the processor monitor to perform these tasks.

   report(value);

        This function will output the value passed to it in a file, in the out/

        path under the simulation directory, called testname-general.log

   exit(value);

        This function will output "value" in a similar fashion to report()

        however this will also signal the processor monitor in the Verilog

        testbench to end the simulation

Using these mechanisms, the software can signal progress and exit statuses for

analysis afterwards. Each test, if successful, should call exit with the value

0x8000000d - a test script will check for this value, and if it does not find

it in out/testname-general.log then it assumes there wasn error and will stop

the test simulation loop.

The report() function is very useful for indicating value of variables

throughout the simulation.

printf():

The simulation support library contains a simple version of printf() which is

an extremely handy for displaying information during run-time. To use printf()

and output via uart be sure to #include "uart.h" before #include "printf.h" and

to call uart_init(DEFAULT_UART) to initalise the UART before printf()'ing.

printf() is a computationally expensive function, and UART communication is a

very slow communcation medium at the best of times, let alone during RTL sim.

With this in mind, printf() should be used sparingly during simulation. However

there is also a method of using printf() which does not use the UART, but can

print via the special OR1k NOP instruction mechnisms mentioned above. If wishing

to use printf() without the penalty of the UART (writing out only, reading from

verilog simulator console does not yet work) then only #include "printf.h" and

not "uart.h" - during simulation the printf()'ing will still work, however the

same code will then not work on target. This significantly speeds up the time

taken to printf() something during simulation.

Building and cleaning the software:

Building can be done simply by going into any of the paths with code intended

for use on the Or1k processor, and build the .elf of any source file, eg. in

the gpio/ path do

$ make gpio-board.elf

This will build the support library, if it hasn't been, and then the gpio-board

application will be compiled.

To see the disassembly of the gpio-board application, run

$ make gpio-board.dis

and then inspect the file gpio-board.dis which is the output of the objdump

program from the binutils suite.

Cleaning:

To clean the entire software suite, change into any of the test application

paths and run:

$ make clean-all

Scripts for simulation and synthesis automatically build all the software as

required by the simulation. Cleaning of the software can also be done by running

$ make clean-sw

from any simulation or synthesis run/ path.

Author: Julius Baxter, julius.baxter@orsoc.se