upsilon/doc/docker.md

Upsilon docker development environment setup

Docker Guide

This guide is tailored toward a Debian-based machine (and tested on Debian 12). However, because most of the build process occurs within Docker containers, this guide should be easily adopted to run in nearly any modern Linux environment.

Setup steps

Do all of the following in the build folder.

Installing OpenFPGALoader

Install openFPGALoader. If this program is not in your repositories, run make openFPGALoader to fetch and build the program. This will install openFPGALoader locally.

Even if you install openFPGALoader locally, there are some files (udev rules) that must be installed with administrative privleges. Check the documentation for openFPGALoader.

Setup Rootless Docker

Docker allows you to run programs in containers, which are isolated environments. Build environments can be set up automatically, and re-setup whenever needed.

To install Docker, run:

sudo apt install docker.io docker-compose

Next, using [this guide][2], create a docker group and add your user to that group. This will allow you to run docker commands without needing to run them as root each time.

If you have issues with docker, try adding to ~/.config/docker/daemon.json

{
   "storage-driver": "fuse-overlayfs"
}

Download and Install Python3

Install python3-venv (or python3-virtualenv) and python3-pip:

sudo apt install python3-venv python3-pip

Clone External Repositories

Run make clone. You may need to download the upsilon repositories and put them in the same folder as the Makefile.

Note: If make is not already installed, you can install it by running the following command:

sudo apt install build-essential

Setup Network

Plug in your router/switch to an ethernet port on your computer. If your computer is usually wired to the network, you will need another ethernet port (a PCI card is ideal, but a USB-Ethernet port works).

Set the ethernet port to static ip 192.168.2.100/24, netmask 255.255.255.0, gateway 192.168.2.1. Make sure this is not the default route. Make sure to adjust your firewall to allow traffic on the 192.168.2.0/24 range.

If your local network already uses the 192.168.2.0/24 range, then you must modify upsilon/gateware/soc.py to use different IPs. You must rebuild the SoC after doing this.

The controller boots using TFTP with port 6969. If you cannot use this port, you can modify upsilon/gateware/soc.py to a different value. This value is hardcoded into the SoC and any change to it requires a rebuild of the SoC. You must also change the port in upsilon/build/Makefile under tftp.

Setup Images

Run make images to create all docker images.

Copy Default Config

If you do not have a config.py file in /gateware, copy config.py.def to config.py.

Setup and Run Containers

For NAME in hardware, opensbi, buildroot:

1. Run make $NAME-container to build the container. You usually only need to do this once.
2. If the container already exists, do docker container start upsilon-$NAME.
3. Run make $NAME-copy to copy Upsilon's code into the container.
4. Run make $NAME-execute to build the data.
5. Run make $NAME-get to retrieve the build artifacts.

If you do not delete the container you can run the following when you need to rebuild:

make $NAME-copy $NAME-execute $NAME-get

If you need shell access, run make $NAME-shell.

Run make $NAME-clean to delete the container.

Launch TFTP Server

Install py3tftp (pip3 install --user py3tftp). Then run make tftp to launch the TFTP server. Keep this terminal open.

Flash FPGA

Plug in your FPGA into the USB slot. If you have installed openFPGALoader by your package manager, run make flash. If you compiled openFPGALoader using make openFPGALoader, the makefile will automatically use this instance. Otherwise, it will attempt to use the openFPGALoader version installed through the package manager.

In a second you should see messages in the TFTP terminal. This means your controller is sucessfully connected to your computer.

SSH Access

Add the following to your SSH config:

Host upsilon
	HostName 192.168.2.50
	StrictHostKeyChecking no
	UserKnownHostsFile /dev/null
	IdentityFile upsilon_key
	User root
	LogLevel QUIET

Then copy the file build/upsilon_key to $HOME/.ssh.

When the FPGA is connected you can access it with ssh upsilon (password upsilon).

Wait about a minute for Linux to boot.

Launch FPGA Shell (Optional)

If you cannot access the FPGA through SSH, you can launch a shell through UART.

You will need to install LiteX. Download and run litex_setup.py.

Run litex_term /dev/ttyUSB1. You should get messages in the window with the TFTP server that the FPGA has connected to the server. Eventually you will get a login prompt (username root password upsilon).

Copy Library

Run make copy to copy the Micropython Upsilon library to the FPGA. After this the modules comm and mmio are available when running scripts in /root.