feat: add opencl overview and notice

StaticRocket · praneethbajjuri · commit e207149faab6 · 2025-02-27T16:54:49.000-06:00
Add an overview about OpenCL, ICD loaders, and some useful tooling. Also
add a note about Yocto specific issues. Things like this should probably
be aggregated in one place, but until then I assume this will help
people who attempt to use common compute libraries in Yocto.

Signed-off-by: Randolph Sapp &lt;rs@ti.com&gt;
diff --git a/configs/AM62PX/AM62PX_linux_toc.txt b/configs/AM62PX/AM62PX_linux_toc.txt
@@ -123,6 +123,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/AM62X/AM62X_linux_toc.txt b/configs/AM62X/AM62X_linux_toc.txt
@@ -130,6 +130,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/AM67/AM67_linux_toc.txt b/configs/AM67/AM67_linux_toc.txt
@@ -95,6 +95,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/AM67A/AM67A_linux_toc.txt b/configs/AM67A/AM67A_linux_toc.txt
@@ -96,6 +96,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/AM68/AM68_linux_toc.txt b/configs/AM68/AM68_linux_toc.txt
@@ -100,6 +100,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/AM68A/AM68A_linux_toc.txt b/configs/AM68A/AM68A_linux_toc.txt
@@ -100,6 +100,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/AM69/AM69_linux_toc.txt b/configs/AM69/AM69_linux_toc.txt
@@ -100,6 +100,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/AM69A/AM69A_linux_toc.txt b/configs/AM69A/AM69A_linux_toc.txt
@@ -101,6 +101,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/J721E/J721E_linux_toc.txt b/configs/J721E/J721E_linux_toc.txt
@@ -105,6 +105,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/J721S2/J721S2_linux_toc.txt b/configs/J721S2/J721S2_linux_toc.txt
@@ -104,6 +104,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/J722S/J722S_linux_toc.txt b/configs/J722S/J722S_linux_toc.txt
@@ -99,6 +99,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/J742S2/J742S2_linux_toc.txt b/configs/J742S2/J742S2_linux_toc.txt
@@ -103,6 +103,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/configs/J784S4/J784S4_linux_toc.txt b/configs/J784S4/J784S4_linux_toc.txt
@@ -103,6 +103,7 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools
 linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/Vulkan
 linux/Foundational_Components/Graphics/Common/Weston
+linux/Foundational_Components/Graphics/Common/OpenCL
 linux/Foundational_Components/Graphics/Rogue/Overview
 linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info
 linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info
diff --git a/source/linux/Foundational_Components/Graphics/Common/OpenCL.rst b/source/linux/Foundational_Components/Graphics/Common/OpenCL.rst
@@ -0,0 +1,40 @@
+.. include:: <isonum.txt>
+
+######
+OpenCL
+######
+
+The OpenCL\ |trade| libraries are packaged with the |__SDK_FULL_NAME__| and are
+used by compute centric libraries for offloading tasks to the GPU without the
+overhead of managing displays or creating a offscreen context. The drivers run
+on an ARM core and programs the firmware running inside a GPU core with commands
+submitted by the user applications.
+
+OpenCL\ |trade| differs from OpenGL\ |reg| in that it makes use of a predefined
+Installable Client Driver (ICD) Loader to allow applications to query and pick
+the device it deems necessary instead of relying on a predefined mapping between
+a chosen display and backing vendor acceleration implementation. This means that
+typically an application that wants to use OpenCL\ |trade| should link against
+an ICD loader library instead of directly using a specific library.
+
+.. note::
+
+   Tools may choose to dynamically load their respective OpenCL\ |trade| library
+   at runtime using dlopen, which may fail in Yocto based environments. This is
+   usually the result of a clash in philosophies between Yocto and Application
+   developers over the usage of devlinks (also know in Yocto as "dev-so"s). It's
+   Yocto's belief that, for the most part, applications should not attempt to
+   use dev links directly and should instead open the specific version of the
+   library they need. You may choose to patch the application to do this or
+   create the devlink from :file:`/usr/lib/libOpenCL.so` to
+   :file:`/usr/lib/libOpenCL.so.1` manually. Tools provided by Yocto will be
+   patched accordingly already.
+
+A useful tool for debugging OpenCL\ |trade| ICD Loaders and devices is
+:command:`clinfo`. This command, when run without any arguments will present a
+list of all supported devices, associated parameters, and supported extensions.
+
+For more information about OpenCL\ |trade| extensions see:
+
+   - `<https://docs.imgtec.com/performance-guides/compute-recommendations/html/topics/introduction/introduction.html>`__
+   - `<https://registry.khronos.org/OpenCL/>`__
diff --git a/source/linux/Foundational_Components_Graphics.rst b/source/linux/Foundational_Components_Graphics.rst
@@ -33,6 +33,7 @@ the details on the features supported by these hardware blocks.
 
    Foundational_Components/Graphics/Common/OpenGL_ES.rst
    Foundational_Components/Graphics/Common/Vulkan.rst
+   Foundational_Components/Graphics/Common/OpenCL.rst
 
    Foundational_Components/Graphics/Common/QT_Graphics_Framework.rst
    Foundational_Components/Graphics/Common/GTK+_Graphics_Framework.rst
