build examples on self-hosted runner

.github/workflows/build_examples.yml

@@ -2,7 +2,7 @@ name: build_examples
 on: [push]
 jobs:
   examples:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     steps:
       - uses: actions/checkout@v3
       - name: Add SSH Keys for lab-bc

Makefile

@@ -108,39 +108,44 @@ nexys_a7: nexys_a7_io_core_ether nexys_a7_io_core_uart nexys_a7_ps2_logic_analyz
 
 nexys_a7_io_core_ether:
 	cd examples/nexys_a7/io_core_ether/;\
-	manta gen manta.yaml src/manta.v;		\
-	wget -nc  https://fpga.mit.edu/6205/_static/F22/documentation/vivado/lab-bc.py; \
+	manta gen manta.yaml src/manta.v; \
+	rm -rf obj; \
 	mkdir -p obj; \
-	python3 lab-bc.py
+	wget -nc https://fpga.mit.edu/6205/_static/F22/labs/lab05/build.tcl; \
+	vivado -mode batch -source build.tcl
 
 nexys_a7_io_core_uart:
 	cd examples/nexys_a7/io_core_uart/; \
 	manta gen manta.yaml src/manta.v;		\
-	wget -nc  https://fpga.mit.edu/6205/_static/F22/documentation/vivado/lab-bc.py; \
+	rm -rf obj; \
 	mkdir -p obj; \
-	python3 lab-bc.py
+	wget -nc https://fpga.mit.edu/6205/_static/F22/labs/lab05/build.tcl; \
+	vivado -mode batch -source build.tcl
 
 nexys_a7_ps2_logic_analyzer:
 	cd examples/nexys_a7/ps2_logic_analyzer/;  					\
 	manta gen manta.yaml src/manta.v;							\
 	manta playback manta.yaml my_logic_analyzer sim/playback.v;	\
-	wget -nc  https://fpga.mit.edu/6205/_static/F22/documentation/vivado/lab-bc.py; \
+	rm -rf obj; \
 	mkdir -p obj; \
-	python3 lab-bc.py
+	wget -nc https://fpga.mit.edu/6205/_static/F22/labs/lab05/build.tcl; \
+	vivado -mode batch -source build.tcl
 
 nexys_a7_video_sprite_ether:
 	cd examples/nexys_a7/video_sprite_ether;\
 	manta gen manta.yaml src/manta.v;		\
-	wget -nc  https://fpga.mit.edu/6205/_static/F22/documentation/vivado/lab-bc.py; \
+	rm -rf obj; \
 	mkdir -p obj; \
-	python3 lab-bc.py
+	wget -nc https://fpga.mit.edu/6205/_static/F22/labs/lab05/build.tcl; \
+	vivado -mode batch -source build.tcl
 
 nexys_a7_video_sprite_uart:
 	cd examples/nexys_a7/video_sprite_uart;	\
 	manta gen manta.yaml src/manta.v;		\
-	wget -nc  https://fpga.mit.edu/6205/_static/F22/documentation/vivado/lab-bc.py; \
+	rm -rf obj; \
 	mkdir -p obj; \
-	python3 lab-bc.py
+	wget -nc https://fpga.mit.edu/6205/_static/F22/labs/lab05/build.tcl; \
+	vivado -mode batch -source build.tcl
 
 icestick: icestick_io_core
 

doc/index.md

@@ -2,40 +2,45 @@
 
 ## Manta: An In-Situ Debugging Tool for Programmable Hardware
 
