DML release v0.1.9-beta

Author: Smirnov1gor

.gitignore

@@ -0,0 +1,18 @@
+# Copyright (C) 2021 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+
+# Exlude build paths (local and remote)
+/*build*
+/*remote*
+
+# Doc build folder
+doc/build
+doc/doxygen_html
+
+# Exlude html documentation generated by doxygen
+doc/html/*
+
+# Exclude IDE projects
+.idea/
+.vscode/

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "google-test"]
+	path = google-test
+	url = https://github.com/google/googletest.git
+	branch = release-1.11.0

CMakeLists.txt

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 cmake_minimum_required(VERSION 3.12 FATAL_ERROR)
-project(Dml VERSION 0.1.8 LANGUAGES C CXX)
+project(Dml VERSION 0.1.9 LANGUAGES C CXX)
 
 set(PROJECT_SOVERSION 0)
 
@@ -14,9 +14,36 @@ else()
 endif()
 
 # TODO: Remove all options below
+option(SANITIZE_MEMORY "Enables memory sanitizing" OFF)
+option(SANITIZE_THREADS "Enables threads sanitizing" OFF)
 option(LOG_HW_INIT "Enables HW initialization log" OFF)
 option(EFFICIENT_WAIT "Enables usage of umonitor/umwait" OFF)
 
+if (SANITIZE_MEMORY)
+    message(STATUS "Memory sanitizing build is enabled")
+
+    if (WIN32)
+        message(FATAL_ERROR "Memory sanitizing is not supported in Windows")
+    else ()
+        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fsanitize=address -fsanitize=leak -g")
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=address -fsanitize=leak -g")
+    endif ()
+endif ()
+
+if (SANITIZE_THREADS)
+    message(STATUS "Threads sanitizing build is enabled")
+
+    if (WIN32)
+        message(FATAL_ERROR "Threads sanitizing is not supported in Windows")
+    else ()
+        set(CMAKE_THREAD_PREFER_PTHREAD TRUE)
+        set(THREADS_PREFER_PTHREAD_FLAG TRUE)
+        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fsanitize=thread -g")
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=thread -g")
+    endif ()
+endif ()
+
+include(cmake/tests.cmake)
 include(cmake/CompileOptions.cmake)
 include(cmake/utils.cmake)
 include(CMakePackageConfigHelpers)
@@ -48,6 +75,15 @@ message(STATUS "Hardware initialization logging: ${LOG_HW_INIT}")
 get_git_revision()
 
 add_subdirectory(sources)
+
+# Dependencies
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+set(BUILD_GMOCK OFF CACHE BOOL "Suppress gmock build" FORCE)
+set(INSTALL_GTEST OFF CACHE BOOL "Suppress gtest installation" FORCE)
+add_subdirectory(google-test)
+
+# Testing
+add_subdirectory(tests)
 add_subdirectory(examples)
 
 # Install rules

Doxyfile

@@ -42,7 +42,7 @@ PROJECT_NAME           = "Intel DML Library"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "v0.1.8-beta"
+PROJECT_NUMBER         = "v0.1.9-beta"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

README.md

@@ -35,6 +35,10 @@ After generation process is completed, open the `<dml_library>/doc/build/html/in
 
 See [Contributing document](./CONTRIBUTING.md) for details about contribution process.
 
+## How to Report Issues
+
+See [Issue Reporting](https://intel.github.io/DML/documentation/introduction_docs/issue_reporting.html) for details about issue reporting process.
+
 ## License
 
 The library is licensed under the MIT license. Refer to the

cmake/tests.cmake

@@ -0,0 +1,5 @@
+# Copyright (C) 2021 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+
+enable_testing()

doc/source/conf.py

@@ -20,7 +20,7 @@
 project = 'Intel® DML'
 copyright = '2022, Intel'
 author = 'Intel'
-release = 'v0.1.8-beta'
+release = 'v0.1.9-beta'
 
 # -- General configuration ---------------------------------------------------
 

doc/source/documentation/api_docs/low_level_api.rst

@@ -381,7 +381,7 @@ The Memory Copy with Dualcast operation copies memory from the
    thrown.
 
 Fill
-''''
+----
 
 
 The Memory Fill operation fills the memory at ``destination_first_ptr``

doc/source/documentation/get_started_docs/code_samples_and_examples.rst

@@ -16,7 +16,7 @@ The ``<dml_library>/examples/dml_job_api/job_wrapper_examples.c`` source
 file contains a number of simple examples, illustrating how you can use
 Intel DML.
 
-The wrapper’s descriptions are placed in the ``dml_examples.h``
+The wrapper's descriptions are placed in the ``dml_examples.h``
 header file.
 
 The examples are compiled during the Intel DML project compilation or
@@ -27,3 +27,106 @@ as a separate CMake target (``job_api_samples``).
   These examples are intended to be illustrative and functional, 
   but they are not intended to be examples of a complete implementation. 
   In particular, their handling of error conditions is rather primitive.
+
+
+Multi-Socket Library Usage
+==========================
+
+
+This sample shows how to utilize several sockets on the system using manual ``numa_id`` 
+setting in the ``dml_job_t`` structure. Thus, the ``memory_move`` operation can be applied 
+to one data array using several sockets at the same time.
+
+
+.. literalinclude:: ../../../../examples/multisocket.c
+    :language: c
+
+
+High-level C++ API Examples
+***************************
+
+
+cache_flush
+===========
+
+
+.. literalinclude:: ../../../../examples/high_level_api/cache_flush.cpp
+    :language: cpp
+
+
+compare_pattern
+===============
+
+
+.. literalinclude:: ../../../../examples/high_level_api/compare_pattern.cpp
+    :language: cpp
+
+
+compare
+=======
+
+
+.. literalinclude:: ../../../../examples/high_level_api/compare.cpp
+    :language: cpp
+
+
+copy_crc
+========
+
+
+.. literalinclude:: ../../../../examples/high_level_api/copy_crc.cpp
+    :language: cpp
+
+
+crc
+===
+
+
+.. literalinclude:: ../../../../examples/high_level_api/crc.cpp
+    :language: cpp
+
+
+delta
+=====
+
+
+.. literalinclude:: ../../../../examples/high_level_api/delta.cpp
+    :language: cpp
+
+
+dualcast
+========
+
+
+.. literalinclude:: ../../../../examples/high_level_api/dualcast.cpp
+    :language: cpp
+
+
+fill
+====
+
+
+.. literalinclude:: ../../../../examples/high_level_api/fill.cpp
+    :language: cpp
+
+
+mem_move
+========
+
+
+.. literalinclude:: ../../../../examples/high_level_api/mem_move.cpp
+    :language: cpp
+
+
+
+Multi-Socket Library Usage
+==========================
+
+
+This sample shows how to utilize several sockets on the system. 
+Thus, the ``memory_move`` operation can be applied 
+to one data array using several sockets at the same time.
+
+
+.. literalinclude:: ../../../../examples/multisocket.cpp
+    :language: cpp

doc/source/documentation/get_started_docs/testing.rst

@@ -0,0 +1,13 @@
+ .. ***************************************************************************
+ .. * Copyright (C) 2021 Intel Corporation
+ .. *
+ .. * SPDX-License-Identifier: MIT
+ .. ***************************************************************************/
+
+
+Test Library
+############
+
+
+To test the library, refer for the instructions to the
+`Testing document <https://github.com/intel/DML/tests/README.md>`__ placed in ``<dml_project_dir>/tests/README.md``.

