Merge pull request #2 from AdamMooers/initial_functionality

Initial functionality

.gitignore

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

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/copying/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
 

build/Makefile

@@ -123,14 +123,19 @@ buildroot-clean:
 
 ###### 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.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:~/
+	scp -O ../boot/mmio.py ../linux/comm.py upsilon:~/
 
 ###### External projects
 
@@ -141,7 +146,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:
@@ -159,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|'
 

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
+network 192.168.2.0
-gateway 192.168.1.1
+gateway 192.168.2.1

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')

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/')

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
+This guide is tailored toward a Debian-based machine (and tested on Debian 12).
-beginner.
+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`,
+Set the ethernet port to static ip `192.168.2.100/24`, netmask `255.255.255.0`,
-gateway `192.168.1.1`. Make sure this is not the default route. Make sure
+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.1.0/24 range.
+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
 
@@ -86,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`.
+by your package manager, run `make flash`. If you compiled openFPGALoader using
-If you installed it using `make openFPGALoader`, then just run `make flash`.
+`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.
@@ -97,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

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,8 +24,9 @@ test:
 
 arty.dts: csr.json
 	litex_json2dts_linux csr.json > arty.dts
+
 arty.dtb: arty.dts
 	dtc -O dtb -o arty.dtb arty.dts
 
-mmio.py: csr2mp.py csr.json csr_bitwidth.json
+mmio.py: csr2mp.py csr.json
-	python3 csr2mp.py csr.json csr_bitwidth.json > mmio.py
+	python3 csr2mp.py csr.json > mmio.py

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

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

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',
+                local_ip='192.168.2.50',
-                remote_ip='192.168.1.100',
+                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"),