Hls decimalmult rebase2 (#826)

* adding new hls example with double type Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> add readme Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> optimize hls action Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> adding comments Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> typo Signed-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> remove link to doc Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> hls_decimal_mult new code Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> rename variables + add test Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> merge + clean Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> Update README.md adding defconfig Signed-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> update README Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> update README Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> Update README.md Update README.md update jenkins test Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> update for decimal_mult Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> Update README.md updating automated tests Signed-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> update error message Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> typo Signed-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> typo Signed-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> update testlist.sh Signed-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> igned-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> test correction Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com> test correction Signed-off-by: Alexandre Castellane <alexandre.castellane@fr.ibm.com> * signoff Signed-off-by: Bruno Mesnet <bruno.mesnet@fr.ibm.com>
open-power · Sep 28, 2018 · 72b1712 · 72b1712
1 parent ecb76cb
commit 72b1712
Show file tree

Hide file tree

Showing 26 changed files with 1,824 additions and 25 deletions.
diff --git a/ActionTypes.md b/ActionTypes.md
@@ -18,7 +18,8 @@ IBM | 10.14.10.07 | 10.14.10.07 | HLS NVMe memcopy
 IBM | 10.14.10.08 | 10.14.10.08 | HLS Hello World
 IBM | 10.14.10.09 | 10.14.10.09 | HLS Latency Evaluation
 IBM | 10.14.10.0A | 10.14.10.0A | HLS WED/STATUS Sharing and MatrixMultiply
-IBM | 10.14.10.0B | 10.14.FF.FF | Reserved for IBM Actions
+IBM | 10.14.10.0B | 10.14.10.0B | HLS Decimal multiplication
+IBM | 10.14.10.0C | 10.14.FF.FF | Reserved for IBM Actions
 MLE | 22.DB.00.01 | 22.DB.00.01 | HDL 10G Ethernet TCP/UDP/IP Accelerator Demo
 MLE | 22.DB.00.02 | 22.DB.00.02 | HDL 25G Ethernet TCP/UDP/IP Accelerator Demo
 Reserved | FF.FF.00.00 | FF.FF.FF.FF | Reserved

diff --git a/actions/README.md b/actions/README.md
@@ -35,12 +35,13 @@ To configure the include path for the common header files with the Xilinx Vivado
 |:------------------------|:--:|:-:|:--:|:-:|:--------------------------------------------------------------------------------
 | **hdl**\_example        | X  | X | X  |   | Shows how to use MMIO registers: Software application uses one of them to collect a hardware counter value. Also shows how to copy data between Host, FPGA, card DDR and card NVMe(Flash) in **VHDL** (**Bandwidth measurement**).
 | **hdl**\_nvme_example   | X  | X | X  |   | Example to read and write 4k NVMe blocks. It provides a block layer library which is compatible to the IBM CapiFLASH block API and contains experiments for caching and prefetching.
-| hls_bfs                 | X  |   |    |   | Breadth first search (graph data): shows how to access a complex data structure.
-| hls_hashjoin            | X  |   |    |   | Hashjoin function: shows how to implement a database operation.
 | hls_helloworld          | X  |   |    |   | **Discovery example** changing all characters of a string into lower or upper cases.
-| hls_latencyeval         | X  |   |    |   | Shows how to code the application and the action to get the lowest latency (**Latency measurement**)
 | hls_memcopy             | X  | X |    |   | Shows how to copy data between Host, FPGA and card DDR (**Bandwidth measurement**).
 | hls_nvme_memcopy        | X  | X | X  |   | Shows how to copy data between Host, FPGA, card DDR and card NVMe(Flash) (**Bandwidth measurement**).
+| hls_bfs                 | X  |   |    |   | Breadth first search (graph data): shows how to access a complex data structure.
+| hls_hashjoin            | X  |   |    |   | Hashjoin function: shows how to implement a database operation.
+| hls_latencyeval         | X  |   |    |   | Shows how to code the application and the action to get the lowest latency (**Latency measurement**)
 | hls_search              | X  | X |    |   | Shows how to code an action providing multiple operations: memcopy + different searches such as Naive, KMP and streaming mode (_code not optimized_)
 | hls_sponge              | X  |   |    |   | Shows how an FPGA can compete against a multi-threaded CPU on a compute intensive code (SHA3)  (**Compute-only benchmark**)
+| hls_decimal_mult        | X  |   |    |   | Shows how to manage decimal values exchanged between the application on the server and the action in the FPGA
 
diff --git a/actions/hls_decimal_mult/Makefile b/actions/hls_decimal_mult/Makefile
@@ -0,0 +1,39 @@
+#
+# Copyright 2017 International Business Machines
+#
+# 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.
+#
+
+subdirs += sw hw
+
+all: $(subdirs)
+
+# Only build if the subdirectory is existent and if Makefile is there
+.PHONY: $(subdirs)
+$(subdirs):
+	@if [ -d $@ -a -f $@/Makefile ]; then			\
+		$(MAKE) -C $@ || exit 1;			\
+	else							\
+		echo "INFO: No Makefile available in $@ ...";	\
+	fi
+
+# Cleanup for all subdirectories.
+# Only dive into subdirectory if existent and if Makefile is there.
+clean:
+	@for dir in $(subdirs); do	\
+		if [ -d $$dir -a -f $$dir/Makefile ]; then	\
+			$(MAKE) -C $$dir $@ || exit 1;		\
+		fi						\
+	done
+	@find . -depth -name '*~'  -exec rm -rf '{}' \; -print
+	@find . -depth -name '.#*' -exec rm -rf '{}' \; -print
diff --git a/actions/hls_decimal_mult/README.md b/actions/hls_decimal_mult/README.md
@@ -0,0 +1,55 @@
+# HLS_DECIMAL_MULT EXAMPLE
+
+* Provides a simple base allowing to discover how to exchange ***single precision floating points (float) or double precision floating points (double)*** between the application on server and the action in the FPGA.
+* C code is multiplying 3 decimal numbers read from host memory and writing result in host memory
+  * code can be executed on the CPU (application + software action)
+  * code can be simulated (application + software and hardware action)
+  * code can then run in hardware when the FPGA is programmed (application + software and hardware action)
+* The example code shows the following:
+  * **application** writes floats or doubles to system host memory and read results to display and compare results processed and expected
+  * **software or hardware action** reads floats or doubles from system memory, multiply decimals 3 by 3 and write the results back in memory
+  The key point here is for the FPGA to ***understand*** the data read from the host memory and formatted by the server Operating System. The code shows the conversion to be done so that the number read can be used as a float or double in HLS code.
+As an example it is important to understand that 4.5 is represented in host memory differently depending on the type used:
+    * as a double as 0x4012_0000_0000_0000
+    * as a float  as 0x4090_0000. 
+
+ __Usage:__
+ * `./snap_decimal_mult -n12 -v` Application calls the hardware action and multiply 12 values 3 by 3. Dumps of data displayed
+ * `SNAP_CONFIG=CPU ./snap_decimal_mult` Application calls the software action
+ * `SNAP_TRACE=0xF  ./snap_decimal_mult` to display all MMIO exchanged between application and action
+ * `./../tests/test_0x1014100B.sh` to execute automatic testing
+
+ __Parameters:__
+*  arguments in command line:
+   * `-n [value]` defines the number of decimals to process (lower or equal than MAX_NB_OF_DECIMAL_READ)
+   * `-w` writes to files the result processed by the action (dec_mult_action.bin) and the expected results (dec_mult_ref.bin). Used for automatic testing.
+   * `-v` verbose mode which will display a dump of the inputs and results from host memory 
+* parameters in include/common_decimal.h:
+   * `#define MAX_NB_OF_DECIMAL_READ  16` defines the maximum number of decimals to read
+   * `typedef float  mat_elmt_t;` definse the type used: float or double
+
+__Files used__:
+```
+|
+|       Makefile                  General Makefile used to automatically prepare the final files
+|       README.md                 Documentation file for this example
+|
+├───sw                            Software directory containing application called from POWER host and software action
+|       snap_decimal_mult.c       APPLICATION which calls the software or the hardware action depending on the flag used 
+|                                 (use SNAP_CONFIG=CPU to call software action and SNAP_CONFIG=FPGA or nothing to call hardware action)
+|       action_decimal_mult.c     SOFTWARE ACTION which will be executed on the CPU only
+|       Makefile                  Makefile to compile the software files
+|
+├───include                       Common directory to sw and hw
+|       common_decimal.h          COMMON HEADER file used by the application and the software/hardware action. 
+|                                 (It contains the main structure and the defines parameters)
+|
+├───hw                            Hardware directory containing the hardware action
+|       action_decimal_mult.cpp   HARDWARE ACTION which will be executed on FPGA and is called by the application 
+|       action_decimal_mult.H     header file containing hardware action parameters
+|       Makefile                  Makefile to compile the hardware action using Vivado HLS synthesizer
+|
+└───tests                         Test directory containing all automated tests
+        test_0x1014100B.sh        Basic test shell running snap_decimal_mult application
+ ```
+
diff --git a/actions/hls_decimal_mult/hw/Makefile b/actions/hls_decimal_mult/hw/Makefile
@@ -0,0 +1,46 @@
+#
+# Copyright 2017 International Business Machines
+#
+# 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.
+#
+
+#
+# Generate HDL version of the HLS sources
+#
+# The generated HDL depends on the chip which is used and
+# therefore must match what is being used to build the
+# toplevel SNAP bitstream.
+#
+# FIXME Pass part_number and other parameters from toplevel
+#      build-system as required.
+#
+
+# Finding $SNAP_ROOT
+ifndef SNAP_ROOT
+# check if we are in hw folder of an action (three directories below snap root)
+ifneq ("$(wildcard ../../../ActionTypes.md)","")
+SNAP_ROOT=$(abspath ../../../)
+else
+$(info You are not building your software from the default directory (/path/to/snap/actions/<action_name>/sw) or specified a wrong $$SNAP_ROOT.)
+$(error Please make sure that $$SNAP_ROOT is set up correctly.)
+endif
+endif
+
+# This is solution specific. Check if we can replace this by generics too.
+SOLUTION_NAME ?= decimal_mult
+SOLUTION_DIR ?= hlsDecimalMult
+srcs += action_decimal_mult.cpp 
+
+# If you have the action code outside of the default snap directory structure, 
+# change to /path/to/snap/actions/hls.mk
+include $(SNAP_ROOT)/actions/hls.mk
diff --git a/actions/hls_decimal_mult/hw/action_decimal_mult.H b/actions/hls_decimal_mult/hw/action_decimal_mult.H
@@ -0,0 +1,40 @@
+#ifndef __ACTION_DECIMAL_MULT_H__
+#define __ACTION_DECIMAL_MULT_H__
+
+/*
+ * Copyright 2017 International Business Machines
+ *
+ * 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 <string.h>
+#include <ap_int.h>
+
+#include "hls_snap.H"
+#include <common_decimal.h> /* DecimalMult Job definition */
+
+#define RELEASE_LEVEL		0x00000010
+
+#define MAX_NB_OF_WORDS_READ	(MAX_NB_OF_DECIMAL_READ*sizeof(mat_elmt_t)/BPERDW) // =2 if double =1 if float
+#define MAX_NB_OF_DECIMAL_PERDW	(BPERDW/sizeof(mat_elmt_t)) // =8 if double =16 if float
+
+typedef char word_t[BPERDW];
+//---------------------------------------------------------------------
+typedef struct {
+	CONTROL Control;	/*  16 bytes */
+	decimal_mult_job_t Data;	/* up to 108 bytes */
+	uint8_t padding[SNAP_HLS_JOBSIZE - sizeof(decimal_mult_job_t)];
+} action_reg;
+
+#endif  /* __ACTION_DECIMAL_MULT_H__*/