SynapseAI Core initial commit

Add the files of the SynapseAI project to github.
See README.md for details on the project

Signed-off-by: Doron Singer <[email protected]>
Reviewed-by: Oded Gabbay <[email protected]>
Signed-off-by: Oded Gabbay <[email protected]>

.gitignore

@@ -0,0 +1,4 @@
+build
+.cproject
+.project
+.settings

CMakeLists.txt

@@ -0,0 +1,33 @@
+# COPYRIGHT (c) 2019-2021 Habanalabs Ltd. See COPYING.md file
+
+cmake_minimum_required(VERSION 3.5.1)
+
+project(synapse_core)
+
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11 -Wall -Werror -Wno-sign-compare -fno-strict-aliasing")
+
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pipe")
+
+if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS 8.0)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-attributes")
+endif()
+
+if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 7.0)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-parentheses")
+endif()
+
+set(SYNAPSE_BACKEND_TARGET synapse_backend)
+set(SYNAPSE_CORE_TARGET synapse_core)
+
+# Copy library files to a lib sub-directory
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+
+# Copy executable files to a bin sub-directory
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+
+add_subdirectory(synapse_backend)
+add_subdirectory(elftools)
+add_subdirectory(synapse_core)
+add_subdirectory(tpc_kernels_db)
+add_subdirectory(tests)

COPYING.MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 HabanaLabs Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

COPYING.md

@@ -0,0 +1,8 @@
+# Default License
+
+Unless otherwise stated this software is available to you under the MIT
+license (see COPYING.MIT).
+
+# Copyright Holders
+
+HabanaLabs Ltd. is the copyright holder of ALL the files in this software.

README.md

