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 diff --git a/README.md b/README.md index b8b7254..a286860 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/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 diff --git a/build/Makefile b/build/Makefile index 12272e0..2bc21ed 100644 --- a/build/Makefile +++ b/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|' 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/') diff --git a/doc/docker.md b/doc/docker.md index c277336..7f03215 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 @@ -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`. -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. @@ -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 diff --git a/gateware/Makefile b/gateware/Makefile index fc91f34..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,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 - python3 csr2mp.py csr.json csr_bitwidth.json > mmio.py +mmio.py: csr2mp.py csr.json + python3 csr2mp.py csr.json > mmio.py 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 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 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"),