A Long Step by Step Guide - micro-FPGA/riscv-contest-2018 GitHub Wiki

This guide is for Windows (it should be simpler on Linux), it is do it all from scratch type of tutorial.

There are separate wiki pages that describe the tasks in more detail, here is just a step by step list of things to be done.

Step 1: Installation

Step 2: Testing verilator

  • Git: https://github.com/cliffordwolf/picorv32
  • Goto \scripts\csmith folder
  • run verilator there
  • Start MSVC, create project, add verilated files
  • Fix the incremental linking issue
  • Compile to EXE, this is the simulator now!
  • put a file named "test.hex" in VERILOG hex format in the same folder as the EXE file
  • Run the EXE to simulate the picorv32

this verifies that your setup is working and can be used for the "verilator" requirements.

Note: GCC can convert elf files to required format, there is no need for special conversion tools.

Step 3: Setting up RISCV simulator

You may skip this, but it really helps you if you have ISS (instruction set simulator) when you write and test the RISCV application code you need for this contest.

renode

It seems that renode is only free simulator that provides downloadable windows binaries without registration

https://renode.io/

Renode is amazing piece of software, it really is, but it may be easier to use some other ISS or write your own. Saying again - renode is amazing, I was amazed. Out of the box renode runs some MIV RISCV RTOS, it may also run zephyr compiled for MIV M2GL025 as target.

ovpSIM

Probably the best option. Free after registration on the FORUM pending admin approval, you need to use corporate e-mail, google is banned, need to use WIKI style formatted user-name, takes more than 24 hours to get approved..

http://www.ovpworld.org/dlp/

engine-V-simulator

You can play around with engine-V-simulator: open source, github, License Apache 2.0, windows executable provided, full source is included, should be fairly easy to recompile with Delphi Community Edition

Note: this simulator is only as good as to comply with the rules for this contest.

Compile simulator from sources

You can try to compile some opensource simulator with mingw-cygwin-msvc or install linux in VM and use linux versions (this is fastest option of course)

Write your own simulator

By doing so you may get extra points, if you do it as jupyter notebook many would be happy.

Step 4: Compiling the RV32I Compliance files

  • goto \riscv-compliance\riscv-test-suite\rv32i
  • make sure you have make working OR setup simple COMPILE.BAT
  • goto \riscv-compliance\riscv-test-env
  • create a new folder
  • copy from "p" folder all files
  • fix linker script
  • fix riscv_test.h
  • goto \riscv-compliance\riscv-target
  • create new folder
  • copy some files to here
  • do something with them
  • goto \riscv-compliance\riscv-test-suite\rv32i
  • type make or start your COMPILE.BAT

You should get now 55 binaries for the compliance test!

Step 5: Compiling Dhrystone

Details there https://github.com/micro-FPGA/riscv-contest-2018/wiki/Dhrystone

You probably do not need to deliver Dhrystone at all if you are targeting only the smallest design category.

For the fastest category you need to optimize the Dhrystone to take out the maximum performance. Dhrystone should be recompiled with real clock frequencies your SoftCPU is running on target boards at the end, otherwise the Dhrystone numbers would be meaningless.

Step 5: Compiling Zephyr

  • goto \zephyr\drivers\serial
  • copy/create Kconfig.yourcpu and uart_yourcpu.c files
  • do something with them
  • add your driver to CMakeLists.txt and Kconfig
  • goto \zephyr\arch\riscv32\soc\riscv-privilege
  • create yoursoc folder
  • copy some files there
  • do something with them
  • goto \zephyr\boards\riscv32
  • create yourboard folder copy some file there
  • do something with them
  • goto samples\hello_world
  • setup some env variables
  • type cmake -Gninja
  • type ninja menuconfig
  • select your soc, uart driver, disable PLIC and some more stuff
  • type ninja
  • get the binary from \build\zephyr

You may have to twiddle a little to get the ninja working

Details here: https://github.com/micro-FPGA/riscv-contest-2018/wiki/Zephyr

Step 6: Compiling Bootloader(s)

Skip this step if you plan to use bootable XiP (linear SPI Flash IP needed) for both Microsemi and Lattice.

TODO

Step 7: Simulation of the SoftCPU - CPU Core

You should not start writing the SoftCPU code before your simulation environment is setup.

