riscv-tests/benchmarks

*************************************************************************
Benchmarks for RISCV Processor
-------------------------------------------------------------------------

The benchmarks make use of the RISCV C compiler toolchain. You will need
to include a bmark.mk makefile fragment in each benchmark directory. The
fragment should include the object files and a rule to actually link
these object files into an executable. There are a couple important
points to make about the toolchain.

+ The toolchain sets the stack pointer to memory address 0x20000 so your
main memory _must_ be larger than 0x20000 bytes or else the stack will
get wrapped around and overwrite program data.

+ The stack grows down from 0x20000 and your program is loaded at 0x1000.
If you have a very large program and have lots of very big arrays
declared on the stack your stack could overwrite your program. Be aware.

+ You cannot use standard clib functions (like memcopy or strcat). You
cannot use system calls and thus cannot use printf.

+ You cannot access the simulated command line - ie you cannot use argc
and argv within main.

+ You may have to increase the timeout check in your test harness to
allow longer programs to run (you can do this from the command line
option +max-cycles with the standard test harness)

+ The compiler loads the program at 0x1000. It does not insert exception
setup code. So if you are careful with what C you use it will only
generate code in the riscv lab1 subset. If you use multiplies, shorts,
and chars it could generate mul, lh, and lb instructions. Be aware.

+ You can write assembly in C - you need to do this to write tohost to 1
to indicate when the benchmark is done. Look at the example
benchmarks to see how this is done. You can find more information
about how to write assembly in C here:
http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html

+ If you look at the example benchmarks you will see that I have two
important macros HOST_DEBUG and VERIFY. Use HOST_DEBUG to compile the
benchmark on your host workstation (ie use standard gcc on Athena/Linux
box) and then debug the benchmark. Since you are using standard gcc you
can use printf's to make sure that your benchmark actually works before
trying it out on your RISCV processor.

+ Debugging C compiled code on the RISCV processor is a real pain. It is
hard to associate the assembly with the C code and there is no
debugger. So if you encounter a bug in your processor when running a C
benchmark you can try to debug it, but you might have better luck
adding more assembly tests to your test suite.

+ To avoid having the compiler try and use a global pointer (ie using
register 28 to point to a space where small global variables are
stored) you need to use the -G 0 command line option.