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

Subversion Repositories openrisc

Compare Revisions

  • This comparison shows the changes necessary to convert path 
    /openrisc
    from Rev 395 to Rev 396
    ↔ Reverse comparison
  •

Rev 395 → Rev 396

/trunk/orpsocv2/sw/README
1,193 → 1,85
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.
This directory contains software that is intended to be compiled and run on
ORPSoC, and utilities to help format 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.
apps
 
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.
Standalone programs and utilities designed to run on ORPSoC. Usually these
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
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
/trunk/orpsocv2/sw/drivers/or1200/Makefile
0,0 → 1,9
SW_ROOT=../..
 
# Sources to go into the liborpsoc.a support library
COMPILE_SRCS=exceptions.c int.c or1200-mmu.S or1200-utils.c
 
include $(SW_ROOT)/Makefile.inc
 
clean:
$(Q)rm -f *.a *.o

powered by: WebSVN 2.1.0

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