Improve top-level docs

BUILDING.md

@@ -1,7 +1,7 @@
 # Building Instructions
 
-All of this is assumed to be on a linux system. Eventually I'll probably make or use some dockerfile that
-has all this installed already.
+All of this is assumed to be on a linux system. Eventually I'll probably make or
+use some dockerfile or nix flake that has all this installed already.
 
 ## Toolchain Installation
 
@@ -12,20 +12,54 @@ and unpack it into an install directory of your choice.
 
 Ensure the `bin/` folder is included in your build environment's PATH.
 
-### LiteX
-
-Simply follow the [LiteX quick start guide](https://github.com/enjoy-digital/litex#quick-start-guide).
-
-Ensure that the RISCV toolchain `bin/` folder is also included in your build environment's PATH.
-
 ### Rust
 
-TODO will need to install rust and install the rv32/nightly toolchain
+Install the rust toolchain with the instructions at [rustup.rs](https://rustup.rs).
+
+Install the RV32 target:
+
+```shell
+rustup target add riscv32i-unknown-none-elf
+```
 
 ### ecpdap (Optional?)
 
-You may or may not have to install your own version of ecpdap, I found the one in `oss-cad-suite` didn't work
-for whatever reason, so I had to install it myself. There are releases on the github, or you can just build it
-yourself with Rust. Just make sure you either replace the binary in the oss-cad-suite location or make sure
-this version of ecpdap has priority in PATH.
+You may or may not have to install your own version of ecpdap, I found the one
+in `oss-cad-suite` didn't work for whatever reason, so I had to install it
+myself. There are releases on the github, or you can just build it yourself with
+Rust. Just make sure you either replace the binary in the oss-cad-suite location
+or make sure this version of ecpdap has priority in PATH.
 
+## Building
+
+TODO is to unify everything into a top-level python script, but until then, you have to live with this.
+
+Firmware must be built first, as it gets incorporated into RTL image.
+
+Firmware can be built with:
+
+```shell
+cd firmware/
+cargo build --release
+```
+
+Gateware can be built with:
+
+```shell
+cd gateware/
+python3 soc.py --build
+```
+
+## Programming
+
+Gateware can be programmed to the FPGA in volatile memory with:
+
+```shell
+ecpdap program gateware/build/top.bit --freq 10M
+```
+
+Gateware can be written to flash with:
+
+```shell
+# TODO, it's a lightly awkward command that isn't in my shell history
+```

README.md

@@ -1,61 +1,72 @@
 # Updated Sonar System
 
-Will *not* be doing LVDS system, because arty doesn't have selectable bank voltage to actually use it.
-
-Switching to use Colorlight i9 board (ECP5 UP5K 45), because it has plenty IO broken out, also provides ethernet
-(I just need to implement the magnetics and jack), and is cheaper/potentially easier to acquire for ARVP
-in the future. The LiteX implementation fits in <40% of total resources of the 25K LUT variant, so the 45K
-should be plenty for what I need. Frankly what I'm implementing is very simple. It can probably even handle doing
-the FFT on board if I wanted to.
+This repository contains all the design files for my attempt at an updated and
+improved passive sonar data acquisition system. The goal of this system is
+simply to be able to capture pinger data, filtered by the preprocessor board,
+via ethernet, at significantly faster speed than the previous system.
 
 ## Repo Layout
 
 ```
+firmware/
+  hello_world_c - My very first testing code for doing SoC bringup
+  TODO - break FW out into multiple crates to provide more functionality
+gateware/ - RTL for creating the SoC
 hardware/ - Directory for any hardware designs
   pmod/ - A PMOD interface board, using 4 ADCs with LVDS converters to get data across PMOD [Failed Idea]
+  colorlight-base/ - Baseboard that attaches to the preprocessor (replases BeagleBone + PruDAQ)
+  sonar-footprints.pretty/ - custom KiCAD footprints for this project
   sonar_symbols.kicad_sym - custom KiCAD symbols I create for hardware
+  colorlight_pin_extractor.py - a script I used to help in making the kicad symbol for the colorlight module
 ```
 
 ## Design Goals
 
-- 4x 20MSPS channels @ > 8 bits
+- ~~4x 20MSPS channels @ > 8 bits~~ Reduced to 10MSPS @ 9 bits due to memory resource constraints.
 - Ethernet data channel
 - Simplified software stack (or at least fewer layers of components)
 - Well-documented
 
-## System Architecture
-
 ## RTL Architecture
 
-General SoC architecture and other similar goodies can be found in `gateware/docs`.
+General SoC architecture and other similar goodies can be found in
+`gateware/docs`.
 
-#### Diagram TODO
+To over simplify, I am creating an SoC with an rv32im core, connected to a
+single wishbone bus to access all memory and peripherals. All RTL is written in
+Amaranth.
 
-The plan is to use LiteX and let it do most of the heavy lifting. Components to
-generate:
+## Firmware Architecture
 
-- Softcore (some RISC-V core)
-- Main memory bus
-- DMA engine
-- Gigabit Ethernet MAC
+Given how much I can very simply offload onto the RTL (peak detection, maaaybe DMA, etc.),
+the firmware will be pretty simple. I will use embassy just to make things easier
+on myself. All I really have to do is provide some configuration interface over ethernet,
+set up and read out captures, and push those to the Xavier.
 
-THis way the only actual RTL to write is the peripheral that interacts with the ADCs,
-which should be very simple. To do early bringup I can start with a blinky peripheral to
-demonstrate access to the bus, and then I can keep adding functionality.
+The configuration interface only needs to expose the following functionality:
 
-## Software Planning
+- Stop/start capturing
+- Set filter frequency
+- Set capture size and offset
+- Automatic triggering settings
+- Manual triggering
 
-Will try to use embassy on RISC-V if I can.
+The data channel can be whatever form I want, although if ZMQ is easy to
+implement I may keep it to reduce changes to the ROS software.
 
-Should make sure to have a debug port available as early as possible.
+## Random notes
 
-I will make the interface as generic as possible, so it should be easy to swap out, but I
-will start by targetting zmq so I can change as little of the software stack as possible.
+You will probably need to un write-protect the flash on the colorlight
 
+Will *not* be doing LVDS system, because arty doesn't have selectable bank
+voltage to actually use it.
 
-## Random issues
-
-You will probably need to un write-protect the flash
+Switching to use Colorlight i9 board (ECP5 UP5K 45), because it has plenty IO
+broken out, also provides ethernet (I just need to implement the magnetics and
+jack), and is cheaper/potentially easier to acquire for ARVP in the future. The
+LiteX implementation fits in <40% of total resources of the 25K LUT variant, so
+the 45K should be plenty for what I need. Frankly what I'm implementing is very
+simple. It can probably even handle doing the FFT on board if I wanted to.
 
 ### ecpdap: "Error: specified probe not found"
 
@@ -63,4 +74,5 @@ A Reboot fixed it....
 
 Do I have ecpdap installed in two places and one of them doesn't work maybe?
 
-I do have two versions installed. one from oss-cad-suite and one by building it manually.
+I do have two versions installed. one from oss-cad-suite and one by building it
+manually.

gateware/design_notes.md

@@ -0,0 +1,46 @@
+# Acquisition capture design
+
+How much data do we need to capture worst case?
+
+- 2ms @ 40MHz
+
+80_000 samples, or 160_000 bytes (if we assume >8 bit samples)
+
+LFE5U-45 has 108 18kbit sysMEM blocks.
+
+18kbit is roughly equal to 2kB, so 80 EBR blocks per channel
+
+shit
+
+DDR2 provides up to 800Mbit/s data rates
+
+800 / 40MHz = 20 bits, not enough to stream data out either...
+
+huh
+
+This may be problematic
+
+if we chop to 20MHz and 1 byte per sample, we get 40_000 bytes per channel
+
+This puts us at 20 EBR blocks per channel, which is feasible, 28 EBR to use for other resources
+
+Huh, this is *very* marginal. Maybe should have gone with something else.
+
+Oh well
+
+Likely the best thing to do here, is to add icache and dcache, and put system memory behind DRAM.
+
+And also pull code in to DRAM
+
+
+# Interfaces to support:
+
+DAC for setting gain. (DAC needs to be added in hardware)
+
+I2C to set Variable Oscillator for setting filter frequencies
+
+Peak detector does not have an ADC on board. Given this, we should just do peak detection in gateware.
+
+# General notes
+
+Will need to have a timer implemented as well

gateware/minerva_notes.md

@@ -0,0 +1,6 @@
+# Issues I had
+
+external_interrupt signals are quite un-documented. Are they inputs or outputs?
+Seems like they're outputs, but how do we import external interrupts?
+Are we supposed to implement our own interrupt controller?
+These are inputs then?