@@ -0,0 +1,99 @@
+# SynapseAI Core
+SynapseAI Core is a reference implementation of the SynapseAI API running on Habana Gaudi.
+
+- [SynapseAI Core](#synapseai-core)
+  - [Library components](#library-components)
+  - [Pre-requisites](#pre-requisites)
+  - [Building SynapseAI Core](#building-synapseai-core)
+  - [Tests](#tests)
+    - [Running the Tensor Division test](#running-the-tensor-division-test)
+  - [Limitations](#limitations)
+
+## Library components
+
+SynapseAI Core contains the following elements:
+
+- Synapse Core: an implementation of the SynapseAI APIs. Some APIs are not implemented for brevity, see documentation below.
+- Synapse Backend: a library for executing code on Habana Gaudi, using the habanalabs driver and the hl-thunk user-space library.
+- TPC Kernels DB: a library containing some sample TPC (Tensor Processing Core) kernels and accompanying host-side code.
+- ELFTools: a utility library for parsing ELF sections and extracting metadata generated by the TPC LLVM compiler.
+- Tests: Some simple tests to demonstrate how to execute workloads on the device that utilize the TPC engines.
+
+## Pre-requisites
+
+1. Linux kernel with latest habanalabs driver. 
+   Gaudi device support was added in kernel 5.7 but to work with a secured device, kernel 5.15 and above is required.
+
+2. hl-thunk library (https://github.com/HabanaAI/hl-thunk)
+
+3. TPC LLVM compiler (https://github.com/HabanaAI/tpc_llvm)
+
+4. cmake version 3.5.1 or higher
+
+5. GCC 7.5 or higher
+
+## Building SynapseAI Core
+
+1. Build the hl-thunk library and TPC LLVM compiler according to their respective instructions.
+   From here on, we assume the root of TPC LLVM is $HOME/tpc-llvm and the root of hl-thunk
+   is $HOME/hl-thunk
+
+2. Clone the repository. From here on, we assume it was cloned to $HOME/SynapseAI_core
+
+3. Run the build.sh script:
+
+```sh
+cd $HOME/SynapseAI_Core
+EXTRA_CMAKE_FLAGS="-DTPC_LLVM_BIN_PATH=$HOME/tpc-llvm/build/bin -DHLTHUNK_INCLUDE_PATH=$HOME/hl-thunk/include/uapi -DHLTHUNK_LIB_PATH=$HOME/hl-thunk/build/lib" ./build.sh
+```
+
+## Tests
+
+There are a couple of tests in the tests folder but currently only two will compile.
+In the near future we will add the missing kernels for the rest of the tests.
+
+The tests that can currently be run are:
+
+1. div_test - This test computes division of two tensors on the device. It copies the output to the host and compares the result to a reference implementation on the host.
+   The test serves as a demonstration of how to create a graph containing a single node. The node represents a divide operator. The division is implemented using a TPC kernel that performs the computation on the TPC engines.
+
+2. memcpy_test - This test demonstrates how to use the DMA engine to copy a tensor in and out of the device. It doesn't use the TPC engine and doesn't require any TPC kernel.
+
+### Running the Tensor Division test
+
+```sh
+cd $HOME/SynapseAI_Core
+./build/bin/div_test
+```
+
+The expected result should be:
+```sh
+Comparison passed successfully
+```
+
+## Limitations
+
+Limitations of this implementation compared to the closed-source SynapseAI release:
+
+- Operations are synchronous and synchronization occurs through the host.
+  - So many APIs, like synStreamWaitEvent, synEventCreate etc, are no-ops.
+- This version of the library doesn't implement any operations itself. This means for an operation like reshape or split, the user has to resolve it themselves, or write a TPC kernel to perform it.
+- The implementation is limited to single-node graphs. Calling synNodeCreate on a graph that already contains a node will fail.
+  - As a corollary, the user must perform all memory management of the Gaudi Memory (HBM)
+  - And control edges are not supported since they're not needed
+- The "section" mechanism is not supported. All tensors must be created with a null for section handle.
+- The user is limited to a single stream per type. Only compute, copy device to host and copy host to device are supported.
+- Tensors must be dense in device memory. Strided tensors are not supported.
+- Only floating point tensors are supported.
+- No profiler support.
+- No support for printf from kernels.
+- No support for quantization-related APIs, such as providing tensors with static data.
+- No support for advanced SynapseAI features, like dynamic shape support or tensors of any rank.
+
+- Unsupported SynapseAI APIs:
+  - synRecipeSerialize / Deserialize
+  - synDeviceAcquireByModuleID
+  - synConfigurationGet/Set
+  - synProfilerStart/Stop/GetTrace
+  - synConstTensorCreate
+  - synEventElapsedTime always returns 0

build.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+set -e
+
+# If the TPC LLVM binaries are not installed in /usr/bin, you need
+# to manually point to them. e.g. if they are located at
+# $HOME/habanaTools/build/bin then you need to define EXTRA_CMAKE_FLAGS as:
+# 
+# EXTRA_CMAKE_FLAGS=-DTPC_LLVM_BIN_PATH=$HOME/habanaTools/build/bin
+
+# If the hl-thunk library is not installed in /usr/lib/habanalabs,
+# you need to manually point to it. e.g. if it is located at
+# $HOME/hl-thunk/build/lib then you need to define EXTRA_CMAKE_FLAGS as:
+# EXTRA_CMAKE_FLAGS=-DHLTHUNK_LIB_PATH=$HOME/hl-thunk/build/lib
+
+# If the hl-thunk headers are not installed in /usr/include/habanalabs,
+# you need to manually point to them. e.g. if they are located at
+# $HOME/hl-thunk/include/uapi then you need to define EXTRA_CMAKE_FLAGS as:
+# EXTRA_CMAKE_FLAGS=-DHLTHUNK_INCLUDE_PATH=$HOME/hl-thunk/include/uapi
+
+# If the driver uapi header is not found at /usr/include/misc/habanalabs.h,
+# you need to manually point to it. e.g. if it is located at
+# $HOME/habanalabs/include/uapi/misc/habanalabs.h
+# then you need to define EXTRA_CMAKE_FLAGS as:
+# EXTRA_CMAKE_FLAGS=-DDRIVER_INCLUDE_PATH=$HOME/habanalabs/include/uapi
+
+SRCDIR=`dirname $0`
+BUILDDIR="$SRCDIR/build"
+
+if [ -d $BUILDDIR ]; then
+	rm -rf $BUILDDIR
+fi
+
+mkdir -p "$BUILDDIR"
+
+if hash cmake3 2>/dev/null; then
+    # CentOS users should install cmake3 from EPEL
+    CMAKE=cmake3
+else
+    CMAKE=cmake
+fi
+
+cd "$BUILDDIR"
+
+$CMAKE -DCMAKE_BUILD_TYPE="Release" ${EXTRA_CMAKE_FLAGS:-} ..
+make -j8

elftools/CMakeLists.txt

@@ -0,0 +1,5 @@
+# COPYRIGHT (c) 2019-2021 Habanalabs Ltd. See COPYING.md file
+
+cmake_minimum_required(VERSION 3.5.1)
+project(ELFTool)
+add_subdirectory(./src)

elftools/src/CMakeLists.txt

@@ -0,0 +1,21 @@
+# COPYRIGHT (c) 2019-2021 Habanalabs Ltd. See COPYING.md file
+
+set(ELFTOOL elftool)
+set(TPC_ELF_READEER TpcElfReader)
+
+set(CMAKE_CXX_FLAGS_DEBUG "-ggdb -O0 ")
+set(CMAKE_CXX_FLAGS_RELEASE "-O2")
+if (NOT CMAKE_BUILD_TYPE)
+    message(STATUS "No build type selected, defaulting to Debug")
+    set(CMAKE_BUILD_TYPE "Debug")
+endif()
+
+file(GLOB ELFTOLLREAD elfTool.cpp)
+file(GLOB TPCELFREADEF *.cpp)
+
+include_directories(./
+                    ./elfio/
+                    ../../external_includes/
+)
+
+ADD_LIBRARY(${TPC_ELF_READEER} SHARED ${TPCELFREADEF})