Cleartext CPU Reference Backend

Table of Contents

1. Requirements
2. Build Configuration
   1. Build Type
   2. Advanced Configuration
      1. Third-Party Components
      2. Configuring Pre-Installed API Bridge
      3. Configuring Pre-Installed GSL
3. Building
4. Running the Benchmark
5. Contributing

Requirements

Current build system uses Cmake.

• Ubuntu 16.04/18.04/20.04
• C++17 capable compiler (tested with GCC 9.3)
• Cmake 3.12

Build Configuration

By default, the build system will pull the required third-party component versions from remote repos and build locally. Thus, this build system requires Internet access and being able to clone the required third-party repos using git.

The majority of warnings generated by third-party libraries are shown by default. If users want to hide these (e.g. to make debugging this project easier), set CMake flag -DHIDE_EXT_WARNINGS=ON. This will hide most warnings generated by third-party components built by this build system.

Build Type

If no build type is specified, the build system will build in Debug mode. Use -DCMAKE_BUILD_TYPE configuration variable to set your preferred build type:

• -DCMAKE_BUILD_TYPE=Debug : debug mode (default if no build type is specified).
• -DCMAKE_BUILD_TYPE=Release : release mode. Compiler optimizations for release enabled.
• -DCMAKE_BUILD_TYPE=RelWithDebInfo : release mode with debug symbols.
• -DCMAKE_BUILD_TYPE=MinSizeRel : release mode optimized for size.

Advanced Configuration

Users can pull, build and pre-install the required third-party components. This feature is mostly tailored for development, testing, and debugging. Otherwise, using the default behavior is recommended and this section can be skipped.

If no pre-installed version of a component is found, the correct version will be pulled from remote repo and build locally.

The build system will search for pre-installed third-party components in each of the locations below, in order, until one is found:

1. -D{COMPONENT_NAME}_INCLUDE_DIR and/or -D{COMPONENT_NAME}_LIB_DIR (lib dir is not needed for header only components).
2. -D{COMPONENT_NAME}_INSTALL_DIR
3. /usr/local

Note that if pre-installed versions are incompatible with the current version of the frontend, the build will fail.

See the following sections for the specific configuration variable names for each required third-party component.

Third-Party Components

This backend requires the following third party components:

• HEBench API Bridge: Frontend component containing the API Bridge (both C headers and C++ wrapper).
• Guideline Support Library (GSL): v3.1.0
  This is a header only library, so, it does not need to be built.

Configuring Pre-Installed API Bridge

The API Bridge is the component in HEBench that allows communication between Test Harness and backends.

If API Bridge has been pre-built, users can point the build system to the pre-installed version of API Bridge using the following CMake config variables:

-DAPI_BRIDGE_INCLUDE_DIR: include directory for API Bridge.

-DAPI_BRIDGE_LIB_DIR: lib directory for API Bridge.

-DAPI_BRIDGE_INSTALL_DIR: base directory for API Bridge. Contains both include and lib. This will be used if any of the previous config variables for API Bridge have not been set.

Configuring Pre-Installed GSL

If GSL has been pre-installed, users can point the build system to the pre-installed version using the following Cmake config variables:

-DGSL_INCLUDE_DIR: include directory for GSL.

-DGSL_INSTALL_DIR: base directory for GSL. The include directory for GSL is inside this location. This will be used if any of the previous config variables for GSL have not been set.

Building

Build from the top level of cleartext-cpu with Cmake as follows:

# assuming cleartext-cpu is already cloned
cd ~/cleartext-cpu
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$INSTALL_LOCATION # change install location at will, and/or specify pre-installed third-party directories here
make -j
make install # install built components

The install step will copy the target backend library libhebench_cleartext_backend.so to $INSTALL_LOCATION/lib

If not using pre-installed frontend, make install will include the frontend components as part of the installation.

Running the Benchmark

Once the backend has been built and installed successfully (assuming it has been installed to $INSTALL_LOCATION), the frontend Test Harness can run the benchmark as follows:

test_harness --backend_lib_path $INSTALL_LOCATION/lib/libhebench_cleartext_backend.so --report_root_path $REPORT_OUTPUT_PATH

The Test Harness will save the reports and summary of the run to the path specified in $REPORT_OUTPUT_PATH.

Contributing

This project welcomes external contributions. To contribute to HEBench, see CONTRIBUTING.md. We encourage feedback and suggestions via Github Issues as well as discussion via Github Discussions.