Note: if you are not sure that the code you write is synthesize-able you should setup FPGA synthesis at this step and run sanity synthesis to check that your does synthesize.

If you write your code in verilog, you should also setup verilator testbench at this step. You can also use verilator as your simulator, but using a RTL simulator is most likely more productive.

Any RTL simulator can be used, it is perfectly OK to use Vivado built in simulator as example. You are not required to deliver any RTL simulation scripts or anything as deliverable for the contest entry.

Step 8: Porting to the target FPGA's

As long as your verilog code can be synthesized and is tested either with RTL simulator or verilator it should compile for the FPGA as well.

Step 9: Initial testing on target Boards

You can test on target board as soon as your CPU Core does execute some instructions correctly you do not even need to build the full SoC first. Just connect a LED to some CPU Program Counter bit and implement LED on/off by forever loop at different addresses. To test with this LED you only need a a few instructions to work.

Note: while it may be fun to test on real target boards, it is time consuming so most work should be done in RTL simulator. But you can set up the pass/fail LED at early stage to see some actual progress on your work.

Step 10: Creating the SoC Peripherals

Peripherals are not needed as long as you only work with verilator, they can be implemented in simulation only verilog in the testbench files. For the SoC to work on the real boards you need:

UART

Transmit only UART is sufficient if you plan to use XiP from SPI or eNVM otherwise you need UART with transmit and receive functionality. This UART can be half duplex and you can implement it using bit banged GPIO, in this case the you only need a GPIO with one bit, this UART does not need to have interrupt support.

Machine Timer

Described in privileged specification, 64 bit memory mapped time register and compare register are needed, on compare match machine timer exception is fired. This machine timer is supported by Zephyr.

Step 11: SoftCPU Optimization (speed or size)

This is where the majority of your work is.

Step 12: Prove of RV32I Compliance

Compliance test with verilator

Verilog testbench for your SoC should be modified to "pull out" the signatures from RAM after the execution of the tests. Those signatures should be written to file. If the format you write from verilator does not match the format the of the reference output, you need to provide some conversion tools (could be python script).

Test cases compiled for engine-V prepend 16 bytes of 0xBB and append 16 bytes of 0xEE to the signatures in RAM. This makes it simple to find the location of the signatures (this is different for each test case!). Other methods can be used as well.

All 55 signatures have to match the reference output, some script should be included that compares the signatures to the reference.

Compliance test on target board

For absolute clean compliance test signature check should be used on target board as well, this involves reading out the data RAM after tests by some means. This can be done by piece of assembly code compiled into the test binaries to dump the signatures to UART.

You may optionally implement compliance testing using the IO_ASSERT macros, to indicate the pass fail status on LED and/or UART console. This should also be acceptable (but riscv compliance testing github documentation does not describe this method as valid one at the moment).

Step 13: Dhrystone SCORE Result

Dhrystone binaries should be compiled after you have determined the maximum operating clock speed of your SoftCPU on both platforms. This should be used as HZ value during compilation of final Dhrystone code.

If it is clear from the provided code that verilator model is cycle accurate to your FPGA implementation it may be acceptable that Dhrystone is run with verilator. To be very clean it is better to provide Dhrystone results from real execution on target boards not only from verilator.

Step 14: Final verilator testbench

You should provide simulation models for:

  • instantiated Math Blocks
  • instantiated RAM Blocks
  • PLL
  • eNVM and eSRAM for Microsemi if you use them
  • any other instantiated hard IP blocks
  • external SPI Flash if you use it
  • receive only UART if you use bitbang GPIO based UART in your SoC

If you use Cortex-M3 assisted boot option then it should be acceptable to wire the HPS FIC ports to constant in the testbench and just preload the Microsemi fabric rams with verilog readmem.

Using readmem directly to load the RAMs without using your SoC UART bootloader (if you use one) in verilator should also be acceptable.

Output from SoC UART should however appear as verilator printout.

Step 15-:

TODO

Step 98: Preparing the files to deliver as contest entry

TODO

Step 99: Sending email

Email to [email protected] should be sent no later than 11:59 PST on Nov. 26, 2018.

This email should only contain links to github repositories, so you should not attach any files to that email, all has to be pushed to github at the time you send the email. It is expected that repositories you list will be fetched and used by the judges.