From 1595b1cbc089acb622f869ba829fecf650c36fd8 Mon Sep 17 00:00:00 2001
From: moose <moose@freezinspeech.domain4952>
Date: Wed, 2 Aug 2023 22:20:32 -0400
Subject: [PATCH 01/18] Fixed path to docker set guide

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b8b7254..6ce8827 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Linux. Read `doc/copying/README.md` for license information.
 
 ## Quickstart
 
-Read `doc/copying/docker.md` to set up the Docker build environment.
+Read `doc/docker.md` to set up the Docker build environment.
 
 ## Project Organization
 

From de2f3afd1f0bd1368fe1937219d8c59bc86ebcbd Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Mon, 7 Aug 2023 23:49:18 -0400
Subject: [PATCH 02/18] Removed reference to non-existent file

---
 gateware/rtl/control_loop/control_loop.v.m4 | 1 -
 1 file changed, 1 deletion(-)

diff --git a/gateware/rtl/control_loop/control_loop.v.m4 b/gateware/rtl/control_loop/control_loop.v.m4
index 3e9158a..d9c7d88 100644
--- a/gateware/rtl/control_loop/control_loop.v.m4
+++ b/gateware/rtl/control_loop/control_loop.v.m4
@@ -1,7 +1,6 @@
 m4_changequote(`⟨', `⟩')
 m4_changecom(⟨/*⟩, ⟨*/⟩)
 m4_define(generate_macro, ⟨m4_define(M4_$1, $2)⟩)
-m4_include(control_loop_cmds.m4)
 /* Copyright 2023 (C) Peter McGoron
  * This file is a part of Upsilon, a free and open source software project.
  * For license terms, refer to the files in `doc/copying` in the Upsilon

From 61f1d212b6b68d9acbb77ca0dd9f5273f955385b Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Mon, 7 Aug 2023 23:50:10 -0400
Subject: [PATCH 03/18] Fixed .gitignore to refer to gateware instead of
 firmware

---
 .gitignore | 52 ++++++++++++++++++++++++++--------------------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/.gitignore b/.gitignore
index 07bafcc..b94ccf0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,37 +1,37 @@
 extdoc/
-firmware/build/
-firmware/csr.json
-firmware/litex_json2dts_zephyr.py
-firmware/overlay.config
-firmware/overlay.cmake
-firmware/overlay.dts
-firmware/pin_io.c
+gateware/build/
+gateware/csr.json
+gateware/litex_json2dts_zephyr.py
+gateware/overlay.config
+gateware/overlay.cmake
+gateware/overlay.dts
+gateware/pin_io.c
 misc/
 software/build/
 *.fst
 obj_dir
 *.fst.hier
 *.swp
-firmware/rtl/control_loop/control_loop_cmds.h
-firmware/rtl/raster/ram_shim_cmds.h
-firmware/rtl/raster/raster_cmds.h
-firmware/rtl/base/base.v
-firmware/rtl/control_loop/control_loop.v
-firmware/rtl/control_loop/control_loop_cmds.vh
-firmware/rtl/control_loop/control_loop_math.v
+gateware/rtl/control_loop/control_loop_cmds.h
+gateware/rtl/raster/ram_shim_cmds.h
+gateware/rtl/raster/raster_cmds.h
+gateware/rtl/base/base.v
+gateware/rtl/control_loop/control_loop.v
+gateware/rtl/control_loop/control_loop_cmds.vh
+gateware/rtl/control_loop/control_loop_math.v
 *_preprocessed.v
-firmware/csr.repl
-firmware/csr.resc
-firmware/rtl/control_loop/slpp_all/
-firmware/rtl/raster/.f4cache
-firmware/rtl/raster/build/
-firmware/rtl/raster/pack.log
-firmware/rtl/raster/place.log
-firmware/rtl/raster/route.log
-firmware/rtl/raster/synth.log
-firmware/rtl/raster/synth_test_yosys.v
-firmware/rtl/raster/yosys_output
-firmware/csr_bitwidth.json
+gateware/csr.repl
+gateware/csr.resc
+gateware/rtl/control_loop/slpp_all/
+gateware/rtl/raster/.f4cache
+gateware/rtl/raster/build/
+gateware/rtl/raster/pack.log
+gateware/rtl/raster/place.log
+gateware/rtl/raster/route.log
+gateware/rtl/raster/synth.log
+gateware/rtl/raster/synth_test_yosys.v
+gateware/rtl/raster/yosys_output
+gateware/csr_bitwidth.json
 boot/*
 !boot/boot.json
 build/buildroot.tar.gz

From e6d88df57a536836a7fed88c1be021ce1e912dfa Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 8 Aug 2023 17:05:47 -0400
Subject: [PATCH 04/18] csr_bitdwidth.json appears to have been superceded by
 mmio_descr.py

---
 gateware/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gateware/Makefile b/gateware/Makefile
index fc91f34..6b30672 100644
--- a/gateware/Makefile
+++ b/gateware/Makefile
@@ -25,5 +25,5 @@ arty.dts: csr.json
 arty.dtb: arty.dts
 	dtc -O dtb -o arty.dtb arty.dts
 
-mmio.py: csr2mp.py csr.json csr_bitwidth.json
-	python3 csr2mp.py csr.json csr_bitwidth.json > mmio.py
+mmio.py: csr2mp.py csr.json
+	python3 csr2mp.py csr.json > mmio.py

From 1243542729fefd0d3f536878e39f275b74e1590d Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 8 Aug 2023 17:06:36 -0400
Subject: [PATCH 05/18] Fixed spacing in assignment

---
 gateware/mmio_descr.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gateware/mmio_descr.py b/gateware/mmio_descr.py
index e8635c7..86f9fad 100644
--- a/gateware/mmio_descr.py
+++ b/gateware/mmio_descr.py
@@ -12,7 +12,7 @@ class Descr:
         self.name = name
         self.blen = blen
         self.doc = textwrap.dedent(descr)
-        self.num =num
+        self.num = num
         self.rwperm = rwperm
 
     @classmethod

From dad7e356fbea1f596b063086840ef9674fd6b8e6 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 8 Aug 2023 23:41:28 -0400
Subject: [PATCH 06/18] Moved network from to 192.168.2 because 192.168.1 is
 very common

---
 gateware/soc.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gateware/soc.py b/gateware/soc.py
index a942342..ec5537f 100644
--- a/gateware/soc.py
+++ b/gateware/soc.py
@@ -268,8 +268,8 @@ class UpsilonSoC(SoCCore):
                 csr_address_width=14,
                 csr_paging=0x800,
                 csr_ordering="big",
-                local_ip='192.168.1.50',
-                remote_ip='192.168.1.100',
+                local_ip='192.168.2.50',
+                remote_ip='192.168.2.100',
                 timer_uptime = True)
         # This initializes the connection to the physical DRAM interface.
         self.submodules.ddrphy = s7ddrphy.A7DDRPHY(platform.request("ddram"),

From 9f2ad01907758d4771f0e008db2c8d9b2effec77 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 8 Aug 2023 23:44:41 -0400
Subject: [PATCH 07/18] Removed docker readme because it is maintained in
 upsilon-docker repo

---
 doc/docker.md | 130 --------------------------------------------------
 1 file changed, 130 deletions(-)
 delete mode 100644 doc/docker.md

diff --git a/doc/docker.md b/doc/docker.md
deleted file mode 100644
index c277336..0000000
--- a/doc/docker.md
+++ /dev/null
@@ -1,130 +0,0 @@
-Upsilon docker development environment setup.
-
-# Dockerfile style guide
-
-Dockerfiles should be simple. The Dockerfiles should be readable to a
-beginner.
-
-# Setup steps
-
-Do all of the following in the `build` folder.
-
-## Installing OpenFPGALoader
-
-Install [openFPGALoader][1]. 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.
-
-[1]: https://trabucayre.github.io/openFPGALoader/index.html
-
-## 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.
-
-If you have issues with docker, try adding to `~/.config/docker/daemon.json`
-
-    {
-       "storage-driver": "fuse-overlayfs"
-    }
-
-
-## Download and Install Python3
-
-Install `python3` and `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.
-
-## 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.1.100/24`, netmask `255.255.255.0`,
-gateway `192.168.1.1`. Make sure this is not the default route. Make sure
-to adjust your firewall to allow traffic on the 192.168.1.0/24 range.
-
-If your local network already uses the 192.168.1.0/24 range, then you must
-modify `upsilon/firmware/soc.py` to use different IPs. You must rebuild the
-SoC after doing this.
-
-## Setup Images
-
-Run `make images` to create all docker images.
-
-## 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 artefacts.
-
-If you do not delete the container you can run
-
-	make $NAME-copy $NAME-execute $NAME-get
-
-when you need to rebuild. If you need shell access, run `make $NAME-shell`.
-
-## 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 OPENFPGALOADER=openfpgaloader flash`.
-If you installed it using `make openFPGALoader`, then just run `make flash`.
-
-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.1.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](https://github.com/enjoy-digital/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`.

From 3d00a6514743c7070063849958eb7a331628b4d5 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 8 Aug 2023 23:56:01 -0400
Subject: [PATCH 08/18] Revert "Removed docker readme because it is maintained
 in upsilon-docker repo"

This reverts commit 9f2ad01907758d4771f0e008db2c8d9b2effec77.
---
 doc/docker.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 doc/docker.md

diff --git a/doc/docker.md b/doc/docker.md
new file mode 100644
index 0000000..c277336
--- /dev/null
+++ b/doc/docker.md
@@ -0,0 +1,130 @@
+Upsilon docker development environment setup.
+
+# Dockerfile style guide
+
+Dockerfiles should be simple. The Dockerfiles should be readable to a
+beginner.
+
+# Setup steps
+
+Do all of the following in the `build` folder.
+
+## Installing OpenFPGALoader
+
+Install [openFPGALoader][1]. 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.
+
+[1]: https://trabucayre.github.io/openFPGALoader/index.html
+
+## 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.
+
+If you have issues with docker, try adding to `~/.config/docker/daemon.json`
+
+    {
+       "storage-driver": "fuse-overlayfs"
+    }
+
+
+## Download and Install Python3
+
+Install `python3` and `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.
+
+## 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.1.100/24`, netmask `255.255.255.0`,
+gateway `192.168.1.1`. Make sure this is not the default route. Make sure
+to adjust your firewall to allow traffic on the 192.168.1.0/24 range.
+
+If your local network already uses the 192.168.1.0/24 range, then you must
+modify `upsilon/firmware/soc.py` to use different IPs. You must rebuild the
+SoC after doing this.
+
+## Setup Images
+
+Run `make images` to create all docker images.
+
+## 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 artefacts.
+
+If you do not delete the container you can run
+
+	make $NAME-copy $NAME-execute $NAME-get
+
+when you need to rebuild. If you need shell access, run `make $NAME-shell`.
+
+## 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 OPENFPGALOADER=openfpgaloader flash`.
+If you installed it using `make openFPGALoader`, then just run `make flash`.
+
+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.1.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](https://github.com/enjoy-digital/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`.

From 5be345933224af1f654737721143df57a61384b7 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 8 Aug 2023 23:59:34 -0400
Subject: [PATCH 09/18] Moved network from to 192.168.2 because 192.168.1 is
 very common

---
 build/Makefile                                              | 2 +-
 .../litex_vexriscv/rootfs_overlay/etc/network/interfaces    | 6 +++---
 client/noise_test.py                                        | 2 +-
 client/util.py                                              | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/build/Makefile b/build/Makefile
index 12272e0..211e3cc 100644
--- a/build/Makefile
+++ b/build/Makefile
@@ -127,7 +127,7 @@ OPENFPGALOADER=./openFPGALoader/build/openFPGALoader
 flash:
 	${OPENFPGALOADER} -c digilent ../boot/digilent_arty.bit
 tftp:
-	cd ../boot && py3tftp --host 192.168.1.100 -p 6969 -v
+	cd ../boot && py3tftp --host 192.168.2.100 -p 6969 -v
 
 copy:
 	scp ../boot/mmio.py ../linux/comm.py upsilon:~/
diff --git a/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces b/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces
index 869576c..884debf 100644
--- a/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces
+++ b/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces
@@ -3,7 +3,7 @@ iface lo inet loopback
 
 auto eth0
 iface eth0 inet static
-address 192.168.1.50
+address 192.168.2.50
 netmask 255.255.255.0
-network 192.168.1.0
-gateway 192.168.1.1
+network 192.168.2.0
+gateway 192.168.2.1
diff --git a/client/noise_test.py b/client/noise_test.py
index 9a92feb..2f0fd02 100644
--- a/client/noise_test.py
+++ b/client/noise_test.py
@@ -40,7 +40,7 @@ def sign_extend(value, bits):
 
 # Start a SSH connection to the server.
 print('connecting')
-client = SSHClient('192.168.1.50', user='root', pkey='~/.ssh/upsilon_key')
+client = SSHClient('192.168.2.50', user='root', pkey='~/.ssh/upsilon_key')
 # Upload the script.
 print('connected')
 client.scp_send('../linux/noise_test.py', '/root/noise_test.py')
diff --git a/client/util.py b/client/util.py
index 81d1834..17b5f3b 100644
--- a/client/util.py
+++ b/client/util.py
@@ -34,7 +34,7 @@ def connect_execute(f, *arg):
     from pssh.clients import SSHClient # require parallel-ssh
 
     print('connecting')
-    client = SSHClient('192.168.1.50', user='root', pkey='~/.ssh/upsilon_key')
+    client = SSHClient('192.168.2.50', user='root', pkey='~/.ssh/upsilon_key')
     # Upload the script.
     print('connected')
     client.scp_send(f'../linux/{f}', '/root/')

From 7ef5803cd35227198f97efd2eeec5eb68b29c4a7 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 15 Aug 2023 17:32:25 -0400
Subject: [PATCH 10/18] Migrated changes from the upsilon-docker repo to this
 repo

---
 doc/docker.md | 49 ++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/doc/docker.md b/doc/docker.md
index c277336..b9670f7 100644
--- a/doc/docker.md
+++ b/doc/docker.md
@@ -1,9 +1,10 @@
-Upsilon docker development environment setup.
+Upsilon docker development environment setup
 
-# Dockerfile style guide
+# Docker Guide
 
-Dockerfiles should be simple. The Dockerfiles should be readable to a
-beginner.
+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
 
@@ -27,6 +28,15 @@ 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:
+```bash
+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`
 
     {
@@ -36,24 +46,33 @@ If you have issues with docker, try adding to `~/.config/docker/daemon.json`
 
 ## Download and Install Python3
 
-Install `python3` and `python3-pip`.
+Install `python3-venv` (or `python3-virtualenv`) and `python3-pip`:
+```bash
+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:
+```bash
+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.1.100/24`, netmask `255.255.255.0`,
-gateway `192.168.1.1`. Make sure this is not the default route. Make sure
-to adjust your firewall to allow traffic on the 192.168.1.0/24 range.
+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.1.0/24 range, then you must
+If your local network already uses the `192.168.2.0/24` range, then you must
 modify `upsilon/firmware/soc.py` to use different IPs. You must rebuild the
 SoC after doing this.
 
@@ -70,13 +89,17 @@ For `NAME` in `hardware`, `opensbi`, `buildroot`:
 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 artefacts.
+5. Run `make $NAME-get` to retrieve the build artifacts.
 
-If you do not delete the container you can run
+If you do not delete the container you can run the following when you need to rebuild:
 
-	make $NAME-copy $NAME-execute $NAME-get
+```bash
+make $NAME-copy $NAME-execute $NAME-get
+```
 
-when you need to rebuild. If you need shell access, run `make $NAME-shell`.
+If you need shell access, run `make $NAME-shell`.
+
+Run `make $NAME-clean` to delete the container.
 
 ## Launch TFTP Server
 

From f41ab72483b293062fb0dedc8f6bba924c5e1754 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 15 Aug 2023 17:58:03 -0400
Subject: [PATCH 11/18] Added relative links to documentation

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6ce8827..f1aed0a 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
 # upsilon
 
 Upsilon is a 100% free and open source STM/AFM controller for FPGAs running
-Linux. Read `doc/copying/README.md` for license information.
+Linux. Read [doc/copying/README.md](doc/copying/README.md) for license information.
 
 ## Quickstart
 
-Read `doc/docker.md` to set up the Docker build environment.
+Read the docker [doc/docker.md](doc/docker.md) to set up the Docker build environment.
 
 ## Project Organization
 

From 37c734f7bec57f0381a62d78b24fa3dde0f2b144 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 15 Aug 2023 17:59:14 -0400
Subject: [PATCH 12/18] Fixed a typo in the top-level README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f1aed0a..a286860 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Linux. Read [doc/copying/README.md](doc/copying/README.md) for license informati
 
 ## Quickstart
 
-Read the docker [doc/docker.md](doc/docker.md) to set up the Docker build environment.
+Read [doc/docker.md](doc/docker.md) to set up the Docker build environment.
 
 ## Project Organization
 

From 2a97f0a197b86a104f31c9555b935a202c79bb7a Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Tue, 15 Aug 2023 21:11:20 -0400
Subject: [PATCH 13/18] Fixed line which combined two git commands

---
 build/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build/Makefile b/build/Makefile
index 211e3cc..c4d5f3f 100644
--- a/build/Makefile
+++ b/build/Makefile
@@ -141,7 +141,7 @@ f4pga:
 		git clone https://github.com/chipsalliance/f4pga; \
 	fi
 	cd f4pga && git checkout main && git pull && \
-		git checkout -B upsilon_stable 835a40534f9efd70770d74f56f25fef6cfc6ebc6 \
+		git checkout -B upsilon_stable 835a40534f9efd70770d74f56f25fef6cfc6ebc6
 	tar -czvf f4pga.tar.gz f4pga
 
 buildroot:

From e0c3bedcee2d6dc02b911d2b4309011ae9e3e2b6 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Wed, 16 Aug 2023 15:49:44 -0400
Subject: [PATCH 14/18] Updated makefile to automatically select the right
 openFPGALoader

---
 build/Makefile | 10 +++++++---
 doc/docker.md  |  5 +++--
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/build/Makefile b/build/Makefile
index c4d5f3f..961653d 100644
--- a/build/Makefile
+++ b/build/Makefile
@@ -122,10 +122,14 @@ buildroot-clean:
 	-docker container rm upsilon-buildroot
 
 ###### Execute
-
-OPENFPGALOADER=./openFPGALoader/build/openFPGALoader
 flash:
-	${OPENFPGALOADER} -c digilent ../boot/digilent_arty.bit
+	if [ -d 'openFPGALoader' ]; then \
+		OPENFPGALOADER=./openFPGALoader/build/openFPGALoader; \
+	else \
+		OPENFPGALOADER=openFPGALoader; \
+	fi; \
+	$$OPENFPGALOADER -c digilent ../boot/digilent_arty.bit
+
 tftp:
 	cd ../boot && py3tftp --host 192.168.2.100 -p 6969 -v
 
diff --git a/doc/docker.md b/doc/docker.md
index b9670f7..bf9f33c 100644
--- a/doc/docker.md
+++ b/doc/docker.md
@@ -109,8 +109,9 @@ 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 OPENFPGALOADER=openfpgaloader flash`.
-If you installed it using `make openFPGALoader`, then just run `make flash`.
+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.

From e4a92f5e167c21d8c4c7579f1653b9035b0b45d1 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Wed, 16 Aug 2023 16:27:05 -0400
Subject: [PATCH 15/18] Fixed ip address in host config

---
 doc/docker.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/docker.md b/doc/docker.md
index bf9f33c..7f03215 100644
--- a/doc/docker.md
+++ b/doc/docker.md
@@ -121,7 +121,7 @@ controller is sucessfully connected to your computer.
 Add the following to your SSH config:
 
 	Host upsilon
-		HostName 192.168.1.50
+		HostName 192.168.2.50
 		StrictHostKeyChecking no
 		UserKnownHostsFile /dev/null
 		IdentityFile upsilon_key

From b1fb245908a6996c61f59f393b7edffa4b16cb51 Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Thu, 17 Aug 2023 11:53:18 -0400
Subject: [PATCH 16/18] Cleaned up Makefile formatting and clarified tar
 comment

---
 build/Makefile | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/build/Makefile b/build/Makefile
index 961653d..0a0154e 100644
--- a/build/Makefile
+++ b/build/Makefile
@@ -122,6 +122,7 @@ buildroot-clean:
 	-docker container rm upsilon-buildroot
 
 ###### Execute
+
 flash:
 	if [ -d 'openFPGALoader' ]; then \
 		OPENFPGALOADER=./openFPGALoader/build/openFPGALoader; \
@@ -163,11 +164,14 @@ litex:
 	cd litex && git checkout master && git pull && \
 		git checkout -B upsilon_stable c6ccb626e88168045edacced3743f6bd98746742
 
+# This archiving commands rename the directory which only works with GNU tar
+
 upsilon-hardware.tar.gz:
 	tar -czvf upsilon-hardware.tar.gz ../gateware/ --transform 's|gateware|upsilon/gateware|'
+
 upsilon-buildroot.tar.gz:
 	tar -czvf upsilon-buildroot.tar.gz ../buildroot/ --transform 's|buildroot|upsilon/buildroot|'
-# This script only works for GNU tar. It renames the extraction directory.
+
 upsilon-opensbi.tar.gz:
 	tar -czvf upsilon-opensbi.tar.gz ../opensbi/ --transform 's|opensbi|opensbi/platform|'
 

From 2863c9a2d2a2c6aba31fcf1c17c275a1ebf9360e Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Sun, 20 Aug 2023 00:47:04 -0400
Subject: [PATCH 17/18] Fixed bug where scp silently switches to sftp on new
 version of openssh

---
 build/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build/Makefile b/build/Makefile
index 0a0154e..2bc21ed 100644
--- a/build/Makefile
+++ b/build/Makefile
@@ -135,7 +135,7 @@ tftp:
 	cd ../boot && py3tftp --host 192.168.2.100 -p 6969 -v
 
 copy:
-	scp ../boot/mmio.py ../linux/comm.py upsilon:~/
+	scp -O ../boot/mmio.py ../linux/comm.py upsilon:~/
 
 ###### External projects
 

From a9c6c1080cade0585f4606bf48e704b368e32aec Mon Sep 17 00:00:00 2001
From: Adam Mooers <21245397+AdamMooers@users.noreply.github.com>
Date: Wed, 23 Aug 2023 22:09:34 -0400
Subject: [PATCH 18/18] Added makefile formatting

---
 gateware/Makefile | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/gateware/Makefile b/gateware/Makefile
index 6b30672..9b58ad6 100644
--- a/gateware/Makefile
+++ b/gateware/Makefile
@@ -12,8 +12,10 @@ all: rtl_codegen build/digilent_arty/digilent_arty.bit arty.dtb mmio.py
 
 rtl_codegen:
 	cd rtl && make
+
 csr.json build/digilent_arty/digilent_arty.bit: soc.py
 	TFTP_SERVER_PORT=6969 python3 soc.py
+
 clean:
 	rm -rf build csr.json arty.dts arty.dtb mmio.py
 	cd rtl && make clean
@@ -22,6 +24,7 @@ test:
 
 arty.dts: csr.json
 	litex_json2dts_linux csr.json > arty.dts
+
 arty.dtb: arty.dts
 	dtc -O dtb -o arty.dtb arty.dts