luke
/
manta
mirror of https://github.com/fischermoseley/manta.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: condense a few pages

This commit is contained in:
Fischer Moseley 2024-08-06 17:36:39 -07:00
parent daedb91ff2
commit c38e6b5b40
6 changed files with 69 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
doc/getting_started.md
View File

@ -1,69 +1,48 @@
## Overview
Regardless of if you use Manta in a traditional Verilog-based workflow or natively in an Amaranth design, the general concept of operation is as follows:
To use Manta, you'll need a host machine with a FPGA board connected over UART, or a FPGA board connected to the same network via Ethernet. You'll then:
- Specify and configure the cores you wish to include in your FPGA design.
- Generate RTL for these cores, and include this RTL in your design.
- Build the design, and upload it to your device.
- Operate the cores from the host machine.
- _Specify a set of debug cores you wish to include in your design._ This is done by writing a configuration file, typically called `manta.yaml`. Specifying files in JSON is also supported, as long as the hierarchy in the file is equivalent. Just make sure that your YAML files end in `.yaml` or `.yml`, and that JSON files end in `.json`.
- _Invoke Manta to generate Verilog from the configuration provided._ This is done by running `manta gen [config_file] [verilog_file]` at the command line, which generates a Verilog file (typically named `manta.v`) from the provided configuration file. This Verilog file contains a definition for a Verilog module named `manta`, and all its constituent modules.
- _Instantiate `manta` in your design, and connecting it to the logic you'd like to debug._ Manta will provide an example instantiation if you run `manta inst [config_file]`, which you can copy-paste into your source code. You'll connect its ports to the logic you're trying to debug, as well as to whatever interface you're using to communicate with the host. This will be a serial transciever on your development board if you're using UART, or it's RMII PHY if you're using Ethernet.
- _Build and upload the design to your FPGA using your preferred toolchain._
- _Use the debug core(s) through the Python API or the command line._ The functions availble to each core are described in their documentation.
- _Repeat!_ As you debug, you'll probably want to change exactly how Manta is configured. This means tweaking the configuration file, regenerating the Verilog module, and so on.
Manta’s cores are small, configurable blocks that each provide some functionality. More information on each core can be found on their respective documentation pages. Manta supports an arbitrary amount of unique cores, limited only by the available resources of your device.
## Example Configuration
## Usage in Traditional Verilog-Based Workflows
An example config file is provided below. If this file was named `manta.yaml` then running `manta gen manta.yaml manta.v` would generate Verilog for a `manta` module that matched the config file.
Although modern HDLs are rising in popularity, most existing FPGA designs use a Verilog-based workflow. This consists of synthesizing a number of Verilog files into a single design. Manta can easily be used in such a workflow, as described below:
- The cores and interface used to communicate with them is specified in a configuration file, written in YAML. This file is typically named `manta.yaml` .
- A Verilog file containing the cores specified in the configuration file is generated. This is most often done at the command line with the `manta gen` command (for example, `manta gen manta.yaml manta.v`) but can also be done with the `generate_verilog`method of the `Manta` Python class. This file contains the definition of a Verilog module named `manta`, which includes all the cores specified in the configuration file.
- This `manta` module is instantiated in your design, and the signals to each core are connected to your logic. Connections are also made to the signals of the interface specified in the configuration file. The `manta inst` command can also be used to generate a Verilog instantiation that can be copy-pasted into your source.
- After the design is built and uploaded to the FPGA, the cores are operated from the host machine. Each core exposes a Python API containing methods that can be invoked from a Python script. These are described in great detail in the documentation for each core.
!!! success "VHDL works too!"
If your FPGA design is VHDL-based, fret not! Most synthesis tools support mixed-language projects, and will happily ingest both a Verilog-based Manta module inside of a VHDL-based design. Just take care to ensure that the interfaces match.
### Example
A minimal example of a `manta.yaml` file may be observed below:
```yaml
---
cores:
my_io_core:
type: io
inputs:
probe_0_in: 6
probe_1_in: 12
my_input_signal: 6
outputs:
probe_2_out: 20
probe_3_out: 1
my_logic_analyzer:
type: logic_analyzer
sample_depth: 4096
trigger_location: 1000
probes:
larry: 1
curly: 3
moe: 9
triggers:
- moe RISING
- curly FALLING
my_output_signal: 12
uart:
port: "auto"
baudrate: 3000000
clock_freq: 100000000
baudrate: 3e6
clock_freq: 100e6
```
Although it's just an example, this config file shows the two things every Manta configuration needs, namely:
- ___Cores___: A list of the debug cores Manta should place on your FPGA. The behavior and configuration of the cores is described in more detail on their documentation pages, but this list contains each core you'd like included in your `manta` module. This list can have as many entires as your FPGA can support, so long as Manta can address them all. If it can't, it'll throw an error when it tries to generate Verilog.
- ___Interface___: The way data gets on and off the FPGA. At present, Manta only supports UART and Ethernet interfaces. These are described in more detail on their documentation pages, but the interface of choice is specified with either a `uart` or `ethernet` at the end of the configuration file.
This Manta instance has an IO Core and a Logic Analyzer, each containing a number of probes at variable widths. The Manta module itself is provided a 100MHz clock, and communicates with the host over UART running at 3Mbaud. This is just an example, and more details are available in the documentation page for each core.
## Example Instantiation
Lastly, we Manta can automatically generate a copy-pasteable Verilog snippet to instantiate Manta in your design by running `manta inst [config_file]`. For example, the following snippet is generated for the configuration above:
!!! note "Reset is active high!"
The Manta instance will reset while `rst` is held high. If you want to share reset logic with an active low reset signal (for example, `rst_n`), be sure to invert it first.
This includes a single IO core in the `manta` module, which communicates with the host machine over a 3Mbaud UART link. Instantiating this core in your design might look like the following, as generated by `manta inst`:
```verilog
manta manta_inst (
@ -71,11 +50,16 @@ manta manta_inst (
.rst(rst),
.rx(rx),
.tx(tx),
.probe_0_in(probe_0_in),
.probe_1_in(probe_1_in),
.probe_2_out(probe_2_out),
.probe_3_out(probe_3_out),
.larry(larry),
.curly(curly),
.moe(moe));
.my_input_signal(my_input_signal),
.my_output_signal(my_output_signal));
```
!!! note "Reset is active high!"
The Manta instance will reset while `rst` is held high. If you want to share reset logic with an active low reset signal (for example, `rst_n`), be sure to invert it first.
More examples of Verilog-based designs can be found in the [examples/verilog](https://github.com/fischermoseley/manta/tree/main/examples/verilog) folder of the repo.
## Usage in Amaranth Designs
Manta is written in Python, which allows it to easily export a native Amaranth API.

46
doc/index.md
View File

@ -2,52 +2,14 @@
## Manta: A Configurable and Approachable Tool for FPGA Debugging and Rapid Prototyping
Manta is a tool for moving data between a host machine and a FPGA over UART or Ethernet. It's primarily intended for debugging and rapid prototyping of FPGA designs, but it's robust enough to be used as a simple, reliable transport layer.
Manta is a tool for rapidly prototyping and debugging FPGA designs. It works by providing a Manta module which is included in a FPGA design, which itself contains a number of *cores* - small, configurable debugging blocks that each provide some functionality. These cores are then connected to your design, and allow you to interface with it from a connected host machine.
Manta works by generating a number of cores that are instantiated in the FPGA design. These allow for a variety of functions, such as reading and writing to registers and memory, or capturing data with a logic analyzer. These cores are operated by the connected host machine through either the Manta CLI, or a simple Python API.
These cores include functionality such as register reads/writes, memory accesses, and an embedded logic analyzer. Manta includes both a UART and Ethernet (via UDP) interface for communication between the host and FPGA.
Manta is written in Amaranth HDL, and the generated designs may be used natively in other Amaranth designs, or exported to vendor-agnostic Verilog-2001. All dependencies are cross-platform, so Manta can be used on any machine that has at least Python 3.8 or newer installed.
Manta's capabilities are best reflected in its cores, for which a brief description of each is provided below:
### __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.
* _Capturing arbitrary data_ - you're working on a DSP project, and you'd like to grab some test data from your onboard ADCs to start prototyping your signal processing with. Manta will grab that data, and export it for you.
### __I/O Core__
_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.
You may find this core useful for:
* _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_ - you'd like to get some telemetry out of your existing FPGA design and display it nicely, but you don't want to implement an interface, design a packetization scheme, and write a library.
### __Memory Cores__
_More details available on the [full documentation page](./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.
You may find this core useful for:
* _Moving data between a host and connected FPGA_ - you're working on a cool new machine learning accelerator, but you don't want to think about how to get training data and weights out of TensorFlow, and into your core.
* _Hand-tuning ROMs_ - you're designing a digital filter for a DSP project and would like to tune it in real-time, or you're developing a soft processor and want to upload program code without rebuilding a bitstream.
Manta specifies its RTL logic with [Amaranth](https://github.com/amaranth-lang/amaranth) which allows it to target nearly any FPGA device, regardless of vendor. Manta itself is written in pure Python, which allows it to run on Windows, macOS, Linux, and BSD across a variety of CPU architectures. Manta can be included natively in Amaranth-based designs, or export Verilog-2001 for use in traditional Verilog-based workflows.
## About
Manta and its source code are released under a [GPLv3 license](https://github.com/fischermoseley/manta/blob/main/LICENSE.txt), and it was originally developed as part of my [Master's Thesis at MIT](https://hdl.handle.net/1721.1/151223) in 2023, done under the supervision of [Dr. Joe Steinmeyer](https://www.jodalyst.com/). The thesis itself is copyrighted by Fischer Moseley (me!), but feel free to use the following Bibtex if you'd like to cite it:
Manta and its source code are released under a [GPLv3 license](https://github.com/fischermoseley/manta/blob/main/LICENSE.txt), and it was originally developed as part of my [Master's Thesis at MIT](https://hdl.handle.net/1721.1/151223) in 2023, done under the supervision of [Dr. Joe Steinmeyer](https://www.jodalyst.com/). The following Bibtex is available if you wish to cite it:
```bibtex
@misc{manta2023,

41
doc/installation.md
View File

@ -4,8 +4,15 @@ Before installing, make sure to upgrade your `pip` to the latest version:
pip install --upgrade pip
```
## Latest Version
You can install the latest version of Manta directly from source with:
## Latest Release (Recommended)
The latest release of Manta can be installed from PyPI with:
```bash
pip install --upgrade manta-python
```
## Development Snapshot
The latest development snapshot of Manta can be installed with:
```bash
pip install --upgrade git+https://github.com/fischermoseley/manta.git
@ -20,32 +27,26 @@ cd manta
pip install -e ".[dev]"
```
Manta's hardware-in-the-loop tests rely on Amaranth's build system for programming FPGAs, which in turn rely on the open-source `xc3sprog` and `iceprog` tools for programming Xilinx and ice40 devices, respecitvely. If you'd like to run these tests locally, you may need to install these tools and have them available on your `PATH`. If you're on Linux, you may also need to add a new udev rule to give non-superuser accounts access to any connected FTDI devices. This can be done by making a new file at `/etc/udev/rules.d/99-ftdi-devices.rules`, which contains:
Manta's hardware-in-the-loop tests rely on Amaranth's build system for programming FPGAs, which in turn rely on the open-source `xc3sprog` and `iceprog` tools for programming Xilinx and ice40 devices, respecitvely. If you'd like to run these tests locally, you may need to install these tools and have them available on your `PATH`.
If you're on Linux, you may also need to add a new udev rule to give non-superuser accounts access to any connected FTDI devices. This can be done by making a new file at `/etc/udev/rules.d/99-ftdi-devices.rules`, which contains:
```
ACTION=="add", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE:="666"
```
Be sure to reload your udev rules after saving the file.
Be sure to reload your udev rules after saving the file. On most distributions, this is accomplished with:
## Adding Manta to Path (Recommended)
```bash
udevadm control --reload-rules && udevadm trigger
```
It's recommended to place Manta on your system path by adding `export PATH="~/.local/bin:$PATH"` to your `.bashrc` or `.zshrc`. This isn't strictly necessary, but it means that Manta (and any other executable Python modules) can be run as just `manta` on the command line, instead of `python3 -m manta`. If you're on Windows, this location will likely be different.
## Adding Manta to PATH (Optional)
Later Manta will be availabe on the PyPI lists, and you'll be able to just `pip install mantaray`, but that's not configured quite yet.
Although optional, it is convenient to add the `manta` executable to your system's path. This allows you to invoke Manta's CLI with `manta`, rather than the more verbose `python3 -m manta`. The location of this executable depends on both your platform and if you're using a virtual environment. For example:
## Dependencies
Manta requires the following dependencies:
- Windows: `%APPDATA%\Python\Scripts`, or `path\to\venv\Scripts` if using a virtual environment.
- [Amaranth HDL](https://amaranth-lang.org/docs/amaranth/latest/), which comes with it's own built-in copy of Yosys.
- [LiteEth](https://github.com/enjoy-digital/liteeth), for sending and receiving UDP packets on the FPGA.
- [pySerial](https://pyserial.readthedocs.io/en/latest/index.html), for communicating with the FPGA over UART.
- [pyYAML](https://pyyaml.org/), for parsing configuration files written in YAML.
- [pyVCD](https://github.com/westerndigitalcorporation/pyvcd), for writing waveforms captured by the Logic Analyzer Core to standard Value Change Dump (VCD) files.
- macOS/Linux/BSD: `$HOME/.local/bin`, or `path\to\venv\bin` if using a virtual environment.
As well as these dependencies for development, which are installed with the `[dev]` argument:
- [Pytest](https://pytest.org/), for unit testing.
- [Black](https://black.readthedocs.io/en/stable/), for formatting the Python source.
- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/), for generating the documentation site.
- [amaranth_boards](https://github.com/amaranth-lang/amaranth-boards), for building designs for hardware-in-the-loop testing done by the CI.
This also adds any other Python scripts exposed by your installed packages to your PATH.

15
doc/repository_structure.md
View File

@ -1,15 +0,0 @@
## Repository Structure
- `src/manta/` contains the Python source needed to generate and run the cores.
- `test/` contains Manta's tests, which are a mix of functional simulations and hardware-in-the-loop testing. These tests leverage the `pytest` testing framework.
- `doc/` contains the documentation you're reading right now!
- `examples/` contains examples of Manta being used in designs for a handful of FPGA boards.
- `.github/` contains GitHub Actions workflows for automatically running the tests and building the documentation site on every commit.
## Tools Used
- The [YosysHQ](https://github.com/YosysHQ) tools and [Vivado](https://www.xilinx.com/products/design-tools/vivado.html) are used for building bitstreams.
- [draw.io](https://app.diagrams.net/) is used for block diagrams.
- [GitHub Pages](https://pages.github.com/) is used to serve the documentation site, which is built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
- [GitHub Actions](https://docs.github.com/en/actions) is used for continuous integration.
## GitHub Actions Setup
Since Vivado is large and requires individual licenses, it is run on a private server, which is configured as a self-hosted runner in GitHub Actions. This is a virtual server hosted with KVM/QEMU and managed by libvirt, which is configured as transient so that it reloads its state from a snapshot periodically. A Nexys4 DDR and Icestick are connected to the physical machine and passthrough-ed to this VM so that continuous integration can check against real hardware.

6
doc/alternatives.md → doc/similar_tools.md
View File

@ -1,4 +1,8 @@
There's quite a few FPGA debugging tools out there, and it may happen that your needs are better met by another tool! This section aims to provide a list of alternatives, in hopes that you're able to be confident in your debugging flow.
This page contains a list of tools similar to Manta, either in function or intention. This is meant to provide a useful comparison to other tools that you may be more familiar with, in hopes of a smoother experience integrating Manta into your project.
That said, Manta is by no means feature-complete, and there may be an alternative tool listed on this page that better fits your use case. If that is the case, we encourage you to use that tool (although do consider filing a [feature request](https://github.com/fischermoseley/manta/issues/new) - we’d love to hear about your workflow!). The goal of this project is to make working with FPGAs easier, and maintaining this list serves that end.
If you're aware of a tool missing from this list, please [let us know](https://github.com/fischermoseley/manta/issues/new)!
## Open Source Tools

2
mkdocs.yml
View File

@ -70,7 +70,7 @@ nav:
- Home: index.md
- Installation: installation.md
- Getting Started: getting_started.md
- Alternatives: alternatives.md
- Similar Tools: similar_tools.md
- Architecture: architecture.md
- Usage:
- IO Core: io_core.md