Add vivado simulation support and SDK

Author: guimingwx

DAC_2023_CHAM.pdf

@@ -0,0 +1,7 @@
+Legal Disclaimer
+
+Within this source code, the comments in Chinese shall be the original, governing version. Any comment in other languages are for reference only. In the event of any conflict between the Chinese language version comments and other language version comments, the Chinese language version shall prevail.
+
+法律免责声明
+
+关于代码注释部分，中文注释为官方版本，其它语言注释仅做参考。中文注释可能与其它语言注释存在不一致，当中文注释与其它语言注释存在不一致时，请以中文注释为准。

LEGAL.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Alibaba Damo Academy
+Copyright (c) 2023 Alibaba Damo Academy and Ant Group
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -5,7 +5,7 @@ The __CHAM__ project is initiated by Alibaba DAMO Academy CTL and Ant Group's An
 
 ___CHAM___ is a customized homomorphic encryption accelerator for fast matrix-vector product. Homomorphic encryption (HE), enabling computation on encrypted data, suffers from poor performance due to enlarged data size and exploded amount of computation. Existing HE accelerators either target small HE operations or fail to support fast-evolving HE algorithms. To better support various privacy-preserving applications (e.g., logistic regression and neural-network inference), we propose CHAM for high-performance matrix-vector product, which can be easily extended to 2D/3D convolutions. 
 
-The code in this repository is released by Alibaba DAMO Academy CTL and Ant Group's AntChain under MIT License.
+The code in this repository is released by Alibaba DAMO Academy CTL, Ant Group's AntChain and Ant Research under MIT License.
 
 The distribution is developed as part of our DAC2023 paper called *"CHAM: A Customized Homomorphic Encryption Accelerator for Fast Matrix-Vector Product"*. This distribution is an open-source version of our commercial accelerator and not ready for production use.
 
@@ -25,30 +25,42 @@ The directory structure is as follows:
 * [__sim__](sim): simulation environment
 * [__tv__](tv): test vectors
 * [__xilinx_vcs_lib__](xilinx_vcs_lib): xilinx vcs simulation library
-
+* [__chisel__](chisel): Chisel source files
+* [__mvp_sdk__](mvp_sdk): SDK for CHAM users
 
 ## Build guide
 
+You need install Python3 and Vivado before simulation
+
+If you use VCS, you may need to run as follows:
 1. Generate xilinx vcs lib in ./xilinx_vcs_lib
 2. Modify sim/vcs/tb_top.sh line 48 to your vcs path
 3. cd sim
 4. make clean //remove the previous run_dir
-5. ./run_case <test name>//test name is showing below in Test cases
-    test_stg_0_0                test single stage at stage 0, and test only ksk ram init path
-    test_stg_0_1                test single stage at stage 0, and test only preprocess init path
-    test_stg_1                  test single stage at stage 1
-    test_stg_2                  test single stage at stage 2
-    test_stg_3                  test single stage at stage 3
-    test_stg_4                  test single stage at stage 4
-    test_stg_5                  test single stage at stage 5
-    test_stg_6                  test single stage at stage 6
-    test_stg_7                  test single stage at stage 7
-    test_stg_8                  test single stage at stage 8
-    test_stg_9                  test single stage at stage 9
-    test_stg_10                 test single stage at stage 10
-    test_row                    test all stages in a row
-    test_full_no_uram_4x4096    test full case, the test vector is 4x4096. we use testbench to init ksk ram instead of designtest_full_4x4096            test full case, the test vector is 4x4096.
-    test_full_4x4096            test full case, the test vector is 4x4096.
+5. ./run_case <test name>  //test name is showing below in Test cases
+
+test_stg_0_0:                test single stage at stage 0, and test only ksk ram init path
+test_stg_0_1:                test single stage at stage 0, and test only preprocess init path
+test_stg_1:                  test single stage at stage 1
+test_stg_2:                  test single stage at stage 2
+test_stg_3:                  test single stage at stage 3
+test_stg_4:                  test single stage at stage 4
+test_stg_5:                  test single stage at stage 5
+test_stg_6:                  test single stage at stage 6
+test_stg_7:                  test single stage at stage 7
+test_stg_8:                  test single stage at stage 8
+test_stg_9:                  test single stage at stage 9
+test_stg_10:                 test single stage at stage 10
+test_row:                    test all stages in a row
+test_full_no_uram_4x4096:    test full case, the test vector is 4x4096. we use testbench to init ksk ram instead of design
+test_full_4x4096:            test full case, the test vector is 4x4096.
+test_full_4x4096:            test full case, the test vector is 4x4096.
+
+If you use Vivado XSIM, you may need to run as follows:
+1. cd sim
+2. make partial_sim or make full_sim
+3. make clean
+
 
 ## License
 