-Manta is a tool for getting information into and out of FPGAs over an interface like UART or Ethernet. It's primarily intended for debugging, but it's robust enough to be a simple, reliable transport layer between a FPGA and a host machine. It lets you configure a series of cores on a shared bus via a YAML or JSON file, and then provides a Python API to each core, along with vendor-agnostic Verilog HDL to instantiate them on your FPGA.
+Manta is a tool for getting information into and out of FPGAs over UART or Ethernet. It's primarily intended for debugging and experimentation, but it's robust enough to be a simple, reliable transport layer between a FPGA and a host machine. It works by letting you configure a series of cores, which live as digital logic on the FPGA and are represented with vendor-agnostic Verilog-2001. The information and behavior of these cores are accessible to the host machine, which presents a Python API to the user. Manta includes the following cores, any number and combination of which may be used at once:
+
+### __Logic Analyzer Core__
+
+_More details available on the [full documentation page](./logic_analyzer_core.md)._
+
+This core captures a timeseries of digital signals from within the FPGA, much like a benchtop logic analyzer would. This captures data on the FPGA's native clock and presents it as a waveform, making it very useful for debugging logic cycle-by-cycle. This concept is very similar to the Xilinx [Integrated Logic Analyzer (ILA)](https://docs.xilinx.com/r/en-US/ug908-vivado-programming-debugging/ILA) and Intel [SignalTap](https://www.intel.com/content/www/us/en/docs/programmable/683819/21-3/logic-analyzer-introduction.html) utilities.
+
+You may find this core useful for:
+
+* _Verifying specification adherence for connected hardware_ - for instance, you're writing a S/PDIF decoder that works in simulation, but fails in hardware. The logic analyzer core can record a cycle-by-cycle capture of what's coming off the cable, letting you verify that your input signals are what you expect. Even better, Manta will let you play that capture back in your preferred simulator, letting you feed the exact same inputs to your module in simulation and check your logic.
 
 
-You might find Manta useful for:
+### __I/O Core__
 
