Browse Source

Brushup for publication ...

master
kaqu 10 months ago
parent
commit
e9213e9637
  1. 3
      .vscode/launch.json
  2. 77
      README.md
  3. BIN
      Risq5_Overview.png
  4. BIN
      debugger/Debugger_GUI.png
  5. 10
      debugger/README.md
  6. BIN
      impress/InstructionDecoder.png
  7. 34
      libmodules/README.md
  8. 0
      risq5.py
  9. 12
      software/README.md

3
.vscode/launch.json

@ -20,7 +20,8 @@
"--csr-csv=build/csr.csv", // Only this one for remotetest.py!
"--doc", // Generate documentation files for sphinx
//"--with-bios-for-none" // Provide ROM & BIOS even w/o CPU (+10 minutes!)
"--isa-extension-m" // Provide RISC-V 'M' instruction set extension
"--isa-extension-m", // Provide RISC-V 'M' instruction set extension
"--isa-extension-f" // Provide RISC-V 'F' instruction set extension
],
//"args": ["--build"],
//"pythonArgs": ["--build", "--uart-name=crossover"],

77
README.md

@ -0,0 +1,77 @@
![Showtime](Risq5_Overview.png)
# Risq5 - one more clone to go ... #
This project demonstrates the use of LiteX & migen to create a full blown RISC-V CPU. The project requires a colorlight-5a-75b board (sells at ~18€ as of 10/2020).
(Hint: project has been tested on Linux Mint 20 only, but should run on other Linux versions as well ...)
## Installation ##
### 1. Software ###
To use this project effectively, you will have to install LiteX, see https://github.com/enjoy-digital/litex for details (and project Trellis, NextPNR & YoSys requirements).
Also, it is recommended to install the board support, see https://github.com/litex-hub/litex-boards,
as well as the the RISC-V tool chain (see https://github.com/sifive/freedom-tools/releases).
To communicate with your board via network, install the wishbone tools, see https://github.com/litex-hub/wishbone-utils.
To use the automatic documentation feature, you will have to install sphinx, see https://www.sphinx-doc.org/en/master. Also its wavedrom extension has to be installed, see https://pypi.org/project/wavedrom.
Some helpful links for RST docstring formats:
http://daouzli.com/blog/docstring.html &
https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
The project assumes a local 'fpga' path within the home directory of the user, where all the above mentioned software packages are installed.
Furthermore, the project assumes a virtual environment named 'fpga' where all project relevant python libs are registered (this is not strictly necessary ... maybe software/ramcreate.sh has to be adjusted, as well as the python interpreter settings within VSC!).
The actual 'Risq5' project may be installed anywhere, but local paths will have to be adjusted (firmware/main.c, software/ramcreate.sh ... worx for me ;).
### 2. Hardware ###
A JTAG programmer will be required for successful device programming. Thanx to Wolfgang, I'm using the Versaloon (s/w for blue-pill STM32), see https://github.com/zoobab/versaloon. To use this device, you also will have to install openocd via 'apt install openocd'. See https://git.hacknology.de/wolfgang/colorlight#user-content-class-hub75sender for details, on how to connect the JTAG adapter.
For board specific details see
https://github.com/enjoy-digital/colorlite/blob/master.
Other helpful links to board data:
https://github.com/q3k/chubby75/blob/master/5a-75b/hardware_V7.0.md
https://saturn.ffzg.hr/rot13/index.cgi?colorlight_5a_75b
https://github.com/trabucayre/litexOnColorlightLab004/
https://blog.pcbxprt.com/index.php/2020/07/19/running-risc-v-core-on-small-fpga-board/
## Program structure: ##
1. risq5.py - this is the main FPGA building source
2. libmodules subdir - all RISC-V sources, DRAM DMA loader helper & system time support
3. helpers subdir - contains python helpers for load & flash etc.
4. debugger - contains the sources for the Risq5 'visual debugger'
5. firmware subdir - contains some modified BIOS files (& the originals), not used currently
6. software subdir - contains a separate build, load & flash logic for RV32IMF application code
7. litex subdir - contains modified LiteX sources (& originals)
8. impress subdir - impress graphics to improve understanding
(the rest currently is of minor importance ...)
## Quickstart ##
After installation of the relevant toolchains:
1. Open the project in VSC (or use your favourite IDE & maybe adjust some settings ;), adjust local paths if nec. ...
2. Connect your JTAG adapter as described in Wolfgang's documentation @ https://git.hacknology.de/wolfgang/colorlight
3. Run risq5.py with these options (you may omit the --doc option if there is no Sphinx installed):
--build --load --revision=7.0 --uart-name=crossover --with-etherbone --ip-address=192.168.1.20 --csr-csv=build/csr.csv --isa-extension-m --isa-extension-f --doc
to create & load the project to on-board SRAM via the USB/JTAG-Adapter (this takes it's time ...)
## Test assembly code ##
1. This time, open up a terminal & cd to the project local 'software' subdirectory
2. You can load an application to absolute location 0x40190000 (you may have to adjust local paths!):
./testloader.sh flwstw
3. Run the debugger: risq5dbg.py with the same options as above (for risq5.py)
4. You're now able to verify correct operations of the cpu (well, hopefully 😎!)
## Some - maybe helpful - references for implementing IEEE 754 FPU logic: ##
- [IEEE 754 simulator](https://www.h-schmidt.net/FloatConverter/IEEE754.html)
- [IEEE 754 format usage](https://www.pitt.edu/~juy9/142/slides/L3-FP_Representation.pdf)
- [same as above](https://cs.boisestate.edu/~alark/cs354/lectures/ieee754.pdf)
- [same, same ...](https://steve.hollasch.net/cgindex/coding/ieeefloat.html)
- [IEEE 754 tutorial (w/ shitty bitmap graphics 💀 ...)](https://www.rfwireless-world.com/Tutorials/floating-point-tutorial.html)
- [Floating point adders & multipliers](http://users.encs.concordia.ca/~asim/COEN_6501/Lecture_Notes/L4_Slides.pdf)
- [Floating point multiply & divide](https://wiki.eecs.yorku.ca/course_archive/2017-18/F/2021E/_media/chapter_3_add_mul.pdf)
- [Floating point division (video)](https://www.youtube.com/watch?v=fi8A4zz1d-s)
- [Methods of computing square roots](https://en.wikipedia.org/wiki/Methods_of_computing_square_roots)
- [Bit-shifting tricks for integer multiply & divide](https://bisqwit.iki.fi/story/howto/bitmath/#DivAndModDivisionAndModulo)

BIN
Risq5_Overview.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 499 KiB

BIN
debugger/Debugger_GUI.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 355 KiB

10
debugger/README.md

@ -0,0 +1,10 @@
# DEBUGGER #
The visual debugger consists of 3 files
- risq5dbg.py - starter
- qt5dbg.py - Qt5 based GUI
- dbgeval.py - opcode decoding
![Showtime](Debugger_GUI.png)

BIN
impress/InstructionDecoder.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 226 KiB

34
libmodules/README.md

@ -0,0 +1,34 @@
# LIBMODULES #
## File contents: ##
__dramtransfer.py__ - contains main helpers for DRAM access.
__fpu_decode.py__ - contains the FPU instruction decoder for most 'F' extension opcodes.
A note on the square root logic: I have implemented a variant of Goldschmidt's
algorithm which allows for up to ⚠ 3.5% error, but there is simply no replacement for speed!
If you need more accuracy, you will have to implement Newton-Raphson in s/w or perhaps
doubles w/ external lib. calls. Example:
// Newton-Raphson approximation (6 digits after decimal ok)
#define MAXITERATION 128
#define ACCURRACY 1E-16
float f = <value>; // Whatever you wanna calc.!
float approx = 0.5 * f; // 1st approximation
float betterapprox;
for(int i=0;i < MAXITERATION;i++) {
betterapprox = 0.5 * (approx + f/approx);
if(f_abs(betterapprox - approx) < ACCURRACY)
break;
approx = betterapprox;
}
__instruction_decode.py__ - contains the main instruction decoder für base 'I', multiply/divide 'M' & a few 'F' extension opcodes.
__register_file.py__ - contains the register file implementation, opcode dissection & some combinatorial adressing logic.
__risq5defs.py__ - contains the definitions for the nec. control & status registers (CSRs) as well as some exception codes.
__systime.py__ - contains a memory mapped clock as required according to RISC-V spec.

0
risq5_imf.py → risq5.py

12
software/README.md

@ -2,14 +2,18 @@
This directory contains the actual application & the loading/flashing tools.
1. ramcreate.sh - Create & load a startable binary to either RAM bank 1 or 2 (will be lost on power cycles ...)
1. testloader.sh - Create & load a binary to fixed address @40190000h
usage: ./testloader.sh <source>
-------------------- NOT USED CURRENTLY !!!! -----------------------------------------------------------
2. ramcreate.sh - Create & load a startable binary to either RAM bank 1 or 2 (will be lost on power cycles ...)
usage: ./ramcreate.sh <<main_app_w/o_extension>> <<additional_lib_w/o_extension>> <<ram_bank_no>>
example: ./ramcreate.sh main illumination 1
2. flashcreate.sh - Create & flash an application image (for permanent action across power losses)
3. flashcreate.sh - Create & flash an application image (for permanent action across power losses)
usage: ./flashcreate.sh
3. flashclearapp.sh - Make flash app invalid, thus booting faster & then RAM boot dev. (pure convenience ...)
4. flashclearapp.sh - Make flash app invalid, thus booting faster & then RAM boot dev. (pure convenience ...)
usage: ./flashclearapp.sh

Loading…
Cancel
Save