do a pass over all the docs

Author: maltanar

doc/hardware.md

@@ -75,4 +75,4 @@ This will produce a file `CharacterizePC.log` with the results.
 Completing the characterization will take some time depending on the range of
 parameters.
 To change the range of parameters for characterization, see the
-`makeParamSpace` functions under `CharacterizeMain`.
+`makeParamSpace` functions under `CharacterizeMain` in `src/main/scala/MainCharacterize.scala`.

doc/platforms.md

@@ -1,5 +1,9 @@
 # Platforms, Build and Deployment
 
+BISMO assumes that the hardware design and supporting files are first prepared
+on a *host*, and then deployed on a *target*. These may be the same computer in
+some cases.
+
 ## Deployment
 
 In general, each supported platform may do deployment slightly differently,
@@ -11,6 +15,10 @@ but all current BISMO platforms do this in a similar manner:
 4. User flashes the bitfile
 5. User runs the test application (or their own application)
 
+All generated files during build are placed under a directory whose path
+reflects the current platform and configuration, see `BUILD_DIR` in Makefile
+variables below. The deployment folder is generated at `$BUILD_DIR/deploy`.
+
 ## Useful Make targets and variables
 
 BISMO involves a somewhat complex hardware-software build, which is currently managed using the top-level `Makefile`. Below are some of the useful variables and targets.
@@ -26,6 +34,7 @@ BISMO involves a somewhat complex hardware-software build, which is currently ma
 | `N` | RHS parallelism for overlay; see Dn in BISMO paper | 2 |
 | `LMEM` | Number of entries in LHS memory; see Bm in BISMO paper | 1024 |
 | `RMEM` | Number of entries in RHS memory; see Bn in BISMO paper | 1024 |
+| `BUILD_DIR` | Build directory for current BISMO instance | build/$(OVERLAY_CFG)/$(PLATFORM) |
 
 ### Make targets
 

doc/software.md

@@ -67,7 +67,14 @@ available (determined by the platform) will also limit the maximum size.
 
 ## Under the Hood
 
+This section is quite thin on content at the moment, contributions are welcome!
 
+### The runtime
+
+The runtime is spread across several files under
+`src/main/resources/lib/` all prefixed with `bismo_rt_`. Most of the runtime
+is a thin wrapper around the functionality already provided by the low-level
+driver, plus some "added value" for instrumentation and data movement.
 
 ### The low-level driver
 
@@ -83,15 +90,4 @@ One level under this low-level driver is the register driver
 `BitSerialMatMulAccel.hpp` which is generated automatically by
 [fpga-tidbits
 PlatformWrapper](https://github.com/maltanar/fpga-tidbits/wiki/platformwrapper).
-
-
-
-BISMO overlays are programmable via the instructions listed in the paper,
-although full compiler support is lacking at this point.
-A rudimentary software stack can be found under `src/main/cpp/app`, which
-consists of the following:
-
-
-
-* `BISMOTests.hpp` contains the top-level test code, which also serve as
-usage examples. It uses `BitSerialMatMulExecutor` calls.
+You can find this file under `$BUILD_DIR/hw/driver`.

doc/testing.md

@@ -13,7 +13,7 @@ indicating which mode to run in:
 * `i` to run interactive benchmarking
 * `b` to run batch-mode benchmarking
 
-## More (unit) tests
+## Unit tests
 Besides the top-level BISMO test described here, there are several
 other tests available for BISMO components under `src/test`.
 See [here](src/test/scala) for more on the pure Scala/Chisel tests, and