Installation

Installation#

System Requirements#

Intel® Data Mover Library (DML) supports only the Intel 64 platform.

Software Path Requirements#

Minimum requirements
x86-64 CPU with Intel® Advanced Vector Extensions 2 support (Intel® microarchitecture code name Broadwell).
Recommended requirements
x86-64 CPU with Intel® Advanced Vector Extensions 512 support (Intel® microarchitecture code name Skylake (Server) processor or higher).

Hardware Path Requirements#

Execution using the Hardware Path is available only on Linux* OS.

Additionally, the operating system must meet the following requirements:

Accelerator Configuration#

Library requires presetting of Intel® Data Streaming Accelerator (Intel® DSA) configuration before use. Library doesn’t perform hardware setup independently. System administrator is responsible for correctness of accelerator configuration. If configuration is invalid or doesn’t exist, the library returns an appropriate status code if the hardware execution is path used.

Warning

Not all features supported in Intel® DSA are present in Intel® DML. Refer to Library Limitations for more details.

An Intel® DSA device can be configured with the libaccel-config library, which can be found at intel/idxd-config.

For instance, users can use the following commands to directly configure the device with the accel-config using existing config file:

accel-config load-config -c <config file>
accel-config enable-device <device>
accel-config enable-wq <device>/<wq>

Intel® DML also provides a way to configure Intel® DSA through calling either of the following commands based on whether you are setting up via the Intel® DML source or from the Intel® DML installed directory:

sudo python3 <dml-library>/tools/scripts/accel_conf.py --load=<path to config file>

sudo python3 <install-dir>/share/DML/scripts/accel_conf.py --load=<path to config file>

With configuration files found at either <dml-library>/tools/configs/ or <install-dir>/share/DML/configs/. With configuration files of the format <# nodes>n<# devices>d<# engines>e<# of workqueues>w-s.conf or <# nodes>n<# devices>d<# engines>e<# of workqueues>w-s-n<which node>.conf.

Attention

Sudo privileges are required to configure Intel® DSA.

Building the Library#

Prerequisites#

Before building the library, install and set up the following tools:

  • C++ compiler with C++17 standard support

    • Linux* OS: GCC 8.2+ (or Clang 12.0.1+ for building fuzz tests)

    • Windows* OS: MSVC 19 or higher

  • Linux* OS: Universally Unique ID library (uuid-dev) version 2.35.2 or higher

  • Cross-platform build tool: CMake* version 3.12 or higher. If Intel DML is built with -DSANITIZE_THREADS=ON, use CMake version 3.23 or higher

  • Make

    • Linux* OS: GNU Make

    • Windows* OS: Microsoft NMAKE`

Available Build Options#

Intel DML supports the following build options:

  • -DSANITIZE_MEMORY=[ON|OFF] - Enables memory sanitizing (OFF by default).

  • -DSANITIZE_THREADS=[ON|OFF] - Enables threads sanitizing (OFF by default).

Attention

Options -DSANITIZE_THREADS=ON and -DSANITIZE_MEMORY=ON are incompatible and can not be used for the same build.

Attention

If Intel DML is built with -DSANITIZE_THREADS=ON, use CMake* version 3.23 or higher to avoid issue with finding pthread library in FindThreads.

  • -DLOG_HW_INIT=[ON|OFF] - Enables hardware initialization log (OFF by default).

  • -DDML_BUILD_FUZZ_TESTS=[ON|OFF] - Enables building of fuzz tests (OFF by default).

  • -DDML_BUILD_EXAMPLES=[OFF|ON] - Enables building library examples (ON by default). For more information on existing examples, see Code Samples and Examples.

  • -DDML_BUILD_TESTS=[OFF|ON] - Enables building library testing and benchmarks frameworks (ON by default). For more information on library testing, see Library Testing section. For information on benchmarking the library, see Benchmarks Framework Guide.

Attention

To build Intel DML from the GitHub release package (.tar, .tgz) without downloading sub-module dependencies for testing and benchmarking, use -DDML_BUILD_TESTS=OFF.

  • DML_RECORD_SWITCHES=[OFF|ON] - Enables -frecord-gcc-switches flag (OFF by default).

Build#

To build the library, complete the following steps:

  1. Make sure that all the tools from the Prerequisites section are available from your environment.

  2. Extract git sources using the following command:

    git clone --recursive https://github.com/intel/DML.git

  3. Build the library and tests by executing the following list of commands from <dml_library> depending on OS:

Windows* OS:

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=<install_dir> -G "NMake Makefiles" ..
cmake --build . --target install

Linux* OS:

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=<install_dir> ..
cmake --build . --target install

Installed Package Structure#

┌── bin
│   ├── dml_benchmarks         # Benchmarks framework
│   ├── tests*                 # Testing framework
│   └── dml_test_functional*   # Additional test executables for C and C++ APIs
│
├── include
│   └── dml
|       ├── dml.h              # Low-Level C API headers
|       ├── dml.hpp            # High-Level C++ API headers
|       ├── dmldefs.h
|       ├── detail
|       └── hl
│
├── lib or lib64
|   ├── cmake
|   ├── libdml.a               # Library with High-Level C++ APIs and implementations
|   └── libdmlhl.a             # Library with Low-Level C APIs and implementations
|
└── share/DML
    ├── configs                # Configuration files for Intel® DSA
    └── scripts                # Scripts useful for configuration step

Executables for tests and benchmarks framework are available in bin/ folder.

Configuration files and scripts for Intel® DSA (see Accelerator Configuration for more details) are available in bin/ folder.

Examples are located in <dml_library>/build/examples/.

Building the Documentation#

Prerequisites#

To build the offline version of the documentation, the following tools must be installed:

  • Doxygen 1.8.17 or higher (e.g., with apt install doxygen)

  • Python 3.8.5 or higher (e.g., with apt install python3.X)

  • Sphinx 7.2.6 or higher (e.g., with pip3 install sphinx)

  • sphinx_book_theme 1.1.2 or higher (e.g., with pip3 install sphinx-book-theme)

  • Breathe 4.35.0 or higher (e.g., with pip3 install breathe)

Attention

To avoid incompatibility between Breathe, sphinx_book_theme and Sphinx versions, use requirements.txt file to install guaranteed compatible combination of components.

pip3 install -r <qpl_library>/doc/requirements.txt

Build Steps#

To generate full offline documentation from sources, use the following commands:

/bin/bash <dml_library>/doc/_get_docs.sh

Attention

Linux* OS shell (or Windows* OS shell alternatives) is required to run the documentation build script.

After the generation process is completed, open the <dml_library>/doc/build/html/index.html file.

Contents