Shuffle around files

Author: matiasilva

README.md

@@ -1,42 +1,52 @@
-# riscv-cpu
+# riscv-soc
+
+This repository contains the source code for my Minimal RISC-V SoC.
+
+## Author
+
+Matias Wang Silva, 2024/2025
+
+## License
+
+MIT
 
 ## Naming conventions
 
 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.
 
-* signals use snake case
-	- note: logical word units are joined without underscore
-	- eg: memwrite expands to memory write (one action)
-	- eg: mem_to_reg expands to memory to register (no joining)
-* parameters use ALL CAPS
-* task names, module names are all snake case
-* common abbreviations are used where possible (reg for register, mem for memory, ctrl for control, etc)
+- signals use snake case
+  - note: logical word units are joined without underscore
+  - eg: memwrite expands to memory write (one action)
+  - eg: mem_to_reg expands to memory to register (no joining)
+- parameters use ALL CAPS
+- task names, module names are all snake case
+- common abbreviations are used where possible (reg for register, mem for memory, ctrl for control, etc)
 
 ## Development
 
 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:
 
-* `yosys` for synthesis 
-	- https://github.com/YosysHQ/yosys
-* `nextpnr` for place n route
-	- https://github.com/YosysHQ/nextpnr
-* `iverilog` for Verilog compilation and simulation
-	- https://github.com/steveicarus/iverilog
-* `icestorm` for a few useful tools for the iCE40 family of FPGAs
-	- https://github.com/YosysHQ/icestorm
-* `icesprog` for uploading the bitstream to the iCESugar board specifically
-	- http://github.com/wuxx/icesugar
+- `yosys` for synthesis
+  - <https://github.com/YosysHQ/yosys>
+- `nextpnr` for place n route
+  - <https://github.com/YosysHQ/nextpnr>
+- `iverilog` for Verilog compilation and simulation
+  - <https://github.com/steveicarus/iverilog>
+- `icestorm` for a few useful tools for the iCE40 family of FPGAs
+  - <https://github.com/YosysHQ/icestorm>
+- `icesprog` for uploading the bitstream to the iCESugar board specifically
+  - <http://github.com/wuxx/icesugar>
 
-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.
+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.
 
 ## TODO
 
-* turn instrmem and regfile into BRAM, memory maybe SPRAM
-* write a simple linker script
-* add pipeline stalls
-* rename pc_incr to pc
-* double sw hazard, extra pipeline?
-* if a clocked module requires the output of a previous stage, it should take it directly from that previous stage, not the pipeline register!
+- turn instrmem and regfile into BRAM, memory maybe SPRAM
+- write a simple linker script
+- add pipeline stalls
+- rename pc_incr to pc
+- double sw hazard, extra pipeline?
+- if a clocked module requires the output of a previous stage, it should take it directly from that previous stage, not the pipeline register!
 
 ## Extra steps
 
@@ -56,7 +66,7 @@ UUID=2702-1974 /mnt/iCELink vfat defaults,auto,users,rw,nofail 0 0
 
 and that was it!
 
-### Homebrew formula for  GTKWave for MacOS (M-series)
+### Homebrew formula for GTKWave for MacOS (M-series)
 
 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".
 
@@ -80,17 +90,18 @@ Format of the process file: I wasn't able to find any strict documentation on th
 
 ### RISC-V toolchain
 
-https://github.com/riscv-software-src/homebrew-riscv?tab=readme-ov-file
+<https://github.com/riscv-software-src/homebrew-riscv?tab=readme-ov-file>
 
 ### macros
 
 FPGA
 
 ### formatting
 
-https://github.com/chipsalliance/verible/blob/master/verilog/tools/formatter/README.md
+<https://github.com/chipsalliance/verible/blob/master/verilog/tools/formatter/README.md>
 
 ### verification
 
-https://github.com/YosysHQ/riscv-formal
-https://github.com/riscv-software-src/riscv-tests/
+<https://github.com/YosysHQ/riscv-formal>
+<https://github.com/riscv-software-src/riscv-tests/>
+

docs/conf.py

@@ -1,28 +1,25 @@
 # Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Minimal RISC-V SoC'
-copyright = '2024, Matias Wang Silva'
-author = 'Matias Wang Silva'
+project = "Minimal RISC-V SoC"
+copyright = "2024, Matias Wang Silva"
+author = "Matias Wang Silva"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["myst_parser", 'sphinx_last_updated_by_git']
+extensions = ["myst_parser", "sphinx_last_updated_by_git"]
 
-templates_path = ['_templates']
-exclude_patterns = ['build', 'Thumbs.db', '.DS_Store']
+templates_path = ["_templates"]
+exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'furo'
-html_static_path = ['_static']
+html_theme = "furo"
+html_static_path = ["_static"]
 html_theme_options = {
     "source_edit_link": "https://github.com/matiasilva/riscv-soc/edit/master/docs/src/{filename}",
     "source_view_link": "https://github.com/matiasilva/riscv-soc/blob/master/docs/src/{filename}",
@@ -33,5 +30,4 @@
 myst_heading_anchors = 3
 
 # LaTeX output
-latex_engine = 'lualatex'
-
+latex_engine = "lualatex"

docs/src/index.md

@@ -20,6 +20,7 @@ core
 fpgas
 testing
 log
+tools
 resources
 ```
 

docs/src/tools.md

@@ -0,0 +1,23 @@
+# Tools
+
+## Custom scripts
+
+Every design project has its own set of custom scripts, usually to shoehorn
+bytes around into the right format.
+
+## Editor
+
+This was the first project I completed fully in (neo)vim, using the LazyVim set
+of plugins. I know, I became the very thing I swore to destroy.
+
+If you do happen to go down that route, though, I used the JetBrains Mono Nerd
+Font, which gives full icon support in LazyVim, with the
+[Monokai Pro](https://github.com/loctvl842/monokai-pro.nvim) theme [^also]. I
+also recommend `mini.align` for aligning SystemVerilog and Prettier for
+formatting Markdown, which when coupled with LazyVim's native `lang.markdown`
+support leads to an incredible documentation writing experience. I suggest
+turning on `proseWrap` specifically for Markdown to keep things nicely limited
+at 80 chars per row.
+
+[^also]:
+    I also considered the [Alabaster](https://sr.ht/~p00f/alabaster.nvim/) theme