Skip to content

Commit 535d294

Browse files
matiasilvamatiasilva
committed
Rework README
1 parent dc3badb commit 535d294

File tree

5 files changed

+140
-95
lines changed

5 files changed

+140
-95
lines changed

‎README.md

+12-94
Original file line numberDiff line numberDiff line change
@@ -2,106 +2,24 @@
22

33
This repository contains the source code for my Minimal RISC-V SoC.
44

5-
## Author
6-
7-
Matias Wang Silva, 2024/2025
8-
9-
## License
10-
11-
MIT
12-
13-
## Naming conventions
14-
15-
The code follows the [lowRISC coding style](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md) for Verilog for the most part. I wrote this myself in my free time so there will be deviations for no real reason.
16-
17-
- signals use snake case
18-
- note: logical word units are joined without underscore
19-
- eg: memwrite expands to memory write (one action)
20-
- eg: mem_to_reg expands to memory to register (no joining)
21-
- parameters use ALL CAPS
22-
- task names, module names are all snake case
23-
- common abbreviations are used where possible (reg for register, mem for memory, ctrl for control, etc)
5+
To view the datasheet and full documentation set associated with this project,
6+
[click here](https://matiasilva.github.io/riscv-soc).
247

258
## Development
269

27-
While there is a great open source toolset for the iCESugar v1.5, it remains difficult to navigate the web of broken links to find what is really needed to get Verilog synthesized and 'running on' the FPGA. After lots of searching and reading tutorials, I've condensed it to this:
28-
29-
- `yosys` for synthesis
30-
- <https://github.com/YosysHQ/yosys>
31-
- `nextpnr` for place n route
32-
- <https://github.com/YosysHQ/nextpnr>
33-
- `iverilog` for Verilog compilation and simulation
34-
- <https://github.com/steveicarus/iverilog>
35-
- `icestorm` for a few useful tools for the iCE40 family of FPGAs
36-
- <https://github.com/YosysHQ/icestorm>
37-
- `icesprog` for uploading the bitstream to the iCESugar board specifically
38-
- <http://github.com/wuxx/icesugar>
39-
40-
I recommend building each of these tools from source to ensure the latest (working) version and in the case of `icesprog` you'll also need to add the binary directory to your `$PATH`. Each of these tools has their own required dependencies so look them up to find them. Then, a standard `make -j4` and `sudo make install` suffices, apart from the odd case when a `./configure` was needed. While I was wrapping my head around this, I found <https://f4pga.readthedocs.io/en/latest/flows/index.html> quite helpful in explaining each step of the design flow and how that interlinks with these open source tools.
41-
42-
## TODO
43-
44-
- turn instrmem and regfile into BRAM, memory maybe SPRAM
45-
- write a simple linker script
46-
- add pipeline stalls
47-
- rename pc_incr to pc
48-
- double sw hazard, extra pipeline?
49-
- if a clocked module requires the output of a previous stage, it should take it directly from that previous stage, not the pipeline register!
50-
51-
## Extra steps
52-
53-
### Mounting the iCESugar board
54-
55-
It seems that Raspberry Pi OS couldn't mount the board since `df` turned up empty. It was evident that the device was correctly plugged in though as `lsusb` showed a new addition and `dmesg` didn't show any errors. This meant that the board had to be manually mounted (remember, it's not really a mass storage device but acts like one), so I ran `blkid` to get the device UUID:
56-
57-
```
58-
/dev/sda: SEC_TYPE="msdos" LABEL_FATBOOT="DAPLINK-DND" LABEL="iCELink" UUID="2702-1974" BLOCK_SIZE="512" TYPE="vfat"
59-
```
10+
To run simulations, view waveforms, and flash Lattice/Gowin FPGAs, you'll need
11+
the latest version of the [OSS CAD suite](https://github.com/YosysHQ/oss-cad-suite-build). For Xilinx FPGAs, Vivado is required.
6012

61-
I then added an entry in `fstab`:
13+
All Makefiles rely on the `$ROOT` variable being set, which you can get by
14+
sourcing the appropriately named `sourceme` file.
6215

63-
```
64-
UUID=2702-1974 /mnt/iCELink vfat defaults,auto,users,rw,nofail 0 0
65-
```
16+
Full information on running simulations and the project setup are available on
17+
the [project page](https://matiasilva.github.io/riscv-soc/tools.html)
6618

67-
and that was it!
68-
69-
### Homebrew formula for GTKWave for MacOS (M-series)
70-
71-
GTKWave underwent a complete rewrite and somewhere along the line compatibility with newer Macs was broken. The author does not work on a Mac so couldn't provide correct build instructions. Some nice guy on the internet created a custom Homebrew formula with all the right steps to compile from source. I'm also testing a new waveform visualizer called "surfer".
72-
73-
```
74-
brew update
75-
brew outdated
76-
brew upgrade
77-
brew cleanup
78-
brew uninstall gtkwave
79-
brew untap randomplum/gtkwave
80-
brew install --HEAD randomplum/gtkwave/gtkwave
81-
```
82-
83-
### RISC-V decode filter in GTKWave
84-
85-
Full credits go to [mattvenn](https://github.com/mattvenn/gtkwave-python-filter-process) for the initial code for the GTKWave filter process that takes RISC-V machine code and transforms it into RV32I assembly for easy visualization in the waveform viewer. It seems in between the time they wrote it and now, differences in `risv64-unknown-elf-as` output have broken it.
86-
87-
Note to self: the process file needs to be executable!
88-
89-
Format of the process file: I wasn't able to find any strict documentation on the process file but from my testing I found that the values of a particular signal that are currently rendered will be passed into the `stdin` of the script that is called as a hex string. You can then do whatever you want with this but make sure to add a `\n` to the end of your output string (if it doesn't already have one). Beware of `x`s!
90-
91-
### RISC-V toolchain
92-
93-
<https://github.com/riscv-software-src/homebrew-riscv?tab=readme-ov-file>
94-
95-
### macros
96-
97-
FPGA
98-
99-
### formatting
100-
101-
<https://github.com/chipsalliance/verible/blob/master/verilog/tools/formatter/README.md>
19+
## Author
10220

103-
### verification
21+
Matias Wang Silva, 2024/2025
10422

105-
<https://github.com/YosysHQ/riscv-formal>
106-
<https://github.com/riscv-software-src/riscv-tests/>
23+
## License
10724

25+
MIT

‎docs/src/log.md

+11-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,11 @@
1-
# Project Log
1+
# Project log
2+
3+
## TODO
4+
5+
- turn instrmem and regfile into BRAM, memory maybe SPRAM
6+
- write a simple linker script
7+
- add pipeline stalls
8+
- rename pc_incr to pc
9+
- double sw hazard, extra pipeline?
10+
- if a clocked module requires the output of a previous stage, it should take it
11+
directly from that previous stage, not the pipeline register!

‎docs/src/specification.md

+16
Original file line numberDiff line numberDiff line change
@@ -1 +1,17 @@
11
# Specification
2+
3+
## Naming conventions
4+
5+
The code follows the
6+
[lowRISC coding style](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md)
7+
for Verilog for the most part. I wrote this myself in my free time so there will
8+
be deviations for no real reason.
9+
10+
- signals use snake case
11+
- note: logical word units are joined without underscore
12+
- eg: memwrite expands to memory write (one action)
13+
- eg: mem_to_reg expands to memory to register (no joining)
14+
- parameters use ALL CAPS
15+
- task names, module names are all snake case
16+
- sensible abbreviations should be used but never at the cost of understanding
17+
(vld NO valid YES)

‎docs/src/tools.md

+101
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,106 @@
11
# Tools
22

3+
## Open source ASIC/FPGA tools
4+
5+
While there is a great open source toolset for the iCESugar v1.5, it remains
6+
difficult to navigate the web of broken links to find what is really needed to
7+
get Verilog synthesized and 'running on' the FPGA. After lots of searching and
8+
reading tutorials, I've condensed it to this:
9+
10+
- `yosys` for synthesis
11+
- <https://github.com/YosysHQ/yosys>
12+
- `nextpnr` for place n route
13+
- <https://github.com/YosysHQ/nextpnr>
14+
- `iverilog` for Verilog compilation and simulation
15+
- <https://github.com/steveicarus/iverilog>
16+
- `icestorm` for a few useful tools for the iCE40 family of FPGAs
17+
- <https://github.com/YosysHQ/icestorm>
18+
- `icesprog` for uploading the bitstream to the iCESugar board specifically
19+
- <http://github.com/wuxx/icesugar>
20+
21+
I recommend building each of these tools from source to ensure the latest
22+
(working) version and in the case of `icesprog` you'll also need to add the
23+
binary directory to your `$PATH`. Each of these tools has their own required
24+
dependencies so look them up to find them. Then, a standard `make -j4` and
25+
`sudo make install` suffices, apart from the odd case when a `./configure` was
26+
needed. While I was wrapping my head around this, I found
27+
<https://f4pga.readthedocs.io/en/latest/flows/index.html> quite helpful in
28+
explaining each step of the design flow and how that interlinks with these open
29+
source tools.
30+
31+
## Extra steps
32+
33+
### Mounting the iCESugar board
34+
35+
It seems that Raspberry Pi OS couldn't mount the board since `df` turned up
36+
empty. It was evident that the device was correctly plugged in though as `lsusb`
37+
showed a new addition and `dmesg` didn't show any errors. This meant that the
38+
board had to be manually mounted (remember, it's not really a mass storage
39+
device but acts like one), so I ran `blkid` to get the device UUID:
40+
41+
```bash
42+
/dev/sda: SEC_TYPE="msdos" LABEL_FATBOOT="DAPLINK-DND" LABEL="iCELink"
43+
UUID="2702-1974" BLOCK_SIZE="512" TYPE="vfat"
44+
```
45+
46+
I then added an entry in `fstab`:
47+
48+
```bash
49+
50+
UUID=2702-1974 /mnt/iCELink vfat defaults,auto,users,rw,nofail 0 0
51+
```
52+
53+
and that was it!
54+
55+
### RISC-V decode filter in GTKWave
56+
57+
Full credits go to
58+
[mattvenn](https://github.com/mattvenn/gtkwave-python-filter-process) for the
59+
initial code for the GTKWave filter process that takes RISC-V machine code and
60+
transforms it into RV32I assembly for easy visualization in the waveform viewer.
61+
It seems in between the time they wrote it and now, differences in
62+
`risv64-unknown-elf-as` output have broken it.
63+
64+
Note to self: the process file needs to be executable!
65+
66+
Format of the process file: I wasn't able to find any strict documentation on
67+
the process file but from my testing I found that the values of a particular
68+
signal that are currently rendered will be passed into the `stdin` of the script
69+
that is called as a hex string. You can then do whatever you want with this but
70+
make sure to add a `\n` to the end of your output string (if it doesn't already
71+
have one). Beware of `x`s!
72+
73+
### Homebrew formula for GTKWave for MacOS (M-series)
74+
75+
GTKWave underwent a complete rewrite and somewhere along the line compatibility
76+
with newer Macs was broken. The author does not work on a Mac so couldn't
77+
provide correct build instructions. Some nice guy on the internet created a
78+
custom Homebrew formula with all the right steps to compile from source. I'm
79+
also testing a new waveform visualizer called "surfer".
80+
81+
```bash
82+
brew update brew outdated brew upgrade brew cleanup brew uninstall gtkwave brew
83+
untap randomplum/gtkw
84+
```
85+
86+
### RISC-V toolchain
87+
88+
<https://github.com/riscv-software-src/homebrew-riscv?tab=readme-ov-file>
89+
90+
### macros
91+
92+
FPGA
93+
94+
### formatting
95+
96+
<https://github.com/chipsalliance/verible/blob/master/verilog/tools/formatter/README.md>
97+
98+
### verification
99+
100+
<https://github.com/YosysHQ/riscv-formal>
101+
<https://github.com/riscv-software-src/riscv-tests/>ave brew install --HEAD
102+
randomplum/gtkwave/gtkwave
103+
3104
## Custom scripts
4105

5106
Every design project has its own set of custom scripts, usually to shoehorn

‎Makefile ‎fpga/Makefile

File renamed without changes.

0 commit comments

Comments
 (0)