Squashed 'utils' changes from 9fb2945..4eff91b (#738)

4eff91b Merge pull request Xilinx#292 from tuol/update_dm_name
9b0299c update
e8b5b5f Merge pull request Xilinx#291 from tuol/add_perf_doc
ca2c56a add perf data of 4d DM
f5d6bc9 Merge pull request Xilinx#290 from tuol/fix_dm_doc
4d5056e update doc for 4D datamover
1dc9899 Merge pull request Xilinx#289 from RepoOps/update_readme_5
0e4c644 update
0fc8870 update README
32b471c update README
4ed37e1 Merge pull request Xilinx#288 from tuol/cr_1143159
eeb9c9e add freq constrain
c6adb44 Merge pull request Xilinx#287 from tuol/fix_4d
4a65513 add missing utils.mk
b5a1c14 Merge pull request Xilinx#286 from tuol/fix_doc_1010
c633178 add missing images
569364b complement rst doc
0ac615d Merge pull request Xilinx#285 from tuol/4d_datamover_l2_case
4d0e9ae add 4D data mover L2 case
398dc24 Merge pull request Xilinx#284 from tuol/cr_1141439
08a1ce1 Merge pull request Xilinx#283 from RepoOps/update_doc_url_3
0ab1937 slightly update L2/script/makefile
7ab5ed0 update url and branch in doc
5c6bfef Merge pull request Xilinx#282 from tuol/fix_doc_version_3
73b7358 update version to 2022.2
6910294 Merge pull request Xilinx#281 from tuol/doc_fix
8595a85 add release note
f8d18dd Merge pull request Xilinx#280 from RepoOps/update_makefile_20220908-212141
7d7643c update Makefile with 2.0.8 version

Co-authored-by: sdausr <sdausr@xilinx.com>

utils/L1/include/xf_utils_hw/pl_datamover.hpp

@@ -296,6 +296,26 @@ void cmdParser(hls::burst_maxi<ap_uint<64> > descriptor,
 }
 } // namespace details
 
