Merge pull request #21 from MicrochipTech/rc2024_2

Update of SmartHLS libraries for Libero/SmartHLS 2024.2 release

Author: ManuelSaldana

.gitignore

@@ -0,0 +1,11 @@
+**/hls_output
+.vscode
+**/riscv_tests/master_example/discovery_kit/work
+**/riscv_tests/master_example/**/component
+**/riscv_tests/sin_performance/discovery_kit/work
+**/riscv_tests/sin_performance/**/component
+**/__pycache__
+**/math/**/master_example/build
+**/math/examples/**/*_reports
+vision/demo_designs/PF_Video_kit/libero/vision_pipeline
+vision/demo_designs/PF_Video_kit/libero/component

.gitmodules

@@ -1,3 +1,9 @@
 [submodule "support/miv/platform"]
 	path = support/miv/platform
 	url = https://github.com/Mi-V-Soft-RISC-V/platform.git
+[submodule "support/beaglev-fire/gateware"]
+	path = support/beaglev-fire/gateware
+	url = https://openbeagle.org/jennifermah76/gateware.git
+[submodule "support/discovery_kit/polarfire-soc-discovery-kit-reference-design"]
+	path = support/discovery_kit/polarfire-soc-discovery-kit-reference-design
+	url = git@github.com:ManuelSaldana/polarfire-soc-discovery-kit-reference-design.git

README.md

@@ -1,10 +1,17 @@
 # Microchip SmartHLS Libraries
 
-Microchip currently provides two open source libraries that complement and expand the functionality of the SmartHLS tool: the [SmartHLS Vision Library](vision), and the [SmartHLS Fixed-Point Math Library](math). These libraries are currently in active development. To use the libraries, you should first install the SmartHLS tool, which is part of the [Libero SoC Design Suite](https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/fpga/libero-software-later-versions).
- 
-  `Note: This release of the library is designed to work on the latest Libero SoC Design Suite version, 2024.1, and may not be compatible with previous versions of Libero and SmartHLS.`
+Microchip provides open source libraries that complement and expand the functionality of the SmartHLS tool. Currently, the available libraries are:
 
