update bram docs

doc/block_memory.md

@@ -1,42 +1,40 @@
 
-## Usage
+## Overview
+Block Memory (also called Block RAM, or BRAM) is the de facto means of storing data on FPGAs when the space needed exceeds a few registers. As a result, Manta provides a Block Memory core, which instantiates a dual-port BRAM on the FPGA. One port is provided to the host, and the other is connected to your logic with the standard BRAM interface (`addr`, `din`, `dout`, `wea`). This allows the host to provide reasonably large amounts of data to user logic - or the other way around, or a mix of both!
 
+This is a very, very simple task - and while configuration is straightforward, there are a few caveats. More on both topics below:
 
-### Configuration
-The block memory core can be included in your configuration just like any other core. Only the `width` and `depth` parameters are needed:
+## Configuration
+
+Just like the rest of the cores, the Block Memory core is configured via an entry in a project's configuration file. This is easiest to show by example:
 
 ```yaml
 ---
 cores:
   my_block_memory:
     type: block_memory
-    width: 12 # (1)
+    width: 12
     depth: 16384
 
 ```
 
-1. If your BRAM is more than 16 bits wide, check out the section on [Synchronicity](#synchronicity) and make sure Manta's behavior is compatible with your project.
+There's a few parameters that get configured here, including:
 
-### Verilog
-Internally this creates a dual-port BRAM, connects one end to Manta's internal bus, and exposes the other to the user:
+- `name`: The name of the Block Memory core. This name is used to reference the core when working with the API, and can be whatever you'd like.
+- `type`: This denotes that this is a Block Memory core. All cores contain a `type` field, which must be set to `block_memory` to be recognized as an Block Memory core.
 
-```systemverilog
-manta manta_inst (
-    .clk(clk),
+### Dimensions
+The dimensions of the block memory are specified in the config file with the `width` and `depth` entries.
 
-    .rx(rx),
-    .tx(tx),
+Manta won't impose any limit on the width or depth of the block memory you instantiate, but since Manta instantiates BRAM primitives on the FPGA, you will be limited by what your FPGA can support. It helps to know your particular FPGA's architecture here.
 
-    .my_block_memory_clk(),
-    .my_block_memory_addr(),
-    .my_block_memory_din(),
-    .my_block_memory_dout(),
-    .my_block_memory_we());
-```
+If your BRAM is more than 16 bits wide, check out the section on [Synchronicity](#synchronicity) and make sure your project will tolerate how Manta writes to the block memory.
 
-Which are free to connect to whatever logic the user desires.
 
-### Python
+### Python API
+
+The Block Memory core functionality is stored in the `Manta.IOCore` and `Manta.IOCoreProbe` classes in [src/manta/io_core/\_\_init\_\_.py](https://github.com/fischermoseley/manta/blob/main/src/manta/io_core/__init__.py), and it may be controlled with the two functions:
+
 Just like with the other cores, interfacing with the BRAM with the Python API is simple:
 
 ```python

doc/io_core.md

@@ -50,7 +50,7 @@ manta manta_inst (
 
 ## Python API
 
-The IO core functionality is stored in the `Manta.IOCore` and `Manta.IOCoreProbe` classes in [src/manta/io_core/__init__.py](https://github.com/fischermoseley/manta/blob/main/src/manta/io_core/__init__.py), and it may be controlled with the two functions:
+The IO core functionality is stored in the `Manta.IOCore` and `Manta.IOCoreProbe` classes in [src/manta/io_core/\_\_init\_\_.py](https://github.com/fischermoseley/manta/blob/main/src/manta/io_core/__init__.py), and it may be controlled with the two functions:
 
 `Manta.IOCoreProbe.set(int, bool data)`
 

doc/logic_analyzer.md

@@ -29,7 +29,7 @@ cores:
 There's a few parameters that get configured here, including:
 
 - `name`: The name of the Logic Analyzer core. This name is used to reference the core when working with the API, and can be whatever you'd like.
-- `type`: This denotes that this is a Logic Analyzer core. All cores contain a `type` field, which must be set to `logic_analyzer` to be recognized as an IO core.
+- `type`: This denotes that this is a Logic Analyzer core. All cores contain a `type` field, which must be set to `logic_analyzer` to be recognized as an Logic Analyzer core.
 
 ### Sample Depth
 This refers to the number of samples saved in the capture, and is set with the `sample_depth` entry in the config file. A larger sample depth will use more resources, but show what your probes are doing over a longer time.
@@ -132,7 +132,9 @@ This is useful for two situations in particular:
 - _Sparse Sampling_ Sometimes designs will have a small number of inputs, but a huge amount of internal state. In situations like these, it may be more effecient to sample the inputs and simulate the logic, instead of directly sampling the state. For instance, debugging a misbehaving branch predictor in a CPU can be done by recording activity on the address and data busses and playing them back in simulation - which would use less BRAM than sampling the entire pattern history table.
 
 ## Python API
+The Logic Analyzer core functionality is stored in the `Manta.LogicAnalyzerCore` class in [src/manta/la_core/\_\_init\_\_.py](https://github.com/fischermoseley/manta/blob/main/src/manta/la_core/__init__.py).
 
+At present, this class contains methods used really only for capturing data, and exporting `.vcd` and `.mem` files. It'd be super handy to expose the data from the logic analyzer core in a Pythonic way - which is why the feature is on the [roadmap](roadmap.md)!
 
 ## How It Works
 The Logic Analyzer Core's implementation on the FPGA consists of three primary components:

doc/roadmap.md

@@ -3,13 +3,19 @@
 ## Prior to v1.0.0 release:
 _targeting August 2023_
 
-- Clean up UART testbenches, make them actually test things
+- ~~Clean up UART testbenches, make them actually test things~~
 - Pull text from thesis into documentation site
-- Update docs with API reference
-- Make super super sure everything works (need hardware for that)
+- Add API reference to documentation site
 - Port logic analyzer examples to the icestick
-- __IO Core:__ Clock domain crossing, check that >16 bit probes work
-- __Logic Analyzer Core:__ CDC, trigger modes, external trigger
+    - This requires refactoring the block memory core to use unpacked arrays, since Yosys doesn't support packed arrays.
+- Add method for dumping logic analyzer data to Python
+- Add clock domain crossing to IO core
+- Verify that >16 bit probes work on IO core
+- Add clock domain crossing to Logic Analyzer Core
+- Verify that capture modes work on the Logic Analyzer Core
+- Verify that external triggers work on the Logic Analyzer Core
+- Add global AND/OR to Logic Analyzer Core
+- Make super super sure everything works (need hardware for that)
 
 ## Prior to v1.1.0 release:
 - Fix Ethernet packet format

mkdocs.yml

@@ -54,6 +54,7 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.superfences
+  - pymdownx.tilde
 
 nav:
     - Home: index.md