+/**
+ * @brief datamover for reading multiple 4D cuboids.
+ * It will read the descriptors, access data as descriptors demand and feed data to AXI stream.
+ * Descriptors are stored in descriptor buffer, which starts with 64 bit integer which represent number of descriptors
+ * inside the buffer. It's followed by one or multiple descritpors, each of which consists 9 x 64bits interger, cfg[0],
+ * cfg[1] .. cfg[8].
+ * All descriptors will be processed one by one, from the first to the last.
+ * Each descriptor represent the access pattern of 4D cuboid, which could be treated like a 4-layer nested loop.
+ * Please take reference from design internal doc page for details of descriptor format.
+ *
+ * @tparam WDATA Bit width of data element
+ * @tparam LATENCY MAXI port latency, should be the same with pragma setup
+ * @tparam OUTSTANDING MAXI port read/write outstanding, should be the same with pragma setup
+ * @tparam BURSTLEN MAXI port read/write burst length, should be the same with pragma setup
+ *
+ * @param descriptor_buffer Buffer that stores one or multiple descriptors.
+ * @param data Buffer that contains data to be accessed
+ * @param w_data AXI Stream which data will be written to.
+ */
+
 template <int WDATA, int LATENCY, int OUTSTANDING, int BURSTLEN>
 void read4D(
     // input
@@ -315,6 +335,26 @@ void read4D(
     details::manualBurstRead<WDATA, LATENCY, OUTSTANDING, BURSTLEN>(data, r_offset, r_burst, e_r, w_data);
 }
 
+/**
+ * @brief datamover for write multiple 4D cuboids.
+ * It will read data from AXI stream, write access data to the address as descriptors demand.
+ * Descriptors are stored in descriptor buffer, which starts with 64 bit integer which represent number of descriptors
+ * inside the buffer. It's followed by one or multiple descritpors, each of which consists 9 x 64bits interger, cfg[0],
+ * cfg[1] .. cfg[8].
+ * All descriptors will be processed one by one, from the first to the last.
+ * Each descriptor represent the access pattern of 4D cuboid, which could be treated like a 4-layer nested loop.
+ * Please take reference from design internal doc page for details of descriptor format.
+ *
+ * @tparam WDATA Bit width of data element
+ * @tparam LATENCY MAXI port latency, should be the same with pragma setup
+ * @tparam OUTSTANDING MAXI port read/write outstanding, should be the same with pragma setup
+ * @tparam BURSTLEN MAXI port read/write burst length, should be the same with pragma setup
+ *
+ * @param descriptor_buffer Buffer that stores one or multiple descriptors.
+ * @param w_data AXI Stream which data will be written to.
+ * @param data Buffer that contains data to be accessed
+ */
+
 template <int WDATA, int LATENCY, int OUTSTANDING, int BURSTLEN>
 void write4D(
     // input

utils/L2/scripts/internal/generate_kernels.py

@@ -20,7 +20,9 @@
 	'StoreStreamToMasterWithCounter': 'store_stream_to_master_with_counter.cpp.j2',
 	'ValidateStreamWithMaster': 'validate_stream_with_master.cpp.j2',
 	'ValidateStreamWithRam': 'validate_stream_with_ram.cpp.j2',
-	'ValidateStreamWithRom': 'validate_stream_with_rom.cpp.j2'
+	'ValidateStreamWithRom': 'validate_stream_with_rom.cpp.j2',
+    '4DCuboidRead': 'load_4D_cuboid_from_master_to_stream.cpp.j2',
+    '4DCuboidWrite': 'store_4D_cuboid_from_stream_to_master.cpp.j2'
 }
 
 def canonical_name(s):
@@ -37,8 +39,8 @@ def get_name(e):
     if 'buffer' in e:
         return canonical_name(e['buffer'])
     elif 'stream' in e:
-        if e['width'] != 16 and e['width'] != 32 and e['width'] != 64 and e['width'] != 128:
-            sys.exit('[ERROR] Width of AXI stream have to be 16, 32, 64, or 128 bits');
+        if e['width'] != 16 and e['width'] != 32 and e['width'] != 64 and e['width'] != 128 and e['width'] != 256 and e['width'] != 512:
+            sys.exit('[ERROR] Width of AXI stream have to be 16, 32, 64, 128, 256 or 512 bits');
         return canonical_name(e['stream'])
     else:
         sys.exit('[ERROR] File name not defined');
@@ -93,7 +95,8 @@ def main():
                 print('[INFO] created ' + m['in_file']['name'] + '.inc')
             if m.get('in_ref'):
                 m['in_ref']['name'] = get_name(m['in_ref'])
-            m['out']['name'] = get_name(m['out'])
+            if m.get('out'):
+                m['out']['name'] = get_name(m['out'])
 
     #print(d)
 

utils/L2/scripts/makefile

@@ -16,6 +16,7 @@
 
 MK_PATH := $(abspath $(lastword $(MAKEFILE_LIST)))
 MK_DIR := $(patsubst %/,%,$(dir $(MK_PATH)))
+SHELL := /bin/bash
 override XFLIB_DIR := $(shell bash -c 'export MK_PATH=$(MK_PATH); echo $${MK_PATH%/L2/scripts/*}')
 
 DEST_DIR ?= $(CURDIR)

utils/L2/scripts/templates/datamover/load_4D_cuboid_from_master_to_stream.cpp.j2

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2020 Xilinx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <stdint.h>
+#include "xf_utils_hw/pl_datamover.hpp"
+
+extern "C" void {{ k["name"] }}({% for m in k["map"] %}
+    // {{ loop.index0 }}
+    hls::burst_maxi<ap_uint<64> > {{ m["in_port"]["descriptors"] }},
+    hls::burst_maxi<ap_uint<{{ m["out_port"]["width"] }}> > {{ m["in_port"]["name"] }},
+    hls::stream<ap_axiu<{{ m["out_port"]["width"] }}, 0, 0, 0> >& {{ m["out_port"]["stream"] }}{{ ',' if loop.index0 != (k["map"] | length) - 1 else '' }}
+{% endfor %}
+    ) {
+    ; // clang-format off{% for m in k["map"] %}
+#pragma HLS interface m_axi offset=slave bundle=gmem0{{ loop.index0 }} port={{ m["in_port"]["descriptors"] }} \
+    max_read_burst_length={{ m["in_port"]["burst_len"] }} num_read_outstanding={{ m["in_port"]["outstanding"] }} latency={{ m["in_port"]["latency"] }} depth = 4096
+#pragma HLS interface m_axi offset=slave bundle=gmem1{{ loop.index0 }} port={{ m["in_port"]["buffer"] }} \
+    max_read_burst_length={{ m["in_port"]["burst_len"] }} num_read_outstanding={{ m["in_port"]["outstanding"] }} latency={{ m["in_port"]["latency"] }} depth = 4096
+#pragma HLS interface s_axilite bundle=control port={{ m["in_port"]["descriptors"] }}
+#pragma HLS interface s_axilite bundle=control port={{ m["in_port"]["buffer"] }}
+#pragma HLS interface axis port={{ m["out_port"]["stream"] }}
+{% endfor %}
+#pragma HLS interface s_axilite bundle=control port=return
+    ; // clang-format on
+
+#pragma HLS dataflow
+{% for m in k["map"] %}
+    xf::common::utils_hw::read4D<{{ m["out_port"]["width"] }}, {{ m["in_port"]["latency"] }}, {{ m["in_port"]["outstanding"] }}, {{ m["in_port"]["burst_len"] }}>({{ m["in_port"]["descriptors"] }}, {{ m["in_port"]["buffer"] }}, {{ m["out_port"]["stream"] }}); {% endfor %}
+}
+{# vim: set filetype=cpp : #}

utils/L2/scripts/templates/datamover/store_4D_cuboid_from_stream_to_master.cpp.j2

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2020 Xilinx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <stdint.h>
+#include "xf_utils_hw/pl_datamover.hpp"
+
+extern "C" void {{ k["name"] }}({% for m in k["map"] %}
+    // {{ loop.index0 }}
+    hls::burst_maxi<ap_uint<64> > {{ m["in_port"]["descriptors"] }},
+    hls::stream<ap_axiu<{{ m["in_port"]["width"] }}, 0, 0, 0> >& {{ m["in_port"]["stream"] }},
+    hls::burst_maxi<ap_uint<{{ m["in_port"]["width"] }}> > {{ m["out_port"]["buffer"] }}{{ ',' if loop.index0 != (k["map"] | length) - 1 else '' }}
+{% endfor %}
+    ) {
+    ; // clang-format off{% for m in k["map"] %}
+#pragma HLS interface m_axi offset=slave bundle=gmem0{{ loop.index0 }} port={{ m["in_port"]["descriptors"] }} \
+    max_read_burst_length={{ m["out_port"]["burst_len"] }} num_read_outstanding={{ m["out_port"]["outstanding"] }} latency={{ m["out_port"]["latency"] }} depth = 4096
+#pragma HLS interface m_axi offset=slave bundle=gmem1{{ loop.index0 }} port={{ m["out_port"]["buffer"] }} \
+    max_read_burst_length={{ m["out_port"]["burst_len"] }} num_read_outstanding={{ m["out_port"]["outstanding"] }} latency={{ m["out_port"]["latency"] }} depth = 4096
+#pragma HLS interface s_axilite bundle=control port={{ m["in_port"]["descriptors"] }}
+#pragma HLS interface s_axilite bundle=control port={{ m["out_port"]["buffer"] }}
+#pragma HLS interface axis port={{ m["in_port"]["stream"] }}
+{% endfor %}
+#pragma HLS interface s_axilite bundle=control port=return
+    ; // clang-format on
+
+#pragma HLS dataflow
+{% for m in k["map"] %}
+    xf::common::utils_hw::write4D<{{ m["in_port"]["width"] }}, {{ m["out_port"]["latency"] }}, {{ m["out_port"]["outstanding"] }}, {{ m["out_port"]["burst_len"] }}>({{ m["in_port"]["descriptors"] }}, {{ m["in_port"]["stream"] }}, {{ m["out_port"]["buffer"] }});{% endfor %}
+}
+{# vim: set filetype=cpp : #}

utils/L2/tests/datamover/4D_datamover/.gitignore

@@ -0,0 +1,3 @@
+kernel/*.cpp
+kernel/*.inc
+_krnlgen