Skip to content

Commit

Permalink
Crypto: All updates to AOCL 5.0
Browse files Browse the repository at this point in the history 
Signed-off-by: Pranoy Jayaraj <[email protected]>
  • Loading branch information
@pjayaraj-amd
pjayaraj-amd committed Oct 10, 2024
1 parent 6f2dfb2 commit df7b23e
Show file tree
Hide file tree
Showing 878 changed files with 55,414 additions and 33,002 deletions.
130 changes: 103 additions & 27 deletions BUILD.md
View file
Original file line number Diff line number Diff line change
@@ -1,66 +1,88 @@
# AOCL Crypto Library Build
# AOCL Cryptography Library Build

### Build Release Configuration
AOCL-Cryptography uses CMAKE as a build system generator and supports make and Ninja build systems. This document explains the different build flags which can be used to disable/enable specific features for the project. For a quick start into AOCL-Cryptography, please refer to [AOCL-Cryptography Linux Quick Starter](./docs/resources/Quick_Start.md).

```shell
$ mkdir build
$ cd build
$ cmake ../
```
#### Build
`Run from build directory`

#### Extra steps for making STATIC library work
To generate a single .a file from all the .a files
```shell
ar crsT libnew.a libalcp.a libarch_zen3.a libarch_avx2.a
mv libnew.a libalcp.a
```sh
$ cmake -DOPENSSL_INSTALL_DIR=[path_to_openssl_install_dir] -DAOCL_UTILS_INSTALL_DIR=[path_to_utils_install_dir] ../
$ make -j
```
#### Using Ninja build System

```sh
$ cmake -G "Ninja" -DOPENSSL_INSTALL_DIR=[path_to_openssl_install_dir] -DAOCL_UTILS_INSTALL_DIR=[path_to_utils_install_dir] ../
$ ninja
```
#### Enabling Features of AOCL Cryptography

1. [Enable Examples - To compile example/demo code.](#example)
2. [Enable AOCL-UTILS - To dispatch correct kernel with CPU identification.](#aocl-utils)
3. [Enable DEBUG Build - To compile code in Debug Mode.](#debug)
4. [Enable Address Sanitizer Support ](#asan)
5. [Enable Bench - To compile bench code.](#bench)
6. [Enable Tests - To compile test code](#tests)

#### Enable Examples {#example}
1. [Enable Examples - To compile example/demo code.](#enable-examples)
2. [Enable AOCL-UTILS - To dispatch correct kernel with CPU identification.](#enable-aocl-utils)
3. [Enable DEBUG Build - To compile code in Debug Mode.](#build-debug-configuration)
4. [Enable Address Sanitizer Support ](#for-compiling-with-address-sanitizer-support)
5. [Enable Valgrind Memcheck Support ](#for-compiling-with-valgrind-memcheck)
6. [Enable Bench - To compile bench code.](#build-benches)
7. [Enable Tests - To compile test code](#build-tests-using-kat-vectors)
8. [Build docs in pdf form](#to-enable-all-pdf-documentation)
9. [Build Doxygen and Sphinx docs](#to-enable-both-doxygen-and-sphinx)
10. [Build with dynamic compiler selection ](#to-enable-dynamic-compiler-selection-while-building)
11. [Build with assembly disabled](#to-disable-assembly-implementation-and-use-intrinsics-kernels)
12. [Disabling/Enabling Optional Features](#disablingenabling-optional-features)

#### Enable Examples

To enable examples, append `-DALCP_ENABLE_EXAMPLES=ON` to the cmake configuration command.
```sh
$ cmake -DALCP_ENABLE_EXAMPLES=ON ../
```
ALCP_ENABLE_EXAMPLES is ON by default

#### Enable AOCL-UTILS {#aocl-utils}
#### Enable AOCL-UTILS

To enable aocl utils checks, append `-DAOCL_UTILS_INSTALL_DIR=path/to/aocl/utils/source` and `-DENABLE_AOCL_UTILS=ON` to the cmake configuration command.
```bash
$ cmake -DENABLE_AOCL_UTILS=ON -DAOCL_UTILS_INSTALL_DIR=path/to/aocl/utils/source ../
```
ENABLE_AOCL_UTILS is ON by default

#### Build Debug Configuration {#debug}
#### Build Debug Configuration

To build in debug mode, append `-DCMAKE_BUILD_TYPE=DEBUG` to the cmake configuration command.
```sh
$ cmake -DCMAKE_BUILD_TYPE=DEBUG ../
```
CMAKE_BUILD_TYPE is set to RELEASE by default

#### For Compiling with Address Sanitizer Support {#asan}
#### For Compiling with Address Sanitizer Support

To enable sanitizers (asan, tsan etc), append `-DALCP_SANITIZE=ON` to the cmake configuration command.
```sh
$ cmake -DALCP_SANITIZE=ON ../
```
ENABLE_AOCL_UTILS is OFF by default

#### For Compiling with Valgrind Memcheck

In order to build ALCP to run binaries with valgrind to detect any memory leaks
```sh
$ cmake -DALCP_MEMCHECK_VALGRIND=ON ../
```
ALCP_MEMCHECK_VALGRIND is OFF by default

#### Build Benches {#bench}
<span style="color:red"> __Note__: </span> Due to a known limitation in AOCL-Utils, any executables exercising RSA / EC routines might fail when ran with valgrind.

#### Build Benches

To build benchmarking support with alcp library, append `-DALCP_ENABLE_BENCH=ON` to the cmake configuration command.
```sh
$ cmake -DALCP_ENABLE_BENCH=ON ../
```
ALCP_ENABLE_BENCH is OFF by default

Benchmarks will be built into `bench/{algorithm_type}/`

Please look into **[ README.md ](md_bench_README.html)** from bench.
Please look into **[ README.md ](./bench/README.md)** from bench.

#### Execute Benchmarks
```
Expand All @@ -73,16 +95,70 @@ $ ./bench/digest/bench_digest --benchmark_filter=SHA2_512_16 (runs SHA256 scheme
$ ./bench/digest/bench_digest --benchmark_filter=SHA2 (runs for all SHA2 schemes and block sizes)
```

#### Build Tests (using KAT vectors) {#tests}
#### Build Tests (using KAT vectors)
To enable tests, append `-DALCP_ENABLE_TESTS=ON` to the cmake configuration command.
```sh
$ cmake -DALCP_ENABLE_TESTS=ON ../
```
ALCP_ENABLE_TESTS is OFF by default

Test executables can be found inside `tests/{algorithm_type}` directory

For more details see **[README.md](md_tests_README.html)** from tests.
For more details see **[README.md](./tests/README.md)** from tests.

#### Execute Tests
``` shell
$ ./tests/{algorithm_type}/test_{algorithm_type}
```


### Documentation

#### To enable all PDF documentation
These documentations include design documents, Provider documentation etc in PDF format which will be generated.
```sh
$ cmake -DALCP_ENABLE_DOCS=ON ../
```
ALCP_ENABLE_DOCS is OFF by default

Note: Needs the proprietary font “Klavika” to be installed in the system

#### To enable both Doxygen and Sphinx

To enable sphinx documentation before running the CMAKE command install the required python dependencies by

```sh
cd aocl-crypto
pip install -r sphinx/requirements.txt
```
To enable the HTML documentations - Sphinx and doxygen
```sh
$ cmake -DALCP_ENABLE_HTML=ON ../
```
ALCP_ENABLE_HTML is OFF by default

To generate only the Doxygen html documentation without Sphinx documentation
```sh
$ cmake -DALCP_ENABLE_HTML=ON -DALCP_ENABLE_DOXYGEN=ON -DALCP_ENABLE_SPHINX=OFF ../
```
ALCP_ENABLE_DOXYGEN, ALCP_ENABLE_SPHINX both are OFF by default

### To enable Dynamic compiler selection while building
If this option is enabled it will dynamically select between gcc/clang for compiling certain files to improve performance.
```sh
$ cmake -DALCP_ENABLE_DYNAMIC_COMPILER_PICK=ON ../
```
ALCP_ENABLE_DYNAMIC_COMPILER_PICK is on by default

### To disable assembly implementation and use intrinsics Kernels
```sh
$ cmake -DALCP_DISABLE_ASSEMBLY=ON ../
```
ALCP_DISABLE_ASSEMBLY is OFF by default

### Disabling/Enabling Optional Features
By default all of the below features are OFF and they can be enabled optionally by setting their corresponding flags to ON

- To enable multi update feature for all supported ciphers append `-DALCP_ENABLE_CIPHER_MULTI_UPDATE=ON` to build flags.
- To Enable CCM multi update feature append flag `-DALCP_ENABLE_CCM_MULTI_UPDATE=ON` to build flags.
- To Enable OFB multi update feature append flag `-DALCP_ENABLE_OFB_MULTI_UPDATE=ON` to build flags.
70 changes: 46 additions & 24 deletions BUILD_Windows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@

- MS Visual Studio (2019 or greater)
- Clang 15.0 or above
- Python 3.7 or greater
- Cmake 3.21 or greater
- Git
- Ninja(Alternative to Visual Studio Build System)

### Environment Setup:

Expand All @@ -27,6 +27,8 @@ Using Powershell:

### Build

#### Using VS-Studio Generator

`Run from source directory`
```
PS > cmake -A [platform: x86/x64] -B [build_directory] [Enable features] -DCMAKE_BUILD_TYPE=[RELEASE] -G "[generator: Visual Studio 17 2022]" -T [toolset:ClangCl/LLVM]
Expand All @@ -36,6 +38,11 @@ Default set values:
- platform: 'x64' if external LLVM toolset use: -T LLVM (otherwise,ClangCl)
- Available features: EXAMPLES, ADDRESS SANITIZER, TESTS, BENCH

#### Using Ninja build System
```
PS > cmake -B [build_directory] [Enable features] -DCMAKE_BUILD_TYPE=[RELEASE/DEBUG] -DCMAKE_C_COMPILER:FILEPATH=[path to C compiler] -DCMAKE_CXX_COMPILER:FILEPATH=[path_to_cxx_compiler] -G "Ninja"
```

`Powershell`
```
* 1. cmake -A x64 -DCMAKE_BUILD_TYPE=RELEASE -B build -T ClangCl
Expand All @@ -46,12 +53,14 @@ Default set values:

### Enabling features of AOCL Cryptography

1. [Enable Examples - To compile example/demo code.](#win-ex)
2. [Enable AOCL-UTILS - To dispatch correct kernel with CPU identification.](#win-cpu)
3. [Enable DEBUG Build - To compile code in Debug Mode.](#win-debug)
4. [Enable Address Sanitizer Support ](#win-asan)
5. [Enable Bench - To compile bench code.](#win-bench)
6. [Enable Tests - To compile test code](#win-tests)
1. [Enable Examples - To compile example/demo code.](#enable-examples)
2. [Enable AOCL-UTILS - To dispatch correct kernel with CPU identification.](#enable-aocl-utils)
3. [Enable DEBUG Build - To compile code in Debug Mode.](#for-debug-build)
4. [Enable Address Sanitizer Support ](#for-compiling-with-address-sanitizer-support)
5. [Enable Tests - To compile test code](#to-build-tests-using-kat-vectors)
6. [Enable Bench - To compile bench code.](#build-benchmarks)
7. [Enable Compat - To compare with compat libs.](#enabling-compat-libs)
8. [Disabling/Enabling Optional Features](#disablingenabling-optional-features)


#### Steps to find binaries/dll's by setting an environment variable
Expand All @@ -64,34 +73,33 @@ PS> scripts\Set_Env_Path.bat
```


#### Enable Examples {#win-ex}

#### Enable Examples
```
PS> cmake -DALCP_ENABLE_EXAMPLES=ON -B build
PS> cmake --build .\build --config=release
```
#### Run Examples
Run from build directory after setting an environment path.
```
$ .\examples\{algorithm_type}\release\{algorithm_type}\*.exe
$ .\examples\{algorithm_type}\release\*.exe
```


#### Enable AOCL-UTILS {#win-cpu}
#### Enable AOCL-UTILS
```
PS> cmake -DENABLE_AOCL_UTILS=ON -DAOCL_UTILS_INSTALL_DIR=path/to/aocl/utils/source -B build
PS> cmake --build .\build --config=release
```


#### For Debug Build {#win-debug}
#### For Debug Build

```
PS> cmake -DCMAKE_BUILD_TYPE=DEBUG -B build
PS> cmake --build .\build --config=debug
```

#### For Compiling with Address Sanitizer Support {#win-asan}
#### For Compiling with Address Sanitizer Support

```
PS> cmake -DALCP_SANITIZE=ON -B build
Expand All @@ -101,7 +109,7 @@ PS> cmake --build .\build --config=release
Running from build directory
PS>cd build

#### To Build Tests (using KAT vectors) {#win-tests}
#### To Build Tests (using KAT vectors)
```
$ Append the argument '-DALCP_ENABLE_TESTS=ON'
PS> cmake -DALCP_ENABLE_TESTS=ON ./
Expand All @@ -120,7 +128,7 @@ PS> cmake --build . --config=release
PS> ctest -C release
```

#### Build Benchmarks {#win-bench}
#### Build Benchmarks

##### To Build Bench

Expand Down Expand Up @@ -148,27 +156,41 @@ $ .\bench\{algorithm_type}\release\bench_{algorithm_type} --benchmark_filter=SHA
$ .\bench\{algorithm_type}\release\bench_{algorithm_type} --benchmark_filter=SHA2 (runs for all SHA2 schemes and block sizes)
```

### Disabling/Enabling Optional Features
By default all of the below features are OFF and they can be enabled optionally by setting their corresponding flags to ON
- To enable multi update feature for all supported ciphers append `-DALCP_ENABLE_CIPHER_MULTI_UPDATE=ON` to build flags.
- To Enable CCM multi update feature append flag `-DALCP_ENABLE_CCM_MULTI_UPDATE=ON` to build flags.
- To Enable OFB multi update feature append flag `-DALCP_ENABLE_OFB_MULTI_UPDATE=ON` to build flags.

### Enabling compat libs

1. [Enable OpenSSL - To compare performance .](#win-OSSL)
2. [Enable IPPCP - To dcompare performance.](#win-IPPCP)
1. [Enable OpenSSL - To compare performance .](#building-openssl-compatibility-libs)
2. [Enable IPPCP - To compare performance.](#building-ipp-cp-compatibility-libs)

### Build after enabling compat libs

#### Building OpenSSL Compatibility Libs {#win-OSSL}

```
#### Building OpenSSL Compatibility Libs
Enabling openSSL
PS> cmake -DENABLE_TESTS_OPENSSL_API=ON -DOPENSSL_INSTALL_DIR=path/to/openssl ./
```
PS> cd aocl-crypto/build
PS> cmake -DAOCL_COMPAT_LIBS=openssl ../
PS> cmake --build build --config=release
```
After running all the above commands you should see a openssl-compat.dll in \lib\compat\openssl\Release directory

#### Building IPP-CP Compatibility Libs {#win-IPPCP}
#### Benchmarking
​ To bench using provider path, use the following example assuming you are executing command from the openssl bin directory.

```
.\openssl.exe speed -provider-path {path_to_openssl-compat} -provider openssl-compat -evp aes-128-cbc
```
#### Building IPP-CP Compatibility Libs

Enabling IPP-Crypto
PS> cmake -DENABLE_TESTS_IPP_API=ON -DIPP_INSTALL_DIR=path/to/ipp_crypto ./
```
PS> cd aocl-crypto/build
PS> cmake --DAOCL_COMPAT_LIBS=ipp ../
PS> cmake --build build --config=release
```

Expand Down
Loading

0 comments on commit df7b23e

Please sign in to comment.