README.md

@@ -0,0 +1,8 @@
+deps/cpu_features-*/
+deps/GSL-*/
+deps/hexl-*/
+deps/SEAL-*/
+deps/zstd-*/
+build/
+.idea/
+.DS_Store

mvp_sdk/.gitignore

@@ -0,0 +1,75 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(mvp_pubilc)
+include(CMakeFindDependencyMacro)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -g -fPIC")
+
+option(MVP_ENABLE_TESTS "enable gtest" ON)
+option(MVP_ENABLE_PYTHON_WRAPPER "enable python wrapper build" ON)
+
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-arcs -ftest-coverage")
+endif()
+
+## SEAL
+find_package(SEAL REQUIRED PACKAGE_FIND_VERSION_MAJOR 3)
+if (SEAL_STATIC_FOUND)
+  set(SEAL_LIB SEAL::seal)
+elseif (SEAL_SHARED_FOUND)
+  set(SEAL_LIB SEAL::seal_shared)
+endif()
+## MS-GSL
+find_package(Microsoft.GSL REQUIRED)
+## Threads
+find_package(Threads REQUIRED)
+## SPDLOG
+find_package(spdlog REQUIRED)
+## Pybind11
+if (MVP_ENABLE_PYTHON_WRAPPER)
+  find_package(pybind11)
+endif()
+
+include_directories(${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/include)
+
+set(MVP_PUBLIC mvp_public)
+add_library(${MVP_PUBLIC})
+add_library(MVP::public ALIAS ${MVP_PUBLIC})
+add_subdirectory(include/mvp_public)
+target_link_libraries(${MVP_PUBLIC} SEAL::seal_shared Microsoft.GSL::GSL spdlog::spdlog_header_only Threads::Threads)
+
+set(MVP_LIBS ${MVP_PUBLIC})
+
+
+if (MVP_ENABLE_TESTS)
+  enable_testing()
+  find_package(GTest REQUIRED)
+  add_executable(mvp_pub_tests)
+  add_subdirectory(tests/)
+  target_link_libraries(mvp_pub_tests GTest::gtest_main GTest::gtest ${MVP_LIBS})
+endif()
+
+if (MVP_ENABLE_PYTHON_WRAPPER)
+  add_subdirectory(python)
+endif()
+
+## build CLI
+add_subdirectory(cli)
+
+macro(add_exe FILE)
+   add_executable(${FILE}_cc api_examples/${FILE}.cc)
+   target_link_libraries(${FILE}_cc ${MVP_LIBS})
+   target_compile_definitions(${FILE}_cc PUBLIC)
+endmacro()
+
+if (MVP_ENABLE_DEMO)
+  add_exe(demo_standalone)
+  add_exe(demo_end_to_end)
+  add_exe(demo_user_key)
+endif()
+
+

mvp_sdk/.gitmodules

@@ -0,0 +1,86 @@
+# CHAM SDK
+
+## 项目结构
+
+```
+mvp_public
+├── api_examples
+├── coverage
+│   └── html
+│       └── mvp_public
+│           └── util
+├── python
+├── deps
+├── include
+│   ├── mvp_private
+│   │   └── lib
+│   │       ├── linux
+│   │       └── mac
+│   └── mvp_public
+│       ├── F3
+│       └── util
+├── scripts
+└── tests
+
+```
+
+* `api_examples` 包含了三个 demo 样例
+* `coverage` 包含了 SDK  的单元测试下的覆盖率
+* `python` 包含了一层简单的 Python Wrapper 调用 SDK
+* `deps` 包含了依赖的三方包的源码。包括
+  * `microsoft/SEAL` （版本 3.7.2 ）基础的全同态加密库。本 SDK 涉及的所有同态加密的所有操作都基于 SEAL
+  * `microsoft/GSL` （版本 3.1.0）提供 `gsl::span` 接口。
+  * `intel/hexl`（版本1.2.2）为 SEAL 提供基于 AVX512 的加速。
+  * `google/cpu_features` （版本 0.7.0) hexl 的依赖库。用于获取 CPU 支持的指令。
+  * `google/googletests` 用于单元测试
+  * `facebook/zstd`（版本 1.5.0) 用于 SEAL 中密文对象的序列化/反序列化。
+
+* `include/mvp_public` 下则是本 SDK 的源码
+* `scripts` 包含两个用于编译的脚本
+* `tests` 单元测试。需要 Googletest
+
+## 编译
+
+### 前置需求
+* C++ compiler 支持 c++17
+* cmake (>=3.10)
+
+### 执行编译
+* `bash scripts/build-deps.sh` 会编译所有依赖的三方库 `deps/`默认会使用HEXL库，如CPU不支持，在编译时使用`bash script/build-deps.sh 0`将其关闭
+* `bash scripts/build.sh` 会编译本 SDK
+* `scripts/build.sh` 提供四个可变更项
+  * `MVP_ENABLE_TESTS=ON` 设置 `OFF` 则跳过单元测试的编译
+  * `MVP_ENABLE_DEMO=ON` 设置 `OFF` 则跳过 demo 样例的编译
+  * `MVP_ENABLE_PYTHON_WRAPPER=ON` 设置 `OFF` 则跳过 Python wrapper 的编译
+  * `PYTHON_EXE` 设置具体的 Python 版本
+
+### 产出物
+
+* SDK `libmvp_public.a` 存放在 `build/lib/` 目录下
+* Python wrapper `_mvp_py.cpython-*.so` 存放在 `build/lib/` 目录下
+* demo 样例存放在 `build/bin/` 目录下
+* 单元测试 `mvp_pub_tests` 存放在 `build/bin/` 目录下
+
+### Demo 1:
+
+`api_examples/demo_standalone.cc` 样例展示了如何使用本 SDK 完成一次双方的矩阵向量乘。demo 参数: `nrows ncols is_v12 num_threads`
+
+分别代表矩阵行数（2 <=nrows<=4096）；矩阵列数 (1<=ncols)；是否用 v1.2 功能；以及最大线程数目。
+
+如 `build/bin/demo_standalone_cc 256 1024 1 4`  则会利用 FPGAv1.2 的功能 和 4 个线程去计算 256x1024 的矩阵向量乘。
+
+### Demo 2:
+
+在 `demo_standalone.cc`  的基础上。我们模拟网络通信。
+
+`api_examples/demo_end_to_end.cc` 样例展示了如何使用本 SDK 完成一次双方的矩阵向量乘。即一方持有矩阵；而向量则以秘密分享的形式被两方持有。demo 参数: `nrows ncols is_matrix_holder` 分别代表矩阵行数（2 <=nrows<=4096）；矩阵列数 (1<=ncols)；以及是否是矩阵的持有方 (is_matrix_holder=0/1)。本样例需要启动 2 个进程去模拟协议执行双方。如
+
+ `build/bin/demo_end_to_end_cc 256 1024 0 & build/bin/demo_end_to_end_cc 256 1024 1`
+
+本样例会通过 `127.0.0.1:12345` 端口去模拟网络传输。请确保端口 `12345` 是可使用的。
+
+### Demo 3:
+`api_examples/demo_user_key.cc` 样例展示了使用 `api::ConvertUserKey` 接口直接利用用户已有的 SEAL 密钥进行运算。 如 H1 可以作为已有的 SEAL 应用的一部分；而无需生成新的密钥。减轻密钥管理的负担。即使既有的 SEAL 密钥是基于非 CKKS 方案也是可行的。
+
+### Demo 4:
+`python_example.py` 展示了 Python API 的使用。以联邦学习中为例子, 计算 mat*(vec0+vec1)+0.1*w.

