			      Or1ksim Test Suite
			      ==================

This is the Or1ksim test suite, which is now integrated with the main Or1ksim
development package. It operates using a standard DejaGNU framework within the
GNU autoconf/automake/libtool structure.

A separate configuration file is needed for the OpenRISC programs used in
testing, since these use the OR1K tool chain, rather than the host tool
chain. This can be found in the "test-code-or1k" directory.

Tests are provided for the standalone simulator (or1ksim) and for the library
(libsim.a).

At the time of writing a total of 2,447 tests compile, run and pass. That
figure is broken down into 2,185 tests of the standalone simulator and 262
tests of the library

Configuration and make files are provided for further test programs. These
come in three categories.
- Tests which compile correctly, but will not run to completion.
- Tests which compile, but will not run at all.
- Tests which will not compile correctly.

File Organization
=================

Each test program has its own directory under test-code (for native tests,
typically of the library) or test-code-or1k (for OpenRISC code, which must use
the OpenRISC tool chain). This builds the test program. If necessary it copies
data files to the main build/testsuite directory.

Each test then has a DejaGNU expect script in or1ksim.tests (for standalone
tests) and libsim.tests (for library tests), which loads and runs the
test. Support script procedures are in lib/or1ksim.exp and lib/libsim.exp.

Libraries
=========

Within the test-code there are several libraries:

support:    A minimal C library.
except:     Exception handling and startup code.
mc-common:  A library to support the memory controller tests.

Working tests
=============

Tests of standalone Or1ksim:

basic:             8 tests of a wide range of instructions and registers.
cache:            11 tests of the Or1ksim cache modeling
cbasic:           19 tests of minimal C functionality
cfg:              12 tests of the OR1K configuration register
dhry:              1 Dhrystone 2.1 benchmark using Or1ksim's timing facility.
dmatest:           3 tests of DMA.
eth:              12 tests of the Ethernet interface.
except-test:       7 tests of OR1K exception handling
exit:              1 test that C program exits correctly
ext:             104 tests of the sign extension (l.ext) instructions.
fbtest:            1 test of the frame buffer.
flag:              1 test of Supervision Register (SR) flag bits.
fp               337 tests of floating point functionality (Feature 413).
functest:         11 tests of the C function calling interface.
inst-set-test:       A collection of tests of individual instructions
  is-add-test    213 tests of the l.add* instructions (Bugs 1771, 1776)
  is-and-test     80 tests of the l.and* instructions (Bugs 1782-1784)
  is-div-test:   101 tests of the l.div and l.divu instructions (Bug 1770).
  is-find-test:   14 tests of the l.ff1 and l.fl1 instructions (Bug 1772).
  is-jump-test:   27 tests of the jump instructions (Bug 1775).
  is-lws-test:    13 tests of the l.lws instruction (Bug 1767).
  is-mac-test:   189 tests of the MAC instructions (Bugs 1773, 1777).
  is-mul-test:   186 tests of the l.mul* instructions (Bug 1774).
  is-or-test      80 tests of the l.or* instructions (Bugs 1782-1784)
  is-ror-test:    36 tests of the l.ror and l.rori instructions (Bug 1778).
  is-shift-test: 344 tests of the shift instructions (Bug 1782-1784).
  is-spr-test:    28 tests of the l.mfspr and l.mtspr instructions (Bug 1779).
  is-sub-test     58 tests of the l.sub instruction (Bugs 1782-1784)
  is-xor-test     80 tests of the l.xor* instructions (Bugs 1782-1784)
int-test:         88 tests of the programmable interrupt controller.
kbdtest:          26 tests of the PS2 keyboard interface.
local-global:      1 test of C local and global variables.
mem-test:         16 tests of simple memory access.
mmu:              12 tests of the MMU.
mul:               5 tests of the multiply functionality.
mycompress:        1 test using a compression program.
testfloat         40 tests of detailed floating point behavior
tick:             19 tests of the OR1K tick timer.
pcu:		  27 tests of the OR1K performance counters unit.

Tests of the libsim library:

int-edge:               6 tests of edge triggered interrupts.
int-level:              3 tests of level triggered interrupts. 
lib-iftest:             1 test  of the basic library interface functions.
jtag-basic:            17 tests of JTAG reset and instruction selection
jtag-go-command-read:  60 tests of JTAG GO_COMMAND for reading
jtag-go-command-write: 54 tests of JTAG GO_COMMAND for writing
jtag-read-command:     18 tests of JTAG READ_COMMAND
jtag-read-control:      8 tests of JTAG READ_CONTROL
jtag-select-module:    20 tests of JTAG module selection
jtag-write-command:    58 tests of JTAG WRITE_COMMAND
jtag-write-control:    13 tests of JTAG WRITE_CONTROL
upcalls:                2 tests of the upcall interface.

Tests which build, but do not run to completion
===============================================

The following tests of standalone Or1ksim rely on VAPI in Or1ksim, so need a
client to provide test data over TCP/IP.

acv-gpio:  a test of the GPIO.
acv-uart:  a test of the UART

Tests which build, but do not run at all
========================================

These tests of standalone Or1ksim (which are built by the make file), do not
appear to run at all. The problem is in the linker script and/or the
configuration for Or1ksim.

mc-async:  a test of the memory controller with asynchronous memory.
mc-dram:   a test of the memory controller with DRAM.
mc-ssram:  a test of the memory controller with SSRAM.
mc-sync:   a test of the memory controller with synchronous memory.
uOS:       a microKernel.

Tests which do not build
========================

The following test of standalone Or1ksim builds with a myriad of warnings.

inst-set-test:  a comprehensive test of the instruction set using C.


Updated by Jeremy Bennett (jeremy@jeremybennett.com)
Updated by Julius Baxter (julius@opencores.org)
6 June 2011