doc/source/documentation/introduction_docs/introduction.rst

@@ -21,8 +21,7 @@ of available modern CPU capabilities. This can provide tremendous
 development and maintenance savings. The goal of the Intel DML is to
 provide application programming interface (API) with:
 
--  a simple C/C++ interface and data structures to enhance usability and
-   portability
+-  a simple C/C++ interface and data structures to enhance usability and portability
 -  faster time-to-market
 -  scalability with Intel® Data Streaming Accelerator (Intel® DSA) hardware
 
@@ -54,12 +53,10 @@ Library Limitations
 *******************
 
 
--  Library doesn’t work with Dedicated WQs for the accelerator, but uses
-   shared ones only.
--  Library doesn’t have API for the hardware path configuration.
--  Library doesn’t support Hardware execution path on Windows OS.
--  Library is not developed for kernel mode usage. It is user level
-   driver library.
+-  Library does not work with Dedicated WQs for the accelerator, but uses shared ones only.
+-  Library does not have API for the hardware path configuration.
+-  Library does not support Hardware execution path on Windows OS.
+-  Library is not developed for kernel mode usage. It is user level driver library.
 
 Library APIs
 ************
@@ -73,7 +70,7 @@ possibilities through different languages and paradigms: -
 
 Represents a state based interface. The base idea is to allocate a
 single state and configure one with different ways to perform necessary
-operation. Such API doesn’t allocate memory internally.
+operation. Such API does not allocate memory internally.
 
 More details: `C API Manual <../api_docs/low_level_api.html>`_
 
@@ -83,41 +80,3 @@ Represents high level operations API written with C++. API provides
 compile time optimizations and less operation preparation latency.
 
 More details: `C++ API Manual <../api_docs/high_level_api.html>`__
-
-Issue Reporting & Classification
-********************************
-
-
-Intel DML has several execution paths and large number of different
-operations and modes, thus correct issue description is important. Well
-filled description helps to detect and solve problems faster.
-Use GitHub issues to report any problems.
-
-Issues can be classified depending on the step where they occur:
-
-- Configuration step.
-- Hardware path initialization step
-- [TBD] Operation execution step.
-
-All these classes are described below:
-
-**Configuration step issues:**
-
-Intel DML library works with accelerator configuration created by
-system administrator. There can be a lot of different problems. They can
-affect library work correctness. To avoid these problems follow
-instructions in the `Library presetting
-<../get_started_docs/installation.html#library-presetting-and-building>`__
-section. These classes of issue are placed out of scope Intel DML
-library and can be addressed to **idxd-driver** team or **idxd-config**
-team.
-
-**Initialization step issues:**
-
-Intel DML library has 2 different status code groups. The first group
-helps to detect initialization issues. This issue can be caused by:
-
-- Incorrect configuration, that library doesn’t support by reason listed
-  in `Library Limitation <#library-limitations>`__ section
-- Bug in the library initialization code.
-  This kind of problem must be reported to Intel DML team.