From 8b829acc65569019edb896c5150d427f288e8aba Mon Sep 17 00:00:00 2001
From: Olga Malysheva <olga.malysheva@intel.com>
Date: Fri, 17 Nov 2023 17:23:05 +0100
Subject: [PATCH] Update documentation for oneTBB 2021.11.0 (#1268)

Signed-off-by: Olga Malysheva <olga.malysheva@intel.com>
---
 doc/index/toctree.rst                         |  1 +
 doc/main/intro/limitations.rst                | 46 +++++++++++++++++++
 ...e_Contents.rst => Package_Contents_os.rst} |  3 +-
 doc/main/tbb_userguide/title.rst              |  2 +-
 4 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 doc/main/intro/limitations.rst
 rename doc/main/tbb_userguide/{Package_Contents.rst => Package_Contents_os.rst} (93%)

diff --git a/doc/index/toctree.rst b/doc/index/toctree.rst
index eda4497ea0..fba9aee46c 100644
--- a/doc/index/toctree.rst
+++ b/doc/index/toctree.rst
@@ -9,6 +9,7 @@
    /main/intro/intro_os
    /main/intro/Benefits
    /main/intro/testing_approach
+   /main/intro/limitations.rst
 
 
 .. toctree::
diff --git a/doc/main/intro/limitations.rst b/doc/main/intro/limitations.rst
new file mode 100644
index 0000000000..dde9f772d7
--- /dev/null
+++ b/doc/main/intro/limitations.rst
@@ -0,0 +1,46 @@
+.. _limitations:
+
+Known Limitations
+*****************
+
+This page outlines the known limitations of oneTBB to help you better understand its capabilities. 
+
+Freestanding Compilation Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Limitation:** oneTBB does not support the freestanding compilation mode. 
+
+**Risk:** Compiling an application that utilizes oneTBB headers using the Intel(R) oneAPI DPC+/C+ Compiler may result in failure on Windows* OS if the ``/Qfreestanding`` compiler option is employed.
+
+Static Assert
+^^^^^^^^^^^^^
+
+**Limitation:** A static assert causes the compilation failures in oneTBB headers if the following conditions are satisfied:
+  
+  * Compilation is done with Clang 12.0.0 or a more recent version. 
+  * The LLVM standard library is employed, coupled with the use of the ``-ffreestanding`` flag and C++11/14 compiler options.
+
+**Risk:** The compilation failures. 
+
+Interface Incompatibilities: TBB vs oneTBB
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Limitation:** An application using Parallel STL algorithms in the ``libstdc++`` versions 9 and 10 may fail to compile due to incompatible interface changes between earlier versions of Threading Building Blocks (TBB) and oneAPI Threading Building Blocks (oneTBB). 
+
+**Solution:** Disable support for Parallel STL algorithms by defining ``PSTL_USE_PARALLEL_POLICIES`` (in libstdc++ 9) or ``_GLIBCXX_USE_TBB_PAR_BACKEND`` (in libstdc++ 10) macro to zero before inclusion of the first standard header file in each translation unit.
+
+Incorrect Installation Location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Limitation:** On Linux* OS, if oneAPI Threading Building Blocks (oneTBB) or Threading Building Blocks (TBB) are installed in a system folder, such as ``/usr/lib64``, the application may fail to link due to the order in which the linker searches for libraries.  
+
+**Risk:** The issue does not affect the program execution.
+
+**Solution:** Use the ``-L`` linker option to specify the correct location of oneTBB library. 
+
+``fork()`` Support 
+^^^^^^^^^^^^^^^^^^^
+
+**Limitation:** oneTBB does not support ``fork()``. 
+
+**Solution:** To work-around the issue, consider using ``task_scheduler_handle`` to join oneTBB worker threads before using ``fork()``.
diff --git a/doc/main/tbb_userguide/Package_Contents.rst b/doc/main/tbb_userguide/Package_Contents_os.rst
similarity index 93%
rename from doc/main/tbb_userguide/Package_Contents.rst
rename to doc/main/tbb_userguide/Package_Contents_os.rst
index 30d75c096d..2d9e0a2fe4 100644
--- a/doc/main/tbb_userguide/Package_Contents.rst
+++ b/doc/main/tbb_userguide/Package_Contents_os.rst
@@ -14,4 +14,5 @@ and macOS\* operating systems as described in this section.
    ../tbb_userguide/Scalable_Memory_Allocator
    ../tbb_userguide/Windows_OS_ug
    ../tbb_userguide/Linux_OS
-   ../tbb_userguide/Mac_OS
\ No newline at end of file
+   ../tbb_userguide/Mac_OS
+
diff --git a/doc/main/tbb_userguide/title.rst b/doc/main/tbb_userguide/title.rst
index c073acfc8c..8adb7093fe 100644
--- a/doc/main/tbb_userguide/title.rst
+++ b/doc/main/tbb_userguide/title.rst
@@ -8,7 +8,7 @@
 .. toctree::
    :maxdepth: 4
 
-   ../tbb_userguide/Package_Contents
+   ../tbb_userguide/Package_Contents_os
    ../tbb_userguide/Parallelizing_Simple_Loops_os
    ../tbb_userguide/Parallelizing_Complex_Loops
    ../tbb_userguide/Flow_Graph