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

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