OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [orpsocv2/] [sw/] [README] - Diff between revs 349 and 396

Go to most recent revision | Show entire file | Details | Blame | View Log

Rev 349 Rev 396
Line 1... Line 1...
                                Project software
                                Project software
                                ================
                                ================
 
 
The paths here contain a set of software that is for use on an OR1200 processor
This directory contains software that is intended to be compiled and run on
in conjunction with  memory mapped peripherals. The exception is the utils/ path
ORPSoC, and utilities to help format software images.
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,
apps
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
Standalone programs and utilities designed to run on ORPSoC. Usually these
of general utility and driver functions, that each software test can use.
should be run on a FPGA/ASIC ORPSoC target.
 
 
The following is a description of each path's contents:
board
 
 
support/:
This path mainly contains information about the board, in the board.h header
 
found in the board/include path. Typically each board port of ORPSoC will have
 
their own board/include/board.h file to indicate the board's specific
 
configuration.
 
 
Generic support software functions, and drivers for various hardware modules
bootrom
 
 
include/:
This is some assembly which is compiled and converted into Verilog, and then
 
synthesized into a Wishbone ROM module that the processor uses to boot. It is
 
not really software to run on ORPSoC, rather it is software that ends up
 
embedded in ORPSoC. See the README in bootrom for more information.
 
 
The software include files (headers) path
drivers
 
 
utils/:
Each module requiring a driver will have its own path under this directory. In
 
the case of a CPU (currently only OR1200), it will also contain all the
 
necessary files to support creating of standalone executables (C runtime file,
 
linker script, etc.) Under each specific driver's path should be an include/
 
path which contains headers allowing use of the drivers. When using drivers
 
in a board port that are modified versions of those included in the base sw
 
path, the board port's driver will be used over the one in the root sw path.
 
 
Tools to help format the software images - compiled and run on host
lib
 
 
spiflash/:
Generic library softwares, and location of compiled liborpsoc.a library.
 
 
Application, allowing programming of flash memory attached by SPI bus
Makefile.inc
 
 
eth/:
Main Makefile fragment included by all other makefiles when building things. The
 
author is not the best at GNU make, so if anything is done a silly way, please
 
feel free to fix it and commit this back. The better this file is, the easier
 
this convoluted software setup will be to use.
 
 
Tests for ethernet MAC functionality, for simulation and target
README
 
 
flashrom/:
This README.
 
 
Test for Actel devices' UFR
tests
 
 
or1200/:
This path contains software intended to test particular modules of ORPSoC. Each
 
is separated into tests intended to be run in simulation (sim/) and on a "board"
 
or physical ORPSoC target.
 
 
Tests for OR1200 in C, for simulation
utils
 
 
or1200asm/:
A path containing utilities, built for the host system, which will help in the
 
generation of the programming files.
 
 
Tests for OR1200 in assembly, for simulation
 
 
 
sdram/:
                                liborpsoc
 
 
Tests for SDRAM controller, simulation and target
All of the drivers, and generic library functions are compiled into a library
 
called liborpsoc.a which ends up in sw/lib. This is linked against by all
 
test software and standalone applications included here. This alleviates any
 
need for the toolchain to contain a C library, although limits the capabilities
 
of the library, however if anything special functions are needed, it's easy
 
enough to add them to the existing functions in lib/lib-utils.c.
 
 
spi/:
                                Building
 
 
Tests for SPI controller core, simulation
The simulation makefiles should take care of this, but to test building
 
liborpsoc.a change into sw/lib and run "make liborpsoc.a".
 
To test building an executable, go into one of the test directories and run
 
"make test-name.elf" where "test-name" is the name of a valid test file.
 
 
uart/:
                                Cleaning
 
 
Tests for 16550 UART, simulation and target
To clean the software, run "make clean-all" in sw/lib.
 
 
Files to take note of
 
 
 
include/board.h:
 
 
 
This file contains overall 'board' settings for the software. Namely, core
Author: Julius Baxter, julius@opencores.org
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
 
Author: Julius Baxter, julius@opencores.org
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.