# Building Instructions

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.

The recommended dev flow if you want to make changes is to use VSCode with remote containers,
it's the easiest way to get the toolchain up and running, and to fix the issues encountered
with migen.

*Note: I currently do not know how to run the dev container with --privileged, so you'll need
to flash by manually running it*

Recommended extensions:

- Pylance
- rust-analyzer

## Building with docker

Easiest way is to build and use the docker container:

```
docker build -r arvp_sonar:latest ./
# Privileged lets you access USB devices inside the container
docker run --privileged --rm -it -v /path/to/repository:/code arvp_sonar:latest

# These commands are run inside the container
cd /code/gateware
python3 litex_main.py --build # Build the bitstream

# To write to the flash storage
# TODO not sure how to use this command
ecpdap write
# To program the FPGA once
ecpdap program build/sonar/gateware/sonar.bit --freq 10M
```

This will generate a bitstream in `gateware/build/sonar

## Toolchain Manual Installation

### Trellis and FPGA toolchain

First, get an [oss-cad-suite release](https://github.com/YosysHQ/oss-cad-suite-build/releases),
and unpack it into an install directory of your choice.

Ensure the `bin/` folder is included in your build environment's PATH.

### Rust

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
```

### Python

Get a recent version of python3, make sure pip is installed. Maybe make a venv
for this? amaranth isn't really that bad for polluting namespaces so don't worry
about making a virtual environment unless you have firm opinions.

Then:

```shell
pip install -r requirements.txt
```

### 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.

## 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
```