mvp_sdk/CMakeLists.txt

@@ -0,0 +1,42 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(mvp_pubilc_api_examples)
+include(CMakeFindDependencyMacro)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/../lib)
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/../lib)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/../bin)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -g")
+
+option(MVP_ENABLE_FPGA "enable fpga" OFF)
+
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-arcs -ftest-coverage")
+endif()
+
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../include)
+set(mvp_private ${CMAKE_CURRENT_SOURCE_DIR}/../include/mvp_private/lib/mac/libmvp_private.a)
+set(mvp_public ${CMAKE_CURRENT_SOURCE_DIR}/../build/lib/libmvp_public.a)
+
+## SEAL
+find_package(SEAL REQUIRED PACKAGE_FIND_VERSION_MAJOR 3)
+## MS-GSL
+find_package(Microsoft.GSL REQUIRED)
+## Threads
+find_package(Threads REQUIRED)
+
+set(LIBS SEAL::seal_shared Microsoft.GSL::GSL Threads::Threads ${mvp_private} ${mvp_public})
+if (MVP_ENABLE_FPGA)
+  set(LIBS "${LIBS} ${CMAKE_CURRENT_SOURCE_DIR}/../include/mvp_private/linux/libndd.so")
+endif()
+
+macro(add_demo FILE)
+   add_executable(${FILE}_cc ${FILE}.cc)
+   target_link_libraries(${FILE}_cc ${LIBS})
+   target_compile_definitions(${FILE}_cc PUBLIC)
+endmacro()
+
+add_demo(demo_standalone)
+add_demo(demo_end_to_end)
+add_demo(demo_user_key)