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
|
|