HEBench
Quickstart C++ Wrapper Backend Tutorial - Preparation

Table of Contents

Steps

Before attempting these steps, you must have a built version of the API Bridge.

1. Copy example

Start by copying api_bridge_example_be to a new folder with the name of the desired backend

api_bridge_example_backend -> tutorial_backend

2. Rename files to new backend name

After copying, the next step is to rename all of the included files to match the scheme of the new backend name. The files to rename are:

3. Update build system

Update the CMakeLists.txt to become stand-alone: point to the new file names, change the target name as appropriate, locate include directory for and link hebench_cpp static library, locate and link other third-party dependencies, like PALISADE for this tutorial.

For simplicity, this build system will assume that all dependencies have been pre-compiled (PALISADE is assumed to be installed). Creating a robust build system is beyond the scope of this tutorial.

Find the listing of the full CMakeLists.txt stand-alone below. Make sure to replace "/include/directory/for/api_bridge" and "/directory/containing/libhebench_cpp.a" for the correct paths.

# Copyright (C) 2021 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

cmake_minimum_required(VERSION 3.12)
project(be_tutorial LANGUAGES C CXX)

# C++ version
set(CMAKE_CXX_STANDARD 17) # C++ standard C++17
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

set(${PROJECT_NAME}_SOURCES
    "${CMAKE_CURRENT_SOURCE_DIR}/src/tutorial_engine_palisade.cpp"
    "${CMAKE_CURRENT_SOURCE_DIR}/src/tutorial_eltwiseadd_benchmark_palisade.cpp"
    )
set(${PROJECT_NAME}_HEADERS
    "${CMAKE_CURRENT_SOURCE_DIR}/include/tutorial_error_palisade.h"
    "${CMAKE_CURRENT_SOURCE_DIR}/include/tutorial_engine_palisade.h"
    "${CMAKE_CURRENT_SOURCE_DIR}/include/tutorial_eltwiseadd_benchmark_palisade.h"
    )

add_library(${PROJECT_NAME} SHARED ${${PROJECT_NAME}_SOURCES} ${${PROJECT_NAME}_HEADERS})
target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)

# All external libraries are assumed to be pre-compiled for tutorial simplicity.

# find the hebench_cpp archive
set(HEBENCH_API_INCLUDE_DIR "/include/directory/for/api_bridge")
target_include_directories(${PROJECT_NAME} PRIVATE ${HEBENCH_API_INCLUDE_DIR}) # point to include for api_bridge
find_library(hebench_cpp_FOUND NAMES libhebench_cpp.a HINTS "/directory/containing/libhebench_cpp.a")
if(hebench_cpp_FOUND)
    add_library(hebench_cpp UNKNOWN IMPORTED)
    # populate the found library with its properties
    set_property(TARGET hebench_cpp PROPERTY IMPORTED_LOCATION ${hebench_cpp_FOUND})
    set_property(TARGET hebench_cpp APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${HEBENCH_API_INCLUDE_DIR})
else()
    message(FATAL_ERROR "libhebench_cpp.a not found.")
endif()

# link found library
target_link_libraries(${PROJECT_NAME} PUBLIC "-Wl,--whole-archive" hebench_cpp "-Wl,--no-whole-archive")

# find other third party dependencies
# pre-built PALISADE
set(PALISADE_HINT_DIR "/usr/local/")

find_package(Palisade HINTS ${PALISADE_HINT_DIR} REQUIRED)
add_library(libpalisade INTERFACE)
target_include_directories(libpalisade INTERFACE
    ${OPENMP_INCLUDES} # Will be empty if PALISADE is built single-threaded
    ${PALISADE_INCLUDE}
    ${PALISADE_INCLUDE}/third-party/include
    ${PALISADE_INCLUDE}/core
    ${PALISADE_INCLUDE}/pke
    ${PALISADE_INCLUDE}/binfhe)
target_link_directories(libpalisade INTERFACE ${PALISADE_LIBDIR})
target_link_libraries(libpalisade INTERFACE ${PALISADE_LIBRARIES} ${OPENMP_LIBRARIES})

# Ignore errors from PALISADE
add_compile_options(-Wno-error=unused-parameter -Wno-error=ignored-qualifiers -Wno-error=deprecated-copy)

# link found library
target_link_libraries(${PROJECT_NAME} PUBLIC libpalisade)

# extra compile options
target_compile_options(${PROJECT_NAME} PRIVATE -Wall -Wextra) # show warnings

# install options
include(GNUInstallDirs)
set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib")
install(TARGETS ${PROJECT_NAME} DESTINATION lib)

4. Update includes in source files

After renaming our files for our new engine we must update the includes in the example files as follows.

tutorial_engine_palisade.cpp

#include "../include/ex_engine_palisade.h"
#include <cstring>
// include all benchmarks
#include "../include/ex_benchmark_palisade.h"

changed to

#include <cstring>
#include "tutorial_engine_palisade.h"
#include "tutorial_error_palisade.h"
// include all benchmarks
#include "tutorial_eltwiseadd_benchmark_palisade.h"
tutorial_eltwiseadd_benchmark_palisade.h
tutorial_engine_palisade.h
tutorial_error_palisade.h

tutorial_eltwiseadd_benchmark_palisade.cpp

#include "../include/ex_benchmark_palisade.h"
#include "../include/ex_engine_palisade.h"

changed to

#include "tutorial_eltwiseadd_benchmark_palisade.h"
#include "tutorial_engine_palisade.h"
#include "tutorial_error_palisade.h"

5. Define any new error codes

Add the following content to tutorial_error_palisade.h:

#pragma once
#define TUTORIAL_ECODE_PALISADE_ERROR 2

6. Refactor classes

Now that we have renamed the files to a name suitable for our new backend we must rename the example classes described in the files to the names of our new backend. For this step it is highly recommend to use an IDE with support for automatic class refactoring.

Refactor the following classes to the new name:

tutorial_engine_palisade.h

  • ExampleEngine -> TutorialEngine

tutorial_eltwiseadd_benchmark_palisade.h

  • ExampleBenchmark -> TutorialEltwiseAddBenchmark
  • ExampleBenchmarkDescription -> TutorialEltwiseAddBenchmarkDescription

Checkpoint

After completing this step it may be a good idea to try compiling the backend and running it. In its current state, if the above steps have been followed, the backend should run and perform a simple matrix multiplication in plain text. The next steps will discuss the steps to perform our benchmark instead.

Tutorial steps

Tutorial Home
Preparation
Engine Initialization and Benchmark Description
Benchmark Implementation
File References