Updated READMEs.

Author: ribesstefano

README.md

@@ -6,26 +6,13 @@ This project includes the HLS implementation and the approximation algorithms in
 
 ### SVD Approximation Algorithm
 
-The bot AI is trained in Google Colab following the notebook in `ai/` folder.
-
-### Hardware
-
-The hardware part was implemented in Vivado High Level Synthesis (HLS) C++. It exploits Xilinx OpenCV libraries for resizing and stream the video frames generated by the game.
-
-#### Pong Game Cosimulation
-
-#### OpenCV Cosimulation
-
-#### HDMI Modules
-
-For instantiating the HDMI IPs, please follow this [guide](https://forums.xilinx.com/t5/Design-and-Debug-Techniques-Blog/Video-Series-23-Generate-a-video-output-on-Pynq-Z2-HDMI-out/ba-p/932553).
-
-#### Vivado Project
+The approximation algorithms are in the `python/` folder.
 
 ## Requirements
 
 * CMake
-* Xilinx Vivado 2018.3
+* Xilinx Vivado 2018.3 (deprecated)
+* Xilinx Vitis 2021.1 (deprecated)
 
 ### CMake Simulation
 
@@ -47,34 +34,29 @@ cmake ..
 make all
 ```
 
-## Notes on Using Vitis
+## Notes on Using Vitis HLS
 
 ### AXIS Interface and DMA
 
-Vitis to include the TLAST side channel if and only if TKEEP and TSTRB are also included.
+Vitis will include the TLAST side channel if and only if TKEEP and TSTRB are also included.
 
 In order to attach the port to a Xilinx DMA, the TLAST signal must be properly set HIGH at the end of the data transmission.
 
 The TKEEP and TSTRB signals must be *always* set to HIGH, as indicated in the [AXIS documentation](https://developer.arm.com/documentation/ihi0051/a/Interface-Signals/Byte-qualifiers/TKEEP-and-TSTRB-combinations).
 
+Note: for using external DMAs, we need the TLAST, TKEEP and TSTRB signals. In particular, TKEEP and TSTRB must be all set (i.e. all ones) in order to signal data packets.
 
-### Partitioning hls::vector Arrays
+#### AxiStreamInterface Class
 
-A standard way of partitioning an array is:
-```c++
-  hls::stream<hls::vector<int, 4> > x_streams[M][N];
-#pragma HLS ARRAY_PARTITION variable=x_streams complete dim=0
-```
-However, since we are dealing with a `hls::vector` type, setting `dim=0` (all dimensions) will partition the array on the vector dimension too.
+This repository contains a wrapper class for kernel arguments of type `hls::stream` named `AxiStreamInterface`. The class is implemented following a _Policy-based_ C++ paradigm, meaning that it accepts either a `AxiStreamPort` or `AxiStreamFifo` as possible policies (in practice, a template argument).
 
-In the example above, Vitis will create `M * N * 4` different streams (instead of just `M * N`). To fix it, manually specify the partitioning on the dimensions, like so:
-```c++
-  hls::stream<hls::vector<int, 4> > x_streams[M][N];
-#pragma HLS ARRAY_PARTITION variable=x_streams complete dim=1
-#pragma HLS ARRAY_PARTITION variable=x_streams complete dim=2
-```
+The idea is to have a kernel argument, i.e. an HLS port, which can be either an AXIS interface with side-channels, or a bare FIFO interface connected to another kernel. In fact, Vitis HLS doesn't allow stream interfaces with side-channels within an IP. To overcome the issue, the `AxiStreamInterface` can be customized to be an IP port or a FIFO port, depending on the use of the kernel.
+
+An example of this can be seen in `HlsKernelU` and in `svd::SvdKernel`, which specialize the `svd::KernelU` function template. In the first case, the `svd::KernelU` has its output stream port `xu_port` connected to one of the IP's ports (with side-channels). In the latter case instead, `svd::KernelU` is connected to `svd::KernelS`, and so its `xu_port` argument is an internal FIFO (without side-channels).
+
+The `AxiStreamInterface` class in `axis_lib.h` can also be used with `hls::vector` types.
 
-### Implementing AXIS Interfaces
+### AXIS Interfaces and `depth`
 
 In order to implement AXIS interfaces, avoid using `depth` in the pragma, as follows:
 ```c++
@@ -87,17 +69,29 @@ void HlsVectorKernelU(hls::stream<ap_axiu<kAxiBitwidth, 0, 0, 0> >& x_port,
 	// ...
 }
 ```
-The type `ap_axiu` must now be used to generate AXIS with side channels. Note: for using external DMAs, we need the TLAST, TKEEP and TSTRB signals. In particular, TKEEP and TSTRB must be all set (i.e. all ones) in order to signal data packets.
+The type `ap_axiu` must now be used to generate AXIS with side channels.
 
-#### AxiStreamInterface Class
+## hls::vector Arrays on AXI-Lite Interfaces
 
-This repository contains a wrapper class for kernel arguments of type `hls::stream` named `AxiStreamInterface`. The class is implemented following a _Policy-based_ C++ paradigm, meaning that it accepts either a `AxiStreamPort` or `AxiStreamFifo` as possible policies (in practice, a template argument).
+In Vitis 2021.1 it **not** allowed to have `hls::vector` type arguments mapped to AXI-Lite interfaces.
+Instead, use a bare arrays, *e.g.* `const int x[N]` instead of `const hls::vector<int, N> x`.
 
-The idea is to have a kernel argument, i.e. an HLS port, which can be either an AXIS interface with side-channels, or a bare FIFO interface connected to another kernel. In fact, Vitis HLS doesn't allow stream interfaces with side-channels within an IP. To overcome the issue, the `AxiStreamInterface` can be customized to be an IP port or a FIFO port, depending on the use of the kernel.
 
-An example of this can be seen in `HlsKernelU` and in `svd::SvdKernel`, which specialize the `svd::KernelU` function template. In the first case, the `svd::KernelU` has its output stream port `xu_port` connected to one of the IP's ports (with side-channels). In the latter case instead, `svd::KernelU` is connected to `svd::KernelS`, and so its `xu_port` argument is an internal FIFO (without side-channels).
+### Partitioning hls::vector Arrays
 
-The `AxiStreamInterface` class in `axis_lib.h` can also be used with `hls::vector` types.
+A standard way of partitioning an array is:
+```c++
+  hls::stream<hls::vector<int, 4> > x_streams[M][N];
+#pragma HLS ARRAY_PARTITION variable=x_streams complete dim=0
+```
+However, since we are dealing with a `hls::vector` type, setting `dim=0` (all dimensions) will partition the array on the vector dimension too.
+
+In the example above, Vitis will create `M * N * 4` different streams (instead of just `M * N`). To fix it, manually specify the partitioning on the dimensions, like so:
+```c++
+  hls::stream<hls::vector<int, 4> > x_streams[M][N];
+#pragma HLS ARRAY_PARTITION variable=x_streams complete dim=1
+#pragma HLS ARRAY_PARTITION variable=x_streams complete dim=2
+```
 
 ### HLS Vector Patch
 
@@ -118,37 +112,16 @@ std::cout << "Number of elements in a: " << a::width << std::endl;
 // > Number of elements in a: 5
 ```
 
-## Notes on PYNQ Design
-
-### Vivado Project
-
-#### Xilinx DMA
-
-The DMA should be configured in the following way:
-
-* Max burst length to maximum
-* Register buffer width to maximum
-
-#### HP Ports
-
-All HP ports should be set to 64bit width (to avoid receiving data interleaved by zeroes).
-
-
 ## TODOs
 
 List of TODOs:
 
+	* Properly test the pruned versions of Kernel-U and Kernel-V.
 	* ~Import u, s, v new kernels~
-	* ~Import (and clean up?) u, s, v old kernels~
-	* ~Import DMA functions~
-	* ~Import and clean up HLS SVD-model-Bouganis~
-	* ~Import and clean up HLS SVD-model-2LSTM~
-	* ~Import some testbenches to try compile something~
 
 ## Bugs
 
 List of possible bugs:
 
 * Constructing data handler storage might lead to segmentation faults.
-* Having `R == 1` might trigger some asserts.
-* Having `output_size == H` in HlsKernelV might break hardware runs.
+* Having `num_active_inputs == 1` is breaking in hardware runs.

pynq/README.md

@@ -0,0 +1,47 @@
+# Notes on PYNQ Designs
+
+## Vivado Project
+
+### Xilinx DMA
+
+The DMA should be configured in the following way:
+
+* Max burst length to maximum
+* Register buffer width to maximum
+
+### HP Ports
+
+All HP ports should be set to their maximum size width (64bit for the PYNQ-Z1 board and 128bit for the ZCU104) in order to avoid receiving data interleaved by zeroes.
+
+## Jupyter Notebook
+
+### Generating Randomly-filled Buffer
+
+```python
+import numpy as np
+
+R, N, G = 64, 2, 4
+
+xus = np.random.randn(R, N, G).astype(dtype=np.int16)
+xus_buffer = pynq.allocate(shape=(R, N, G), dtype=np.int16)
+np.copyto(xus_buffer, xus, casting='no')
+```
+
+### Storing and Loading Weights from bin file
+
+```python
+import numpy as np
+
+R, N, G = 64, 2, 4
+
+tmp = np.random.randn(R, N, G).astype(dtype=np.int16)
+tmp.tofile('binfile_example.bin')
+
+def load_from_bin(binfile, shape, dtype):
+    tmp_buffer = pynq.allocate(shape=shape, dtype=dtype)
+    tmp = np.fromfile(binfile, dtype=data_t).reshape(tmp_buffer.shape)
+    np.copyto(tmp_buffer, tmp, casting='no')
+    return tmp_buffer
+
+xus_buffer = load_from_bin('binfile_example.bin', shape=(R, N, G), dtype=np.int16)
+```