-* _Verifying specification adherence for connected hardware_ - your I2S decoder works in simulation, but doesn't in hardware. Manta will help you figure out why.
+_More details available on the [full documentation page](./io_core.md)._
+
+This core presents a series of user-accessbile registers to the FPGA fabric, which may be configured as either inputs or outputs. The value of an input register can be read off the FPGA by the host machine, and the value of an output register on the FPGA may be set by the host machine. This is handy for getting small amounts of information into and out of the FPGA, debugging, configuration, or experimentation. This concept is very similar to the Xilinx [Virtual IO](https://docs.xilinx.com/v/u/en-US/pg159-vio) and Intel [In-System Sources and Probes](https://www.intel.com/content/www/us/en/docs/programmable/683552/18-1/in-system-sources-and-probes-66964.html) tools.
 
-* _Moving generic data between a host and connected FPGA_ - you're working on a cool new ML accerleator, but you don't want to think about how to get training data and weights out of TensorFlow, across some interface, and into your core.
 
 * _Prototyping designs in Python, and incrementally migrating them to hardware_ - you're working on some real-time signal processing, but you want to prototype it with some sample data in Numpy before meticulously implementing everything in Verilog.
 
+* _Making dashboards_
+
+### __Block Memory Cores__
+
+_More details available on the [full documentation page](./block_memory_core.md)._
+
+This core creates a two-port block memory on the FPGA, and gives one port to the host machine, and the other to your logic on the FPGA. The width and depth of this block memory is configurable, allowing large chunks of arbitrarily-sized data to be shuffled onto and off of the FPGA by the host machine, via the Python API. This lets you establish a transport layer between the host and FPGA, that treats the data as exactly how it exists on the FPGA.
+
+* _Moving generic data between a host and connected FPGA_ - you're working on a cool new ML accerleator, but you don't want to think about how to get training data and weights out of TensorFlow, across some interface, and into your core.
+
+* _Hand-tuning image sprites_
+
+
+## Dependencies
+
 Mant is written in Python, and generates Verilog-2001 HDL. It's cross-platform, and its only strict dependency is pyYAML. However, [pySerial](https://github.com/pyserial/pyserial) is required for using UART, [scapy](https://github.com/secdev/scapy) is required for using Ethernet, and [pyvcd](https://github.com/westerndigitalcorporation/pyvcd) is required if you want to export a waveform from the Logic Analyzer core to a `.vcd` file.
 
-## Cores
-
-Manta includes a few cores, configurable to your liking:
-
-* __Logic Analyzer Core__: The host can arm the core, and then when a trigger condition is met, the debug output is wired back to the host, where it's saved as a waveform file. This can then be opened and inspected in a waveform viewer like GTKWave, or directly manipulated in Python using the generated API. This is similar to Xilinx's [Integrated Logic Analyzer (ILA)](https://docs.xilinx.com/r/en-US/ug908-vivado-programming-debugging/ILA) and accompanying [ChipScoPy API](https://xilinx.github.io/chipscopy/2022.2/overview.html) and Intel/Altera's [SignalTap](https://www.intel.com/content/www/us/en/docs/programmable/683819/21-3/logic-analyzer-introduction.html) utility.
-
-* __I/O Core__: This exposes a number of probes that can be read or set, allowing for signals inside the FPGA to be monitored and controlled by the host machine. This is similar to Xilinx's [Virtual IO](https://docs.xilinx.com/v/u/en-US/pg159-vio) core.
-
-* __Block Memory Cores__: Under the hood, Manta is just a bunch of memory on a common address and data bus, so adding memory of either type to the bus is straightforward. Block memories are dual-port, so interfacing with them in your own HDL is incredibly easy.
-
-These cores are more explicity described on their individual pages.
-
-## Design Philosophy
-
-* _Things that are easy to misconfigure should be easy to reconfigure_. For instance, it's easy to accidentally put the wrong amount of holdoff in a logic analyzer core and shouldn't require regenerating a bitstream to fix.
-
-* _Autogenerate Verilog 2001 for compatibility._ However, some SystemVerilog 2012 is used for simulation and test.
-
-* _Separate data and operations on it._ This basically means that there shouldn't be much Verilog in the Python, and vice versa. As a result, the code autogeneration is done with a series of HDL templates that have sections filled in by Python. This is done with a bunch of find-and-replace, where hooks in the template file are replaced with the customized Verilog needed at that particular point.
-
-* _Make no assumptions about what the tools can do._ For instance, if you want to make a logic analyzer that has an input probe that's ten billion bits wide, Manta shouldn't complain - it'll leave that to your implementation engine. This allows Manta to maintain portability.
 
 ## About
-Manta was originally developed as part of my [Master's Thesis at MIT](dspace.mit.edu) in 2023, done under the supervision of Dr. Joe Steinmeyer. But I think it's a neat tool, so I'm still working on it :)
+Manta was originally developed as part of my [Master's Thesis at MIT](./thesis.pdf) in 2023, done under the supervision of Dr. Joe Steinmeyer. But I think it's a neat tool, so I'm still working on it :)

doc/system_architecture.md

@@ -165,3 +165,13 @@ Nominal interaction with the logic analyzer core should be:
 - Read out contents from memory
 - Pulse stop_request to end the capture and return the state back to IDLE
 
+
+## Design Philosophy
+
+* _Things that are easy to misconfigure should be easy to reconfigure_. For instance, it's easy to accidentally put the wrong amount of holdoff in a logic analyzer core and shouldn't require regenerating a bitstream to fix.
+
+* _Autogenerate Verilog 2001 for compatibility._ However, some SystemVerilog 2012 is used for simulation and test.
+
+* _Separate data and operations on it._ This basically means that there shouldn't be much Verilog in the Python, and vice versa. As a result, the code autogeneration is done with a series of HDL templates that have sections filled in by Python. This is done with a bunch of find-and-replace, where hooks in the template file are replaced with the customized Verilog needed at that particular point.
+
+* _Make no assumptions about what the tools can do._ For instance, if you want to make a logic analyzer that has an input probe that's ten billion bits wide, Manta shouldn't complain - it'll leave that to your implementation engine. This allows Manta to maintain portability.