-A stable copy of the libraries is included with the SmartHLS installer under the `<PATH TO SMARTHLS INSTALLATION>/SmartHLS/smarthls-library/external` directory. The snapshot of the library is taken at the time when SmartHLS is released, while the Github version can include bug fixes and new functionality that may not be present in the installed copy.
+- [SmartHLS Vision Library](vision)
+- [SmartHLS Fixed-Point Math Library](math)
+- [SmartHLS DSP Library](dsp)
+
+These libraries are currently in active development therefore expect changes in their definition and functionality included. To use the libraries, you should first install the SmartHLS tool, which is part of the [Libero SoC Design Suite](https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/fpga/libero-software-later-versions).
+
+**NOTEs**:
+
+- The main branch of the library repo is designed to work on the latest Libero SoC Design Suite version, and may not be compatible with previous versions of Libero and SmartHLS.  Check the [releases](https://github.com/MicrochipTech/fpga-hls-libraries/releases) page for older versions.
+- A stable copy of the libraries is included with the SmartHLS installer under the `<PATH TO SMARTHLS INSTALLATION>/SmartHLS/smarthls-library/external` directory. The snapshot of the library is taken at the time when SmartHLS is released, while the GitHub version can include bug fixes and new functionality that may not be present in the installed copy.
 
 ## Setup
 
@@ -19,15 +26,16 @@ To use the latest version of the library, users should clone the library from Mi
     This is because Windows OS has a 256-character path length limit.
     Some files generated by Libero project deep down under the repository's directory structure can go over the path limit.
   - Here are the commands:
+
     ```console
-    > cd <DIRECTORY TO CLONE THE LIBRARY INTO>
-    > git lfs install
-    > git clone --recurse-submodules https://github.com/MicrochipTech/fpga-hls-libraries.git
-    > git lfs pull
+    cd <DIRECTORY TO CLONE THE LIBRARY INTO>
+    git lfs install
+    git clone --recurse-submodules https://github.com/MicrochipTech/fpga-hls-libraries.git
+    git lfs pull
     ```
-    
+
 - Next, update any existing designs that use the libraries to include the path where the libraries have been cloned. This can be done by adding `USER_CXX_FLAG+=-I/path/to/cloned/library` to your Makefile.
 
-- If you would like to use the vision library, after clonning the repository please make sure to setup the **OpenCV** and **FFMPEG** pre-compiled libraries first as described in this link: [vision/precompiled_sw_libraries](vision/precompiled_sw_libraries). 
-   - These libraries are also included with the latest release of SmartHLS, under `<PATH TO SMARTHLS INSTALLATION>/SmartHLS/smarthls-library/external/vision/precompiled_sw_libraries`. 
-  
+- If you would like to use the vision library, after clonning the repository please make sure to setup the **OpenCV** and **FFMPEG** pre-compiled libraries first as described in this link: [vision/precompiled_sw_libraries](vision/precompiled_sw_libraries).
+
+  - These libraries are also included with the latest release of SmartHLS, under `<PATH TO SMARTHLS INSTALLATION>/SmartHLS/smarthls-library/external/vision/precompiled_sw_libraries`.

dsp/README.md

@@ -0,0 +1,40 @@
+# SmartHLS DSP Library
+
+<!-- TOC -->
+
+- [SmartHLS DSP Library](#smarthls-dsp-library)
+  - [Overview](#overview)
+  - [Directory structure](#directory-structure)
+  - [Functions](#functions)
+
+<!-- /TOC -->
+## Overview
+
+The SmartHLS DSP includes C++ functions that facilitate the rapid development of applications that require common DSP functionality. Applications developed using the SmartHLS DSP library can be seamlessly ported across various Microchip FPGA platforms, significantly reducing time to market.
+
+By open-sourcing the DSP library, we aim to introduce new features and fixes more rapidly and provide the source code as a reference for developers working on other HLS designs. We encourage all developers to contribute by reporting issues, providing feedback, and submitting feature requests through the "Issues" section. Additionally, we welcome contributions of new algorithms and fixes to enhance this open-source repository.
+
+## Directory structure
+
+Below is the directory structure of the DSP library and each sub-directory's respective content.
+Please see the readme files in sub-directories for more details.
+
+- [docs](./docs/): Documentation for the DSP HLS C++ Library.
+  - [graphs](./docs/graphs/): Graphs that are used in .md files
+  - [md](./docs/md/): folder containing .md files for each DSP function.
+- [include](include/): The header files of the DSP HLS C++ library.
+- [utils](utils/): Python scripts that are used for various purposes.
+- [examples](examples/): Examples showcasing the usage of the DSP HLS C++ library
+  - [riscv_tests](./examples/riscv_tests/): Directory containing examples using the RISC-V CPUs and FPGA fabric for different boards.
+    - [fft_demo](./examples/riscv_tests/fft_demo/): Directory containing the FFT demo for different boards.
+      - [icicle_kit](./examples/riscv_tests/fft_demo/icicle_kit/): Project files for the Icicle Kit
+      - [discovery_kit](./examples/riscv_tests/fft_demo/discovery_kit/): Project files for the Discovery kit.
+      - [beaglev_fire](./examples/riscv_tests/fft_demo/beaglev_fire/): Project files for the BeagleV-Fire board.
+  - [simple](./examples/simple/): Directory containing test programs for each DSP function.
+    - [fft](./examples/simple/fft/): Simple test program for FFT
+
+## Functions
+
+| Function                             | Description                                      | 
+|--------------------------------------|--------------------------------------------------|
+| [fft](docs/md/fft.md)            | Radix 2, 256 samples, in-place FFT               |

dsp/docs/graphs/fft_test10_graph.png

@@ -0,0 +1,16 @@
+{ "signal" : [
+  { "name": "clk",        "wave": "p.......|............|......." },
+  { "name": "start",      "wave": "010.....|.....10.....|.......", "node" : ".j............k"},
+  { "name": "ready",      "wave": "010.....|.....10.....|......."},
+  { "name": "finish",     "wave": "0.......|.....10.....|.....10", "node": '..............b............d'},
+  { "name": "in_en",      "wave": "0..1...0|.......1...0|......."},
+  { "name": "in_data",    "wave": "x..==22x|.......==22x|.......", "data":["a0", "a1", "...", "an-1","b0", "b1", "...", "bn-1"]},
+  { "name": "out_en",     "wave": "0.......|1...0.......|1...0..", "node": '.............a............c'},
+  { "name": "out_data",   "wave": "x.......|====x.......|====x..", "data":["A0", "A1", "...", "An-1", "B0", "B1", "...", "Bn-1"]},
+  {                              "node": '.l............m' },
+],
+"edge": ['a-~>b', 'c-~>d', 'j-l', 'k-m', 'l<->m Call Latency'],
+"head": {
+  "text": "In-place FFT"
+}
+}

dsp/docs/graphs/fft_test3_graph.png

@@ -0,0 +1,83 @@
+## [`fft`](../../include/hls_fft.hpp)
+
+## Table of Contents:
+
+**Functions**
+
+> [`inplace_fft`](#function-inplace_fft)
+
+**Examples**
+
+> [Examples](#examples)
+
+**Quality of Results**
+
+> [Error Graph](#error-graph)
+
+> [Resource Usage](#resource-usage)
+
+### Function `fft`
+~~~lua
+template <unsigned SIZE>
+void fft(hls::FIFO<fft_data_t>& fifo_in, hls::FIFO<fft_data_t>& fifo_out)
+~~~
+
+Compute the FFT. Note that fft_data_t type is defined as:
+```cpp
+struct fft_data_t {
+ap_int<16> im;
+ap_int<16> re;
+};
+```
+![timing_diagram](../graphs/in-place-fft-timing.PNG)
+
+
+**Template Parameters:**
+
+* `unsigned SIZE`: the FFT transform size<br>
+
+**Function Arguments:**
+
+* `hls::FIFO<fft_data_t>& fifo_in`: reference to the input fifo, where the depth must match the FFT size<br>
+* `hls::FIFO<fft_data_t>& fifo_out`: reference to the output fifo, where the depth must match the FFT size<br>
+
+**Limitations:**
+
+* The fft function currently only supports the radix-2, 256-point, forward inplace FFT implementation.
+
+**Returns:**
+
+No return.
+
+## Examples
+
+~~~lua
+hls::dsp::fft<SIZE>(fifo_in, fifo_out);
+~~~
+
+The example used to gather the following graph and resource report can be found [here](../../examples/simple/fft).
+
+## Error Graph
+
+![fft_test10](<../graphs/fft_test10_graph.png>)
+
+![fft_test3](<../graphs/fft_test3_graph.png>)
+
+![fft_test4](<../graphs/fft_test4_graph.png>)
+
+## Resource Usage
+
+Using MPF300
+
+Size:256_Radix:2_forward_inplace
+
+
+| Name        | Latency [cycles] (min/max/avg)   | II [cycles] (min/max/avg)   |   Real Avg Error |   Real Max Error |   Imaginary Avg Error |   Imaginary Max Error |   LUTs |   DFFs |   DSPs |   LSRAM |   uSRAM | Estimated Frequency   |
+|-------------|----------------------------------|-----------------------------|------------------|------------------|-----------------------|-----------------------|--------|--------|--------|---------|---------|-----------------------|
+| inplace_fft | 2,718 / 2,718 / 2,718.00         | 2,718 / 2,718 / 2,718.00    |          1.15234 |                4 |                1.0625 |                     4 |   2387 |   2412 |      6 |       4 |       0 | 259.673 MHz           |
+
+Notes:
+- Targeted FMax was 400MHz.
+
+
+Back to [top](#).

dsp/docs/graphs/fft_test4_graph.png

@@ -0,0 +1,18 @@
+NAME = shls_test
+LOCAL_CONFIG = -legup-config=config.tcl
+SRCS = ../sources/demo.cpp
+
+# Root directory path for the HLS libraries. Modify as necessary. 
+SHLS_LIBRARY_DIR = ../../../../..
+
+USER_CXX_FLAG += -I$(SHLS_LIBRARY_DIR)/dsp/include
+USER_CXX_FLAG += -O3 -pg -Wall -Wno-strict-aliasing -Wno-unused-label -Wno-unknown-pragmas -Wno-attributes 
+USER_CXX_FLAG += -I$(SHLS_ROOT_DIR)/smarthls-library 
+
+# BeagleV-Fire board only supports HLS_ALLOC_NONCACHED
+USER_CXX_FLAG += -DDDR_REGION=HLS_ALLOC_NONCACHED
+
+# AXI_TYPE: available options are:
+# - AXI_TARGET 
+# - AXI_INITIATOR (default)
+# USER_CXX_FLAG += -DAXI_TARGET

dsp/docs/graphs/in-place-fft-timing.PNG

@@ -1,12 +1,11 @@
 source $env(SHLS_ROOT_DIR)/examples/legup.tcl
 set_project PolarFireSoC MPFS025T-FCVG484E Icicle_SoC
 set_parameter POINTSTO_ANALYZE_HW_ONLY 1
+set_parameter SOC_POLL_DELAY 1
 
 #
 # Parameters used for SoC integration
 #
-## Note that SOC_BD_NAME must match the top_level_name in the configuration .yaml file.
-## For an example, see the build-options/sin_performance.yaml file in the BeagleV-Fire gateware repository.
 set_parameter SOC_BD_NAME                 shls_test
 set_parameter SOC_DMA_ENGINE              HARD_DMA
 set_parameter SOC_AXI_INITIATOR           BVF_RISCV_SUBSYSTEM:FIC_0_AXI4_INITIATOR

dsp/docs/inplace_fft.json

@@ -0,0 +1,12 @@
+---
+HSS:
+    type: git
+    link: https://git.beagleboard.org/beaglev-fire/hart-software-services.git
+    branch: develop-beaglev-fire
+    board: bvf
+gateware:
+    top_level_name: shls_test
+    build-args: "M2_OPTION:NONE CAPE_OPTION:NONE SMARTHLS:../../../../../dsp/examples/riscv_tests/fft_demo/beaglev_fire"
+    type: sources
+    unique-design-version:
+

dsp/docs/md/fft.md

@@ -0,0 +1,18 @@
+NAME = FFT
+LOCAL_CONFIG = -legup-config=config.tcl
+SRCS = ../sources/demo.cpp
+
+# Root directory path for the HLS libraries. Modify as necessary. 
+SHLS_LIBRARY_DIR = ../../../../..
+
+USER_CXX_FLAG += -I$(SHLS_LIBRARY_DIR)/dsp/include
+USER_CXX_FLAG += -O3 -pg -Wall -Wno-strict-aliasing -Wno-unused-label -Wno-unknown-pragmas -Wno-attributes 
+USER_CXX_FLAG += -I$(SHLS_ROOT_DIR)/smarthls-library 
+
+# Could be HLS_ALLOC_NONCACHED or HLS_ALLOC_CACHED
+USER_CXX_FLAG += -DDDR_REGION=HLS_ALLOC_NONCACHED
+
+# AXI_TYPE: available options are:
+# - AXI_TARGET 
+# - AXI_INITIATOR (default)
+# USER_CXX_FLAG += -DAXI_TARGET

dsp/examples/riscv_tests/fft_demo/beaglev_fire/Makefile

@@ -0,0 +1,25 @@
+source $env(SHLS_ROOT_DIR)/examples/legup.tcl
+set_project PolarFireSoC MPFS095T-1FCSG325E Icicle_SoC
+set_parameter SOC_POLL_DELAY 1 
+
+# Set other parameters and constraints here
+# Refer to the user guide for more information: https://onlinedocs.microchip.com/oxy/GUID-AFCB5DCC-964F-4BE7-AA46-C756FA87ED7B-en-US-11/GUID-3636C6BE-3977-4267-A5DF-A514D1A46BE3.html
+set_parameter CLOCK_PERIOD 5
+set_parameter MINIMIZE_MATH_BLOCKS 1
+#set_resource_constraint fp_extend 27 
+
+#
+# Parameters used for SoC integration
+#
+## The SOC BD NAME is hard coded in the pre integration script /shrug
+set_parameter SOC_BD_NAME                 FIC_0_PERIPHERALS
+set_parameter SOC_DMA_ENGINE              HARD_DMA
+set_parameter SOC_AXI_INITIATOR           AXI2AXI_TO_HLS:AXI4_MASTER
+set_parameter SOC_AXI_TARGET              AXI2AXI_FROM_HLS:AXI4_SLAVE
+set_parameter SOC_RESET                   ARESETN
+set_parameter SOC_CLOCK                   ACLK
+set_parameter SOC_FABRIC_BASE_ADDRESS     0x70000000
+set_parameter SOC_FABRIC_SIZE             0x400000
+set_parameter SOC_CPU_MEM_BASE_ADDRESS    0x80000000
+set_parameter SOC_CPU_MEM_SIZE            0x60000000
+

math/examples/riscv_tests/sin_performance/beaglev_fire/hls/config.tcl renamed to dsp/examples/riscv_tests/fft_demo/beaglev_fire/config.tcl

@@ -0,0 +1,38 @@
+#!/bin/bash
+#
+# Usage:
+#   ./run_libero.sh
+# Notes:
+#   This script will create a directory in your SHLS project directory, create a 
+#   working directory called "work", and copy in the Discovery Kit reference 
+#   design included in SHLS.
+
+set -e
+
+prjDir=soc
+HLS_PATH=$(pwd)
+
+#
+# Start from a clean state
+#
+rm -rf \
+    $HLS_PATH/hls_output \
+    work \
+    component
+
+# Copy the reference design files to the hls project directory
+mkdir work
+cp -r ../../../../../support/discovery_kit/polarfire-soc-discovery-kit-reference-design/ work
+cd work/polarfire-soc-discovery-kit-reference-design
+
+args=SMARTHLS:$HLS_PATH
+args+=+SYNTHESIZE
+args+=+PLACEROUTE
+args+=+VERIFYTIMING
+args+=+HSS_UPDATE:1
+args+=+EXPORT_FPE:$prjDir
+libero script:MPFS_DISCOVERY_KIT_REFERENCE_DESIGN.tcl \
+    script_args:$args \
+    logfile:disco_kit_sin_performance.log
+
+echo "ALL DONE"

dsp/examples/riscv_tests/fft_demo/beaglev_fire/fft_performance.yaml

@@ -0,0 +1,18 @@
+NAME = FFT
+LOCAL_CONFIG = -legup-config=config.tcl
+SRCS = ../sources/demo.cpp
+
+# Root directory path for the HLS libraries. Modify as necessary. 
+SHLS_LIBRARY_DIR = ../../../../..
+
+USER_CXX_FLAG += -I$(SHLS_LIBRARY_DIR)/dsp/include
+USER_CXX_FLAG += -O3 -pg -Wall -Wno-strict-aliasing -Wno-unused-label -Wno-unknown-pragmas -Wno-attributes 
+USER_CXX_FLAG += -I$(SHLS_ROOT_DIR)/smarthls-library 
+
+# Could be HLS_ALLOC_NONCACHED or HLS_ALLOC_CACHED
+USER_CXX_FLAG += -DDDR_REGION=HLS_ALLOC_NONCACHED
+
+# AXI_TYPE: available options are:
+# - AXI_TARGET 
+# - AXI_INITIATOR (default)
+# USER_CXX_FLAG += -DAXI_TARGET

dsp/examples/riscv_tests/fft_demo/discovery_kit/Makefile

@@ -0,0 +1,8 @@
+########## This file is automatically generated. Any changes to this file will be lost. ##########
+########## If you have your own constraints tcl file, please add it to the project ##########
+########## by using the "Set custom config file" constraint in the HLS Constraints dialog. ##########
+source $env(SHLS_ROOT_DIR)/examples/legup.tcl
+set_project PolarFireSoC MPFS250T Icicle_SoC
+
+set_parameter CLOCK_PERIOD 10
+set_parameter SOC_POLL_DELAY 1