URL
https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk
Subversion Repositories openrisc_2011-10-31
[/] [openrisc/] [trunk/] [orpsocv2/] [sw/] [README] - Rev 362
Go to most recent revision | Compare with Previous | Blame | View Log
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
Go to most recent revision | Compare with Previous | Blame | View Log