From dcffb55710a0224b56a25d763ad53fa828ac2aed Mon Sep 17 00:00:00 2001 From: Fischer Moseley <42497969+fischermoseley@users.noreply.github.com> Date: Thu, 16 Mar 2023 12:49:21 -0400 Subject: [PATCH] update docs and readme --- README.md | 30 +----------------------------- doc/todo.md | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 29 deletions(-) create mode 100644 doc/todo.md diff --git a/README.md b/README.md index eeb26e0..1f1e352 100644 --- a/README.md +++ b/README.md @@ -9,32 +9,4 @@ Manta is a tool for debugging FPGA designs over an interface like UART or Ethern Manta is written in Python, and generates Verilog-2001 HDL. It's cross-platform, and its only dependencies are pySerial and pyYAML. -## Cores - -### Logic Analayzer Core -Manta's downlink mode works by taking a YAML/JSON file describing the ILA configuration, and autogenerating a debug core with SystemVerilog. This gets included in the rest of the project's HDL, and is synthesized and flashed on the FPGA. It can then be controlled by a host machine connected over a serial port. 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. - -This is similar to Xilinx's Integrated Logic Analyzer (ILA) and Intel/Altera's SignalTap utility. - -### I/O Core - -### LUT RAM Core - -### BRAM Core - - -## Getting Started -Manta is installed with `pip3 install mantaray`. Or at least it will be, once it's out of alpha. For now, it's installable with `pip install -i https://test.pypi.org/simple/ mantaray`, which just pulls from the PyPI testing registry. - -## Examples -Examples can be found under `examples/`. These target the Xilinx Series 7 FPGAs on the [Nexys A7](https://digilent.com/reference/programmable-logic/nexys-a7/start)/[Nexys4 DDR](https://digilent.com/reference/programmable-logic/nexys-4-ddr/start) and the Lattice iCE40 on the [Icestick](https://www.latticesemi.com/icestick). - -## Design Philosophy -- Things that are easy to break should be easy to fix. For instance, it's pretty easy to put the wrong number of clock cycles of holdoff in your configuration, but it's a lot harder to accidentally put the wrong number of stop bits in your serial port. Manta supports changing the former post-upload, but not the latter. -- Features are added when they're needed. We won't add features until there's been a use case shown that would benefit from them. This keeps manta lightweight. -- Trust the interface. In the name of simplicity, we don't implement a ton of error checking. If this proves to be a problem, we'll fix it, inline with the philosophy above. -- Don't use macros - there's a possibility that they'll conflict with something in user code. -- Use Verilog 2001 for source for compatibility. Manta uses SystemVerilog 2012 for simulation and test, however. - -## About -Manta was originally developed as part of my [Master's Thesis at MIT](dspace.mit.edu) in 2023, done under the supervision of Joe Steinmeyer. But I think it's a neat tool, so I'm still working on it :) \ No newline at end of file +For more information check out the docs at [https://fischermoseley.github.io/manta](https://fischermoseley.github.io/manta) \ No newline at end of file diff --git a/doc/todo.md b/doc/todo.md new file mode 100644 index 0000000..bdd3588 --- /dev/null +++ b/doc/todo.md @@ -0,0 +1,39 @@ +## IO Core +- add interface read/write to python +- test examples that build +- update IO core read/write memory handling to be less ugly +- add logic for ports >16 bits in width +- figure out what happens for module naming - it's possible we could have two modules that have the same ports but have different names + - do we say that port names have to be globally unique? or do we allow something like `module_name_module_type_inst` for example + +## Logic Analyzer Core +- need to finish up simulations, those might get broken out into separate testbenches for each module +- need to write tests - this will be hard because there's no template to go off of, so need to autogenerate before running tests + +## BRAM Core +- write HDL +- write tests +- write interface + +## Python API +- find a better way of handling tabs +- make finding a serial port possible even if no cores are configured +- make autodetecting and automatically selecting a serial device possible + - if we see a FT2232 on the device we should grab it + +## Documentation +- Move stuff out of readme.md and into the docs front page - right now information is duplicated +- Write out what technologies are being used here (iverilog for sim, gtkwave for vcd, makefile for simulation/lint/pushing to pypi, github actions for automated test and building the doc site, python for autogeneration, verilator for lint. for docs, mkdoc-material for the site, wavedrom for timing diagrams and draw.io for block diagrams) +- Write out where stuff is being stored - `test/` contains all the systemverilog testbenches, `src/manta` contains all verilog and python needed to generate and run the cores, `doc/` contains the documentation site source files, `.github/` contains the github actions config, `examples/` is exactly what it sounds like + +- Write out the anatomy of manta.v and how `Manta` generates that +- Write out what methods need to be implemented for Manta.generate_hdl() to actually be able to pick up on the cores +- Write out what bus transactions look like and how messages get passed. probably going to need wavedrom for this. + +## Testing +- need to add tests for the python itself - does it recognize bad yaml files and produce the right errors when trying to build from them? are good manta files synthesizeable? +- try doing literally anything on Windows lol + +## Meta +- probably want to make all the manta source pass verilator lint - doesn't look like this would be too hard to do +- maybe install local github actions runner to ubuntu/macos/linux VM with boards attached to it or something - just to make sure that examples actually work for real \ No newline at end of file