add benchmarks gitignore
[riscv-tests.git] / benchmarks / readme.txt
1 *************************************************************************
2 Benchmarks for RISCV Processor
3 -------------------------------------------------------------------------
4
5 The benchmarks make use of the RISCV C compiler toolchain. You will need
6 to include a bmark.mk makefile fragment in each benchmark directory. The
7 fragment should include the object files and a rule to actually link
8 these object files into an executable. There are a couple important
9 points to make about the toolchain.
10
11 + The toolchain sets the stack pointer to memory address 0x20000 so your
12 main memory _must_ be larger than 0x20000 bytes or else the stack will
13 get wrapped around and overwrite program data.
14
15 + The stack grows down from 0x20000 and your program is loaded at 0x1000.
16 If you have a very large program and have lots of very big arrays
17 declared on the stack your stack could overwrite your program. Be aware.
18
19 + You cannot use standard clib functions (like memcopy or strcat). You
20 cannot use system calls and thus cannot use printf.
21
22 + You cannot access the simulated command line - ie you cannot use argc
23 and argv within main.
24
25 + You may have to increase the timeout check in your test harness to
26 allow longer programs to run (you can do this from the command line
27 option +max-cycles with the standard test harness)
28
29 + The compiler loads the program at 0x1000. It does not insert exception
30 setup code. So if you are careful with what C you use it will only
31 generate code in the riscv lab1 subset. If you use multiplies, shorts,
32 and chars it could generate mul, lh, and lb instructions. Be aware.
33
34 + You can write assembly in C - you need to do this to write tohost to 1
35 to indicate when the benchmark is done. Look at the example
36 benchmarks to see how this is done. You can find more information
37 about how to write assembly in C here:
38 http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html
39
40 + If you look at the example benchmarks you will see that I have two
41 important macros HOST_DEBUG and VERIFY. Use HOST_DEBUG to compile the
42 benchmark on your host workstation (ie use standard gcc on Athena/Linux
43 box) and then debug the benchmark. Since you are using standard gcc you
44 can use printf's to make sure that your benchmark actually works before
45 trying it out on your RISCV processor.
46
47 + Debugging C compiled code on the RISCV processor is a real pain. It is
48 hard to associate the assembly with the C code and there is no
49 debugger. So if you encounter a bug in your processor when running a C
50 benchmark you can try to debug it, but you might have better luck
51 adding more assembly tests to your test suite.
52
53 + To avoid having the compiler try and use a global pointer (ie using
54 register 28 to point to a space where small global variables are
55 stored) you need to use the -G 0 command line option.