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