From c676f6aabaffb5fb12e01462bea5d1f657fc46e6 Mon Sep 17 00:00:00 2001 From: Randolph Sapp Date: Mon, 19 May 2025 18:27:31 -0500 Subject: [PATCH 1/2] chore(graphics): remove Migration_From_Prior_Releases This old migration guide likely won't be updated again. Nothing major is changing and these are all very old versions. Might as well drop it. Signed-off-by: Randolph Sapp --- configs/AM335X/AM335X_linux_toc.txt | 1 - configs/AM437X/AM437X_linux_toc.txt | 1 - configs/AM57X/AM57X_linux_toc.txt | 1 - configs/AM65X/AM65X_linux_toc.txt | 1 - configs/GEN/GEN_linux_toc.txt | 1 - .../SGX/Migration_From_Prior_Releases.rst | 176 ------------------ .../Graphics/index.rst | 1 - 7 files changed, 182 deletions(-) delete mode 100644 source/linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases.rst diff --git a/configs/AM335X/AM335X_linux_toc.txt b/configs/AM335X/AM335X_linux_toc.txt index 88a20b426..565cce74a 100644 --- a/configs/AM335X/AM335X_linux_toc.txt +++ b/configs/AM335X/AM335X_linux_toc.txt @@ -103,7 +103,6 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework linux/Foundational_Components/Graphics/Common/Weston linux/Foundational_Components/Graphics/SGX/AM3_Beagle_Bone_Black_Configuration -linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases linux/Foundational_Components/Graphics/SGX/OMAP_DRM linux/Foundational_Components/Graphics/SGX/Overview linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info diff --git a/configs/AM437X/AM437X_linux_toc.txt b/configs/AM437X/AM437X_linux_toc.txt index 5f8ee2cdb..720ef9919 100644 --- a/configs/AM437X/AM437X_linux_toc.txt +++ b/configs/AM437X/AM437X_linux_toc.txt @@ -103,7 +103,6 @@ linux/Foundational_Components/Graphics/Common/OpenGL_ES linux/Foundational_Components/Graphics/Common/PVR_Tools linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework linux/Foundational_Components/Graphics/Common/Weston -linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases linux/Foundational_Components/Graphics/SGX/OMAP_DRM linux/Foundational_Components/Graphics/SGX/Overview linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info diff --git a/configs/AM57X/AM57X_linux_toc.txt b/configs/AM57X/AM57X_linux_toc.txt index c2ab3d763..c61de7e09 100644 --- a/configs/AM57X/AM57X_linux_toc.txt +++ b/configs/AM57X/AM57X_linux_toc.txt @@ -105,7 +105,6 @@ linux/Foundational_Components/Graphics/Common/OpenGL_ES linux/Foundational_Components/Graphics/Common/PVR_Tools linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework linux/Foundational_Components/Graphics/Common/Weston -linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases linux/Foundational_Components/Graphics/SGX/OMAP_DRM linux/Foundational_Components/Graphics/SGX/Overview linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info diff --git a/configs/AM65X/AM65X_linux_toc.txt b/configs/AM65X/AM65X_linux_toc.txt index 2c45686db..03f702dd4 100644 --- a/configs/AM65X/AM65X_linux_toc.txt +++ b/configs/AM65X/AM65X_linux_toc.txt @@ -101,7 +101,6 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework linux/Foundational_Components/Graphics/Common/Weston linux/Foundational_Components/Graphics/SGX/AM3_Beagle_Bone_Black_Configuration -linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases linux/Foundational_Components/Graphics/SGX/OMAP_DRM linux/Foundational_Components/Graphics/SGX/Overview linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info diff --git a/configs/GEN/GEN_linux_toc.txt b/configs/GEN/GEN_linux_toc.txt index df3729ba6..38f1a1afb 100644 --- a/configs/GEN/GEN_linux_toc.txt +++ b/configs/GEN/GEN_linux_toc.txt @@ -128,7 +128,6 @@ linux/Foundational_Components/Graphics/Common/PVR_Tools linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework linux/Foundational_Components/Graphics/Common/Weston linux/Foundational_Components/Graphics/SGX/AM3_Beagle_Bone_Black_Configuration -linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases linux/Foundational_Components/Graphics/SGX/OMAP_DRM linux/Foundational_Components/Graphics/SGX/Overview linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info diff --git a/source/linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases.rst b/source/linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases.rst deleted file mode 100644 index 78aae7bf5..000000000 --- a/source/linux/Foundational_Components/Graphics/SGX/Migration_From_Prior_Releases.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. - This subsection provides details on the migration of the SDK from older - releases. - -############################# -Migration from prior releases -############################# - -.. _from-processor-sdk-1-x-to-2-x-for-am3-am4: - -****************************************** -From Processor SDK 1.x to 2.x for AM3, AM4 -****************************************** - -The SGX driver has been enhanced to support DRM based Full Window -Display in processor SDK 2.0 and the FBdev based Full Window modes are -no longer supported. The System startup and most of the Graphics -applications are backward-compatible except with the following changes. - -Window System Libraries -======================= - -The FBdev based Full Screen window systems are no longer supported: - - - ``libpvrPVR2D_FRONTWSEGL.so`` (for direct writes to FrameBuffer - FRONT - mode of operation - directly writes to FrameBuffer without waiting for - vsync - fastest mode of operation) - - - ``libpvrPVR2D_FLIPWSEGL.so`` (for VSync synchronised writes to Framebuffer - - slower, but avoids tearing) - - - ``libpvrPVR2D_BLITWSEGL.so`` (for direct writes to back-buffer, which later - gets written to ``*FrameBuffer`` with sync) - -Instead the DRM based Full Screen window system are provided: - - - ``libpvrDRMWSEGL_FRONT.so`` (for direct writes to DRM FrameBuffer - FRONT - mode of operation - directly writes to FrameBuffer without waiting for - vsync - fastest mode of operation) - - - ``libpvrDRMWSEGL.so`` (for VSync synchronised writes to DRM Framebuffer - - slower, but avoids tearing) - -The window system is specified by the PVR configuration parameter WindowSystem -at the PVR configuration file :file:`/etc/powervr.ini`. By default, that -parameter is set to ``libpvrDRMWSEGL_FRONT.so`` for nullDRM Front mode. To -configure the PVR SGX to operate in nullDRM FLIP mode, edit the PVR -configuration file to set the parameter WindowSystem to ``libpvrDRMWSEGL.so``. -The change will take effect when any graphic application is launched next time. - - -Obsolete Test Programs -====================== - -The following test programs are no longer applicable and removed from -the SDK file system: - - - :file:`/usr/bin/sgx_blit_test` - - - :file:`/usr/bin/sgx_flip_test` - - - :file:`/usr/bin/sgx_render_flip_test` - - - :file:`/usr/bin/sgx_render_test` - -.. _from-processor-sdk-2-0-0-to-2-0-x-for-am4: - -***************************************** -From Processor SDK 2.0.0 to 2.0.x for AM4 -***************************************** - -The SGX driver has been enhanced to support DRM/WAYLAND based -Multi-Window Display in processor SDK 2.0.1. The System startup and most -of the Graphics applications are backward-compatible except with the -following changes. - -Window System Libraries -======================= - -The DRM based Full Screen window systems are no longer supported: - - - ``libpvrDRMWSEGL_FRONT.so`` (for direct writes to DRM FrameBuffer - FRONT - mode of operation - directly writes to FrameBuffer without waiting for - vsync - fastest mode of operation) - - - ``libpvrDRMWSEGL.so`` (for VSync synchronised writes to DRM Framebuffer - - slower, but avoids tearing) - -Instead the DRM/WAYLAND based multi-window system are provided: - -- ``libpvrws_KMS.so`` -- ``libpvrws_WAYLAND.so`` - -The window system will be dynamically loaded by DDK based on the application use -case, so that the PVR configuration parameter WindowSystem at the PVR -configuration file :file:`/etc/powervr.ini` is no longer used. - -.. _from-processor-sdk-2-0-1-to-2-0-x-for-am3-4-5: - -********************************************** -From Processor SDK 2.0.1 to 2.0.x for AM3/4/5 -********************************************** - -The SGX driver has been enhanced to support DRM-based Full -Screen(NullDRM) and Multi-Window(Wayland) Display in processor SDK -2.0.2. The System startup and most of the Graphics applications are -backward-compatible except with the following changes. - -Window System Libraries -======================= - -The DRM based Full Screen window system is supported: - - - ``libpvrDRMWSEGL.so`` (for VSync synchronised writes to DRM Framebuffer - - slower, but avoids tearing) - -The DRM/WAYLAND based multi-window systems are also provided: - - - ``libpvrGBMWSEGL.so`` - - - ``libpvrws_WAYLAND.so`` - -The window system will be dynamically loaded by DDK based on the -application use case, so that the PVR configuration parameter -WindowSystem at the PVR configuration file /etc/powervr.ini is no longer -required. - -.. _from-processor-sdk-3-1-to-3-x-for-am3-4-5: - -***************************************** -From Processor SDK 3.1 to 3.x for AM3/4/5 -***************************************** - -The QT QPA ``eglfs_kms``, which supports multiple screens, has been enabled -and used as the default eglfs platform plugin in processor SDK 3.2. To -fallback to the standard single-screen eglfs plugin, issue the following -instruction at the command line or add the same at the QT environment -configuration file :file:`/etc/profile.d/qt_env.sh`. - -.. code-block:: console - - export QT_QPA_EGLFS_INTEGRATION=none - -.. _from-processor-sdk-6-1-to-6-2-for-am3-4-5-6: - -******************************************* -From Processor SDK 6.1 to 6.2 for AM3/4/5/6 -******************************************* - -The SGX driver has been enhanced to replace IMG WSEGL with MESA-EGL which -supports the essential EGL 1.5 extensions required by the latest versions -of certain graphics applications such as Chromium browser. The System -startup and most of the Graphics applications are backward-compatible except -with the following changes. - -Window System Libraries -======================= - -With MESA-EGL, all window system modules are embedded in the libEGL.so, both -GBM(DRM) full-screen and Wayland window systems are supposrted and dynamically -invoked based on the application use case. The following IMG WSEGL libraries are -no longer used and provided: - - - ``libpvrDRMWSEGL.so`` - - - ``libpvrGBMWSEGL.so`` - - - ``libpvrws_WAYLAND.so`` - -The QT QPA eglfs raw mode is no longer supported and thus should be replaced -with eglfs_kms by setting the environment variable at the QT environment -configuration file :file:`/etc/profile.d/qt_env.sh`. - -.. code-block:: console - - export QT_QPA_EGLFS_INTEGRATION=eglfs_kms diff --git a/source/linux/Foundational_Components/Graphics/index.rst b/source/linux/Foundational_Components/Graphics/index.rst index 95d97efdc..90e4e415c 100644 --- a/source/linux/Foundational_Components/Graphics/index.rst +++ b/source/linux/Foundational_Components/Graphics/index.rst @@ -20,7 +20,6 @@ the details on the features supported by these hardware blocks. SGX/Overview.rst SGX/SGX_Debug_Info.rst SGX/AM3_Beagle_Bone_Black_Configuration.rst - SGX/Migration_From_Prior_Releases.rst SGX/OMAP_DRM.rst SGX/Build_Guide.rst From f9f68e06fb5c25a49a753e1bce2feec3dad0a6ca Mon Sep 17 00:00:00 2001 From: Randolph Sapp Date: Mon, 19 May 2025 18:25:12 -0500 Subject: [PATCH 2/2] fix(graphics): follow almost all vale suggestions Follow almost every vale suggestion. Signed-off-by: Randolph Sapp --- .../Graphics/Common/Display.rst | 98 +++++----- .../Common/GTK+_Graphics_Framework.rst | 19 +- .../Graphics/Common/OpenCL.rst | 27 ++- .../Graphics/Common/OpenGL_ES.rst | 9 +- .../Graphics/Common/PVR_Tools.rst | 47 +++-- .../Graphics/Common/QT_Graphics_Framework.rst | 40 ++--- .../Graphics/Common/Vulkan.rst | 14 +- .../Graphics/Common/Weston.rst | 100 +++++------ .../Graphics/Rogue/Build_Guide.rst | 170 +++++++++--------- .../Graphics/Rogue/Overview.rst | 45 ++--- .../Graphics/Rogue/Rogue_Debug_Info.rst | 50 +++--- .../Rogue/Rogue_Power_Management_Info.rst | 52 +++--- .../AM3_Beagle_Bone_Black_Configuration.rst | 34 ++-- .../Graphics/SGX/Build_Guide.rst | 141 +++++++-------- .../Graphics/SGX/OMAP_DRM.rst | 62 ++++--- .../Graphics/SGX/Overview.rst | 65 ++++--- .../Graphics/SGX/SGX_Debug_Info.rst | 98 +++++----- 17 files changed, 529 insertions(+), 542 deletions(-) diff --git a/source/linux/Foundational_Components/Graphics/Common/Display.rst b/source/linux/Foundational_Components/Graphics/Common/Display.rst index d759f9730..ee3f15fb4 100644 --- a/source/linux/Foundational_Components/Graphics/Common/Display.rst +++ b/source/linux/Foundational_Components/Graphics/Common/Display.rst @@ -2,29 +2,28 @@ Display ####### -TI SoCs are equipped with Display SubSystem (DSS) hardware to provide hardware -acceleration for alpha blending of overlays and color conversion. The DSS -hardware is exposed to the software drm API available through ``libdrm`` module. -Through this drm interface, a user space program can perform *mode setting* of -the display. +TI SoCs with Display Sub-System (DSS) hardware offer hardware acceleration for +alpha blending of overlays and color conversion. The ``libdrm`` module exposes +DSS hardware through the software Direct Render Management (DRM) API. Through +this DRM interface, a user space program can perform *mode setting* of the +display. -The drm module models the display hardware as a series of abstract hardware +The DRM module models the display hardware as a series of abstract hardware blocks and manages them through the API. The blocks are: - CRTC\ [#f1]_\: represents a scanout engine that generates video timing signal from the data pointed to by the scanout buffer - - Connector: represents where the video timing signal is sent across to the - display + - Connector: represents where the video timing signal goes and how it gets + there - - Encoder: transforms the video timing signal from CRTC to a format that is - suitable for sending across the connector + - Encoder: transforms the video timing signal from the CRTC to a format that + is suitable for sending to the connector - - Plane: represents the overlay buffer that a CRTC can be fed with + - Plane: represents the overlay buffer that will feed a CRTC -A utility application ``modetest`` can be used to get the list of available drm -blocks. All the information available for the device can be displayed by using -it. +The list of available DRM blocks is viewable using the application +:command:`modetest`. .. ifconfig:: CONFIG_image_type in ('adas') @@ -37,11 +36,13 @@ it. linux-dtbs and install. Also need to disable Display in r5f, rebuild r5f FW using PSDK RTOS. -******************** -Finding Connector ID -******************** +.. _finding_the_connector_id: -Run the below ``modetest`` command: +************************ +Finding the connector ID +************************ + +Run the following ``modetest`` command: .. ifconfig:: CONFIG_part_family in ('General_family', 'AM335X_family', 'AM437X_family') @@ -55,8 +56,8 @@ Run the below ``modetest`` command: # modetest -M tidss -c -Look for the display device for which the connector ID is required - -such as HDMI, LCD etc. +Look for the required display device's connector ID - such as High-Definition +Multimedia Interface (HDMI), DisplayPort (DP), and so on. .. code-block:: text @@ -75,9 +76,9 @@ such as HDMI, LCD etc. The modes displayed are the various resolutions supported by the connected display. -**************** -Finding Plane ID -**************** +******************** +Finding the plane ID +******************** To find the Plane ID, run the ``modetest`` command: @@ -93,7 +94,7 @@ To find the Plane ID, run the ``modetest`` command: # modetest -M tidss -p -Which should show something like below: +Which should show something similar to the following: .. code-block:: text @@ -108,43 +109,44 @@ Which should show something like below: props: ... -******************************* -Using Connector ID and Plane ID -******************************* +*********************************** +Using the connector ID and plane ID +*********************************** -The above information may be used with some userspace applications to control -which displays are rendered to. These applications are using what is known as -kernel mode setting (kms). For more information about kernel mode setting see -the `upstream kms documentation`_. In this section you only need to keep 2 -things in mind: +The earlier information is useful when attempting to select what display to +render to. Some user space applications have command line switches to easily +show this. These applications are using Kernel Mode Setting (KMS). For more +information about KMS see the `upstream kms documentation`_. For now, you only +need to keep 2 things in mind: - #. Applications that intend to interact with the kms interface usually don't - need any user input. They can query device info through the interface and - will normally pick the first connected display automatically. + #. Applications that intend to interact with the KMS interface usually do not + need any user input. They can query device info through the interface + and will normally pick the first connected display automatically. - #. Only one application can manage the kms interface at a time. Weston is - normally the first graphical application started out of the box and as - such it will prevent you from starting any other kms applications. See - :ref:`stopping-weston` if you want to use another kms application. + #. Only one application can manage the KMS interface at a time. Weston is + normally the first graphical application started by default and as such + it will prevent you from starting any other KMS applications. See + :ref:`stopping-weston` if you want to use another KMS application. .. _upstream kms documentation: https://www.kernel.org/doc/html/latest/gpu/drm-kms.html -That being said, if you wish to change rendering behavior for an application -check with that applications documentation for a way to specify connector, -plane, and / or crtc information. One kms application we include is ``kmscube``. -Below are some examples on how to alter it's default behavior. +If you want to change rendering behavior for an application check with that +applications documentation for a way to specify a connector, plane, and / or +CRTC information. One KMS application we include is :command:`kmscube`. Below +are some examples on how to avoid the default behavior of automatically choosing +a display to render to. -Run kmscube on the default display: +Run :command:`kmscube` on the default display: .. code-block:: console # kmscube -Run kmscube on the secondary display: +Run :command:`kmscube` on the secondary display: .. code-block:: console - # kmscube -n + # kmscube -n For example, if the connector id for the secondary display is 16: @@ -154,7 +156,7 @@ For example, if the connector id for the secondary display is 16: .. [#f1] - CRTC stands for cathode-ray tube controller, a throw back to the old + CRTC stands for Cathode-Ray Tube Controller, a throw back to the old `cathode-ray tubes TV's `_ which had a controller that generated video timings based on the data it is - being fed by a buffer. + receiving from a buffer. diff --git a/source/linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework.rst b/source/linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework.rst index 9757d95b1..6503a8e14 100644 --- a/source/linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework.rst +++ b/source/linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework.rst @@ -2,14 +2,14 @@ This subsection provides details on the GTK+ graphics frameworks ####################### -GTK+ Graphics Framework +GTK+ graphics framework ####################### GTK+, or the GIMP Toolkit, is a multi-platform toolkit for creating graphical -user interfaces. Offering a complete set of widgets, GTK+ is suitable for +user interfaces. Offering a complete set of widgets, GTK+ is suitable for projects ranging from small one-off tools to complete application suites. -Please refer to ``_ for additional details on GTK+. +See ``_ for additional details on GTK+. The PSDK target file system includes the pre-built GTK+ libraries under :file:`/usr/lib` for GTK+3 over Wayland support. There is also a comprehensive @@ -20,15 +20,14 @@ APIs and their usages. Demos ***** -GTK+ will attempt to interact with a windowing system on startup. If one is not -running, or it fails to connect to one for any reason, you will see the -following error: +GTK+ will interact with a windowing system on startup. If one is not running, or +it fails to connect to one for any reason, you will see the following error: .. code-block:: text - (:): Gtk-WARNING **: 21:21:27.361: cannot open display: + (:): Gtk-WARNING **: 21:21:27.361: cannot open display: -If no display value is returned, then you are more than likely missing the -``WAYLAND_DISPLAY`` environment variable. Check the :doc:`Weston` -section for more information. +If no display value is present, then you are more than likely missing the +``WAYLAND_DISPLAY`` environment variable. Check the :doc:`Weston` section for +more information. diff --git a/source/linux/Foundational_Components/Graphics/Common/OpenCL.rst b/source/linux/Foundational_Components/Graphics/Common/OpenCL.rst index 90a553470..e5d2cf5e4 100644 --- a/source/linux/Foundational_Components/Graphics/Common/OpenCL.rst +++ b/source/linux/Foundational_Components/Graphics/Common/OpenCL.rst @@ -4,11 +4,11 @@ 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. +The OpenCL\ |trade| libraries in the |__SDK_FULL_NAME__| allow offloading tasks +to the GPU for compute centric libraries without the GPU or CPU usage incurred +by 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 @@ -19,16 +19,15 @@ 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 + Some tools dynamically load their respective OpenCL\ |trade| library at + runtime by using dlopen, which can 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. + developers over the usage of devlinks (also know in Yocto as "dev-so"s). It + is Yocto's belief that, for the most part, applications should not try to use + dev links directly and should instead open the specific version of the + library they need. You can 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 are already patched. A useful tool for debugging OpenCL\ |trade| ICD Loaders and devices is :command:`clinfo`. This command, when run without any arguments will present a diff --git a/source/linux/Foundational_Components/Graphics/Common/OpenGL_ES.rst b/source/linux/Foundational_Components/Graphics/Common/OpenGL_ES.rst index 9041e676e..ebd941d5b 100644 --- a/source/linux/Foundational_Components/Graphics/Common/OpenGL_ES.rst +++ b/source/linux/Foundational_Components/Graphics/Common/OpenGL_ES.rst @@ -4,10 +4,11 @@ OpenGL ES ######### -The OpenGL\ |reg| ES and EGL\ |reg| libraries are packaged with the -|__SDK_FULL_NAME__| and are used by graphics stacks such as Wayland/Weston. The -drivers run on an ARM core and programs the firmware running inside a GPU core -with rendering commands submitted by the user applications. +The OpenGL\ |reg| ES and EGL\ |reg| libraries packaged with the +|__SDK_FULL_NAME__| used by graphics stacks such as Wayland/Weston provide +accelerated rendering capabilities. The drivers run on an ARM core and program +the firmware running inside a GPU core with rendering commands submitted by the +user applications. For more information about OpenGL\ |reg| ES and EGL\ |reg| extensions see: diff --git a/source/linux/Foundational_Components/Graphics/Common/PVR_Tools.rst b/source/linux/Foundational_Components/Graphics/Common/PVR_Tools.rst index eb02454c3..1e90d9e83 100644 --- a/source/linux/Foundational_Components/Graphics/Common/PVR_Tools.rst +++ b/source/linux/Foundational_Components/Graphics/Common/PVR_Tools.rst @@ -1,38 +1,35 @@ .. include:: ############# -PowerVR Tools +PowerVR tools ############# -The suite of PowerVR Tools is designed to enable rapid graphics application -development. It targets a range of areas including asset exporting and -optimization, PC emulation, prototyping environments, on-line and off-line -performance analysis tools and many more. Please refer to PowerVR-SDK_ for -additional details on the tools and detailed documentation. +The suite of PowerVR Tools exist to help enable rapid graphics application +development. They target a range of areas including asset exporting and +optimization, PC emulation, prototyping environments, online and offline +performance analysis tools and many more. See PowerVR-SDK_ for additional +details on the tools and detailed documentation. -There are a number of useful tools available in the Imagination PowerVR SDK that -are compatible with our devices. Two of the most useful tools available are -PVRTune and PVRCarbon, which can be used for to profiling and tracing GFX -activities. +There are several useful tools available in the Imagination PowerVR SDK that are +compatible with our devices. Two of the most useful tools available are PVRTune +and PVRCarbon, which enable profiling and tracing of Graphics (GFX) activities. -Previously these were included in the target's rootfs, but these were removed -due to tight version dependencies between the target and host tools. Imagination -has moved to packaging the target binaries with their host installer, so we -recommend using those binaries directly for guaranteed compatibility. +Imagination has moved to packaging the target binaries with their host +installer, so we recommend using those binaries directly for guaranteed +compatibility. ******* PVRTune ******* The PVRTune utility is a real-time GPU performance analysis tool. It captures -hardware timing data and counters which facilitate the identification of -performance bottlenecks. PVRPerfServer should be used along with the PVRTune -running on the PC to gather data on the SGX loading and activity threads. The -target binaries can be found in the host's PVRTune installation directory under -PVRPerfServer. +hardware timing data and counters that ease the identification of performance +bottlenecks. PVRPerfServer collects data that is displayed with the PVRTune +running on the PC. The target binaries reside in the host's PVRTune installation +directory under :file:`PVRPerfServer`. -For more information please refer to Imagination's upstream documentation on -PVRTune and PVRPerfServer. +For more information see Imagination's upstream documentation on PVRTune and +PVRPerfServer. - ``_ @@ -43,11 +40,11 @@ PVRCarbon The PVRCarbon is an OpenGL\ |reg| ES and Vulkan |reg| API recording and analysis utility. PVRCarbon GUI provides off-line tools to inspect captured data, identify redundant calls, highlight costly shaders and many more. This tool can -capture traces on target and then play them back on multiple different devices -by introducing shim libraries in place of the standard offering for that API. +capture traces on target and then play them back on different devices by +introducing shim libraries in place of the standard offering for that API. -This requires a little bit of setup on the target though. Please refer to -Imagination's upstream target setup guide for the most recent instructions. +This requires a little bit of setup on the target though. See Imagination's +upstream target setup guide for the most recent instructions. - ``_ diff --git a/source/linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework.rst b/source/linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework.rst index cfc3b231c..82f6f75db 100644 --- a/source/linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework.rst +++ b/source/linux/Foundational_Components/Graphics/Common/QT_Graphics_Framework.rst @@ -2,7 +2,7 @@ This subsection provides details on the QT graphics frameworks ##################### -Qt Graphics Framework +Qt graphics framework ##################### Qt is a powerful C++ toolkit for writing cross-platform graphics @@ -12,15 +12,15 @@ well on Windows and embedded platforms, Please refer ``__ for additional details on Qt. The PSDK target file system includes the pre-built Qt libraries under -:file:`/usr/lib` and a rich set of QT demo applications under +:file:`/usr/lib` and a rich set of Qt demo applications under :file:`/usr/share/examples`. ***** Demos ***** -Demos using the Null Window System / KMS / DRM / EGLFS are -provided with Qt. By default EGLFS will use the ``eglfs_kms`` backend. +Qt provides demos for the Null Window System / KMS / DRM / EGL Full Screen +(EGLFS) backends. By default EGLFS will use the ``eglfs_kms`` backend. .. code-block:: console @@ -28,24 +28,24 @@ provided with Qt. By default EGLFS will use the ``eglfs_kms`` backend. $ /usr/share/examples/opengl/2dpainting/bin/2dpainting -platform eglfs $ /usr/share/examples/opengl/openglwindow/bin/openglwindow -platform eglfs -For more information about Qt's EGLFS and using Qt6 in embedded -applications see: +For more information about the EGLFS platform abstraction and using Qt6 in +embedded applications see: - https://doc.qt.io/qt-6/embedded-linux.html -****** -Qt QPA -****** +*********************** +Qt platform abstraction +*********************** -The Qt6 within PSDK is prebuilt with Wayland enabled and therefore -wayland-egl is the default QPA. Hence all Qt applications should be run -on top of Weston. To run Qt application without Weston, the user can use -``-platform`` option to specify the desired QPA as ``linuxfb`` or ``eglfs``. +The Qt6 within PSDK is prebuilt with Wayland enabled and therefore wayland-egl +is the default Qt Platform Abstraction (QPA). Therefore all Qt applications +should run on top of Weston. To run Qt application without Weston, the user can +use ``-platform`` option to specify the desired QPA as ``linuxfb`` or ``eglfs``. .. note:: - The ``linuxfb`` inteface is deprecated and requires switching the display - into legacy fb mode. + The ``linuxfb`` interface is deprecated and requires switching the display + into "legacy" framebuffer mode. For example: @@ -53,12 +53,12 @@ For example: $ /usr/share/examples/opengl/2dpainting/bin/2dpainting -platform eglfs -************************************************* -Running Qt Applications with the Weston IVI shell -************************************************* +********************************************************************* +Running Qt applications with the Weston In-Vehicle Infotainment shell +********************************************************************* -To run the QT application with ivi-shell, set the -``QT_WAYLAND_SHELL_INTEGRATION`` environment variable to ivi-shell. +To run the Qt application with In-Vehicle Infotainment (IVI) shell, set the +following environment variable, ``QT_WAYLAND_SHELL_INTEGRATION=ivi-shell``. .. code-block:: console diff --git a/source/linux/Foundational_Components/Graphics/Common/Vulkan.rst b/source/linux/Foundational_Components/Graphics/Common/Vulkan.rst index 5f84ecc24..228615bc7 100644 --- a/source/linux/Foundational_Components/Graphics/Common/Vulkan.rst +++ b/source/linux/Foundational_Components/Graphics/Common/Vulkan.rst @@ -4,20 +4,20 @@ Vulkan ###### -The Vulkan\ |reg| libraries are packaged with the |__SDK_FULL_NAME__| and can be -used by graphics stacks such as Qt and GTK. The drivers run on an ARM core and +The Vulkan\ |reg| libraries packaged with |__SDK_FULL_NAME__| offer acceleration +for graphics stacks such as Qt and GTK. The drivers run on an ARM core and programs the firmware running inside a GPU core with rendering commands submitted by the user applications. Vulkan\ |reg| is a relatively new API that focuses on increased verbosity and control over the device as opposed to OpenGL\ |reg| ES, which was initially intended to abstract common processing functions for developers. As a result, it -can be written by hand but it is usually advised to use an existing abstraction -framework, such as the previously mentioned GTK or Qt widget based framework. +is usually advised to use an existing abstraction framework, such as the before +mentioned GTK or Qt widget based frameworks. -Like OpenCL\ |trade|, Vulkan\ |reg| has an 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 +Similar to OpenCL\ |trade|, Vulkan\ |reg| has an Installable Client Driver (ICD) +Loader to allow applications to query and pick the device it deems necessary. It +does not relying on a predefined mapping between a chosen display and backing vendor acceleration implementation. This means that typically an application that wants to use Vulkan\ |reg| should link against an ICD loader library instead of directly using a vendor specific library. diff --git a/source/linux/Foundational_Components/Graphics/Common/Weston.rst b/source/linux/Foundational_Components/Graphics/Common/Weston.rst index adb570a82..398b0593e 100644 --- a/source/linux/Foundational_Components/Graphics/Common/Weston.rst +++ b/source/linux/Foundational_Components/Graphics/Common/Weston.rst @@ -2,18 +2,17 @@ Weston ###### -The supported Wayland/Weston version brings in the multiple display support in -extended desktop mode and the ability to drag-and-drop windows from one display -to the other. - -Weston has support for multiple backends. By default it will use the ``drm`` -backend unless the ``WAYLAND_DISPLAY`` environment variable is set. This backend -will register the compositor as the controller of the kms interface and will -pick up human interface device (HID) input using evdev. - -If the ``WAYLAND_DISPLAY`` variable is set, Weston will attempt to use the -``wayland`` backend for nested composition. This is useful for development, but -is normally not what you want for standard composition use. See +Weston provides support for many displays in an extended desktop mode and the +ability to drag-and-drop windows from one display to the other. + +It has support for many backends. By default it will use the ``drm`` backend +unless given the ``WAYLAND_DISPLAY`` environment variable. This backend will +register the compositor as the controller of the KMS interface and will pick up +human interface device (HID) input by using ``evdev``. + +If the ``WAYLAND_DISPLAY`` variable is present, Weston will use the ``wayland`` +backend for nested composition. This is useful for development, but is normally +not what you want for standard composition use. See :ref:`starting-weston-manually` or `the upstream weston documentation`_ for more information. @@ -33,7 +32,7 @@ information. # weston --drm-device=card0 --additional-devices=card1 - You may also modify the weston service to have systemd do this automatically + You may also modify the Weston service to have systemd do this automatically on launch by editing :file:`/usr/share/wayland-sessions/weston.desktop` and modifying the ``Exec`` line: @@ -50,15 +49,16 @@ Starting Weston with Emptty *************************** Starting with SDK 11.0, the preferred way to start Weston is with the ``weston`` -user using the display manager ``emptty``. Emptty is a console based display +user, using the display manager ``emptty``. Emptty is a console based display manager that coordinates the loading of devices with the initialization of any -specified graphical environment. By default, it is configured to automatically -start ``weston`` under the weston user on device startup. +specified graphical environment. By default it will automatically start +``weston`` under the weston user on device startup. -If you need to interact with this instance using any other user then make sure -that user is capable of interacting with the wayland socket :file:`wayland-1` -under the weston user's ``XDG_RUNTIME_DIR``, :file:`/run/user/1000/`. We do not -recommend running graphical applications as root. +If you need to interact with this instance with any other user, then make sure +that user is capable of interacting with the wayland socket. This will be +:file:`wayland-1` under the ``weston`` user's ``XDG_RUNTIME_DIR``, +:file:`/run/user/1000/`. We do not recommend running graphical applications as +root. To start the systemd service manually, do the following: @@ -75,10 +75,10 @@ To inspect the systemd service status, do the following: .. _starting-weston-manually: ************************ -Starting Weston Manually +Starting Weston manually ************************ -To launch Weston manually with the DRM backend, do the following: +To start Weston manually with the DRM backend, do the following: On the default display: @@ -98,35 +98,35 @@ On all connected displays (LCD and HDMI): # weston -By default, the screensaver timeout is configured to 300 seconds. The user can -change the screensaver timeout using a command line option: +By default, the screen saver timeout will be 300 seconds. The user can change +the screen saver timeout using a command line option: .. code-block:: text --idle-time= For example, to set timeout of 10 minutes and Weston configured to -display on all connectors, use the below command: +display on all connectors, use the following command: .. code-block:: console # weston --idle-time=600 To disable the screen timeout and to configure Weston to display on all -connectors, use the below command: +connectors, use the following command: .. code-block:: console # weston --idle-time=0 -If you face any issues with the above procedure, please refer to `the upstream -weston documentation`_ for troubleshooting tips. +If you face any issues with the earlier procedure, see `the upstream weston +documentation`_ for troubleshooting tips. .. _the upstream weston documentation: https://wayland.pages.freedesktop.org/weston/toc/running-weston.html -The filesystem comes with a preconfigured :file:`weston.ini` file which will -be located at :file:`/etc/xdg/weston/weston.ini` +The filesystem includes a preconfigured :file:`weston.ini` file located at +:file:`/etc/xdg/weston/weston.ini`. .. _stopping-weston: @@ -134,17 +134,17 @@ be located at :file:`/etc/xdg/weston/weston.ini` Stopping Weston *************** -Terminate all Weston clients before exiting Weston. If you have invoked +Stop all Weston clients before exiting Weston. If you have invoked Weston from the serial console, exit Weston by pressing Ctrl-C. -If Weston was started automatically by the display manager then it can be -stopped with: +If Weston started automatically through the display manager, then it the +following will stop it: .. code-block:: console # systemctl stop emptty -It is also possible to invoke Weston from the native console, exit +It is also possible to start Weston from the native console, exit Weston by pressing Ctrl-Alt-Backspace. ********************** @@ -176,24 +176,24 @@ able to use the keyboard and the mouse for various controls. Running multimedia with Wayland sink ************************************ -The GStreamer video sink for Wayland is the waylandsink. To use this +The GStreamer video sink for Wayland is the ``waylandsink``. To use this video-sink for video playback: .. code-block:: console - # gst-launch-1.0 playbin uri=file:// video-sink=waylandsink + # gst-launch-1.0 playbin uri=file:// video-sink=waylandsink -*********************** -Using IVI shell feature -*********************** +******************************************* +Using in-vehicle infotainment shell feature +******************************************* -The SDK also has support for configuring Weston ivi-shell. The default shell -that is configured in the SDK is the desktop-shell. +The SDK also has support for configuring Weston ivi-shell. The default shell in +the SDK is the desktop-shell. To change the shell to ivi-shell, the user will have to add the following lines into the :file:`/etc/xdg/weston/weston.ini`. -To switch back to the desktop-shell can be done by commenting these lines in the +To switch back to the desktop-shell, comment these lines in the :file:`/etc/xdg/weston/weston.ini` (comments begin with a '#' at the start of line). @@ -202,8 +202,8 @@ line). [core] shell=ivi-shell.so -After the above configuration is completed, we can restart Weston by -running the following command: +After the earlier configuration, we can restart Weston by running the following +command: .. code-block:: console @@ -214,14 +214,14 @@ running the following command: When Weston starts with ivi-shell, the default background is black, this is different from the desktop-shell that brings up a window with background. -With ivi-shell configured for Weston, Wayland client applications use -ivi-application protocol to be managed by a central HMI window management. +With ivi-shell configured for Weston, a central Human Machine Interface (HMI) +manages Wayland client applications and they can use ivi-application protocol to +interact with it. -Applications must support the ``ivi_application`` Wayland protocol to be managed by -the HMI central controller with an unique numeric ID. +The HMI central controller will assign clients with an unique numeric ID +assuming they support the ``ivi_application`` Wayland protocol. -Some important references to Weston IVI-shell can be found at the following -link: +See the following for more information about the Weston IVI-shell: - ``_ diff --git a/source/linux/Foundational_Components/Graphics/Rogue/Build_Guide.rst b/source/linux/Foundational_Components/Graphics/Rogue/Build_Guide.rst index d859a5a17..5814e33de 100644 --- a/source/linux/Foundational_Components/Graphics/Rogue/Build_Guide.rst +++ b/source/linux/Foundational_Components/Graphics/Rogue/Build_Guide.rst @@ -1,90 +1,90 @@ ########### -Build Guide +Build guide ########### -The graphics stack on rogue has fluctuated a little over the years as we've -adjusted for binary longevity in the proprietary stack. This will attempt to go -over some of the discrepancies between releases and how you can build the -releases stand alone. +The graphics stack on rogue has fluctuated a little over the years as we have +adjusted for binary longevity in the proprietary stack. This will go over some +of the discrepancies between releases and how you can build the releases stand +alone. ***************** -Proprietary Stack +Proprietary stack ***************** The proprietary stack has been our default offering for all releases so far. It consists of 3 main components with varying classifications: - The kernel module (KM) (Open Source, but out-of-tree) - - The GLES / Vulkan / OpenCL implementation (UM) (Closed Source, binary release) + - The GLES / Vulkan / OpenCL user mode (UM) libraries (Closed Source, binary + release) - The mesa shim (Open Source, but out-of-tree) -All 3 of these components are required for GLES and Vulkan support. Exceptions -will be covered in :ref:`rogue-proprietary-mesa-components`. +GLES and Vulkan support requires all 3 of these components. Exceptions will are +in :ref:`rogue-proprietary-mesa-components`. -Proprietary Kernel Module +Proprietary kernel module ========================= -The kernel module is required for: +The kernel module provides: - Memory and power management - Loading firmware - Monitoring device state - Orchestrating hardware recoveries - - Creating an interface for the userspace server + - Creating an interface for the user space server -The source for the component is available at: +The source is available at: https://git.ti.com/cgit/graphics/ti-img-rogue-driver/ .. _rogue-building-the-proprietary-kernel-module: -Building the Proprietary Kernel Module +Building the proprietary kernel module -------------------------------------- Pick a branch that corresponds to your particular kernel. Keep note of the name. -The UM component must match this release. +The UM part must match this release. The :file:`INSTALL` file gives a brief overview of how to build and install the -module. This gives you the common variables, but it does leave out some of the -more important ones for the build. The following variables are key and *must* -match with the values used in the UM release: +module. This gives you the common variables, but it does omit some of the more +important ones for the build. The following variables are key and *must* match +with the values used in the UM release: - ``BUILD`` -- Options: ``release`` or ``debug`` - ``PVR_BUILD_DIR`` -- Options: ``_linux``, for example ``am62_linux`` - - ``WINDOW_SYSTEM`` -- Options: ``lws-generic``, ``xorg``, ``wayland``, ... + - ``WINDOW_SYSTEM`` -- Options: ``lws-generic``, ``xorg``, ``wayland``, among + others -These variables must be set for the build. To check for updated build variables -please see the ``EXTRA_OEMAKE`` variable in the `ti-img-rogue-driver recipe in -meta-ti`_. This will always contain the latest required variables to compile the -driver. +These variables are mandatory. To check for updated build variables see the +``EXTRA_OEMAKE`` variable in the `ti-img-rogue-driver recipe in meta-ti`_. This +will always contain the latest required variables to compile the driver. .. _ti-img-rogue-driver recipe in meta-ti: https://git.ti.com/cgit/arago-project/meta-ti/tree/meta-ti-bsp/recipes-bsp/powervr-drivers/ti-img-rogue-driver_24.1.6554834.bb?h=10.01.09 -As previously mentioned these build options must match with the corresponding UM +As before mentioned these build options must match with the corresponding UM build options. Currently we only release binaries with ``BUILD=release`` and -``WINDOW_SYSTEM=lws-generic``. The UM section will go previous exceptions -to this. +``WINDOW_SYSTEM=lws-generic``. The UM section will go into exceptions to this. -Proprietary Userspace Components -================================ +Proprietary user space components +================================= -The proprietary userspace components are required for all interactions with the -GPU. It contains the actual firmware binaries, GLES / Vulkan / OpenCL -implementation, and the primary control server. +All interactions with the GPU require the proprietary user space components. It +has the actual firmware binaries, GLES / Vulkan / OpenCL implementation, and the +primary control server. -The binary release for this component is available at: +The binary release for this part is available at: https://git.ti.com/cgit/graphics/ti-img-rogue-umlibs/ -Installing the Proprietary Userspace Components ------------------------------------------------ +Installing the proprietary user space components +------------------------------------------------ -The repository contains binaries for each platform in release specific branches. +The repository has binaries for each platform in release specific branches. Newer releases will match 1:1 with the kernel module branch name you would have picked in the :ref:`rogue-building-the-proprietary-kernel-module` stage. -In the repository the following structure can be seen: +The repository has the following structure: .. code-block:: text @@ -117,7 +117,7 @@ Under the :file:`targetfs` directory there is a subdirectory for each corresponding to the ``WINDOW_SYSTEM`` build variable. Finally, under that directory is a subdirectory corresponding to the ``BUILD`` build variable. -This is reflected in the :file:`Makefile` as: +This is in the :file:`Makefile` as: .. code-block:: Makefile @@ -125,49 +125,49 @@ This is reflected in the :file:`Makefile` as: The :file:`Makefile` simply unpacks this directory structure and installs the corresponding files into ``DESTDIR`` in the install step. Do not worry about the -clean step, as this is used for development. +clean step, as this is for development. .. _rogue-proprietary-mesa-components: -Proprietary Mesa Components +Proprietary mesa components =========================== -Mesa, at this point in time, is a collection of GFX tools and utilities for -setting up and interacting with rendering contexts. It contains everything from -a DRI "megadriver" to full GLES/GL implementations. If you're interested in -learning GFX under Linux it's worth familiarizing yourself with everything else -it provides. +Mesa, at this point in time, is a collection of Graphics (GFX) tools and +utilities for setting up and interacting with rendering contexts. It has +everything from a DRI "megadriver" to full GLES/GL implementations. If you're +interested in learning GFX under Linux it is worth familiarizing yourself with +everything else it provides. For us, the important part is that DRI megadriver. This is the mechanism used to -determine what GLES / GL implementation is picked when you bind one of the -previously mentioned API to a EGL context. This is also where things get tricky. +decide what GLES / GL implementation to pick when you bind one of the earlier +mentioned API to a context. This is also where things get tricky. Historically there has been some issues with embedded GFX because, unlike your standard PC GPU, we tend to mix and match actual Graphics Processing Units and Display Controllers. The megadriver uses the display device name to coordinate -between API implementations. As such, we need a shim to act as a ``tidss`` -DRI driver and coordinate the link with the PVR GLES implementation. +between API implementations. As such, we need a shim to act as a ``tidss`` DRI +driver and coordinate the link with the PVR GLES implementation. -This shim, currently, is provided in the form of a Gallium Frontend. This is the -main reason for the fork and the 60 odd patches we carry at the following repo: +This shim, currently, takes the form of a Gallium Frontend. This is the main +reason for the fork and the 60 odd patches we carry at the following repository: https://gitlab.freedesktop.org/StaticRocket/mesa There are also other nice-to-have features there such as additional pixel -formats, minor fixups, and a few performance tweaks IMG have picked up over the -years, but the main reason we need it is for that shim. +formats, minor fix-ups, and a few performance tweaks Imagination has picked up +over the years. The main reason we need it is for that shim. -Building the Proprietary Mesa Components +Building the proprietary mesa components ---------------------------------------- -We recommend following the `Mesa build guide`_ for general options. Right now -the mesa components use a standard interface that allows you to pick any -``powervr/*`` branch you desire. +We recommend following the `Mesa build guide`_ for general options. Currently +the mesa components use a standard interface that allows the use of any +``powervr/*`` branch. .. note:: - Releases prior to 1.18 did not use this standard interface. Instead all - relevant mesa components for those releases are bundled with the UM binaries. + Releases before 1.18 did not use this standard interface. Instead the UM + binaries include all relevant mesa components for those releases. The only necessary build options are: @@ -185,15 +185,15 @@ earlier: - :file:`pvr_dri.so` -- Main DRI interface - :file:`tidss_dri.so` -- Display controller interface that points back at - :file:`pvr_dri.so`. Will be named after the value specified with + :file:`pvr_dri.so`. This uses the value specified with ``-Dgallium-pvr-alias``. -Using the Proprietary Stack +Using the proprietary stack =========================== -Assuming you're using the SDK or you've built and installed the above correctly, -you should see a message similar to the following in :command:`dmesg` after the -kernel module is loaded: +Assuming you're using the SDK or you've built and installed the earlier parts +correctly, you should see a message similar to the following in :command:`dmesg` +after the kernel module has loaded: .. code-block:: dmesg @@ -206,8 +206,9 @@ kernel module is loaded: The BVNC should correspond with the BVNC set in :file:`build/linux/{PVR_BUILD_DIR}/Makefile` in the kernel module repository. If the module loads but does not detect the device, make sure your device tree has -defined the node properly, corresponding to the value of `SYS_RGX_OF_COMPATIBLE` -in the :file:`services/system/rogue/{platform}/sysinfo.h`. +defined the node properly. This corresponds to the value of +`SYS_RGX_OF_COMPATIBLE` in the +:file:`services/system/rogue/{platform}/sysinfo.h`. You should now be able to issue a simple test. The UM repository provides the :command:`rgx_compute_test` as a simple test that does not depend on the display @@ -220,41 +221,41 @@ upon launching that test: [ 460.694849] PVR_K: 332: Shader binary image 'rgx.sh.36.53.104.796' loaded ***************** -Open Source Stack +Open source stack ***************** -The open source driver is currently available for the AXE-1-16M core, but it -should be noted that performance is not up to par with the proprietary driver at -the moment. Performance improvements are on the table, but core enablement is -the main priority right now. +The open source driver is currently available for the AXE-1-16M core, but +performance is not up to par with the proprietary driver at the moment. +Performance improvements are on the table, but enabling the core is the main +priority at the moment. It currently offers experimental Vulkan 1.0 support. In the future it will -provide at least GL 2.1 via `Zink `_. +provides GL 2.1 through `Zink `_. Please note that Zink support for this driver is not mainline, and it is still experimental. If you want to follow development check out the `Imagination mesa fork `_ -Open Source Kernel Module +Open source kernel module ========================= -This is provided in the upstream `linux -`_ repo as -of version 6.8. It has been enabled in the arm64 defconfig as a module since +This is in the upstream `linux +`_ +repository as of version 6.8. It is in the arm64 ``defconfig`` as a module since this release as well. -Open Source Firmware +Open source firmware ==================== -Firmware is provided with `linux-firmware +Firmware is available in `linux-firmware `_ as of tag 20231211. .. note:: - This a binary, and the firmware itself is still closed source right now, but - this is not the same firmware as the proprietary driver. + This a binary, and the firmware itself is still closed source for the moment, + but this is not the same firmware as the proprietary driver. -Open Source Mesa Components +Open source mesa components =========================== The open source stack dramatically reduces the number of moving pieces by @@ -271,10 +272,10 @@ The only necessary build options are: - ``-Dgallium-drivers=zink`` -- Enable GL 2.1 through Zink -Using the Open Source Stack +Using the open source stack =========================== -After collecting the above artifacts you should be able to see the following +After collecting the earlier artifacts you should be able to see the following message in :command:`dmesg`: .. code-block:: dmesg @@ -283,9 +284,8 @@ message in :command:`dmesg`: [ 8.489916] powervr fd00000.gpu: [drm] FW version v1.0 (build 6503725 OS) [ 8.543073] [drm] Initialized powervr 1.0.0 for fd00000.gpu on minor 1 -Once again, if the module is loaded but you do not see the device being -registered make sure the device tree node matches the binding provided in the -upstream kernel. +Once again, if the module loaded but you do not see the device registering, make +sure the device tree node matches the binding provided in the upstream kernel. At this point you should be able to run a simple test. The tool :command:`vulkaninfo` from the package ``vulkan-tools`` is useful for printing diff --git a/source/linux/Foundational_Components/Graphics/Rogue/Overview.rst b/source/linux/Foundational_Components/Graphics/Rogue/Overview.rst index a100e7621..543125fec 100644 --- a/source/linux/Foundational_Components/Graphics/Rogue/Overview.rst +++ b/source/linux/Foundational_Components/Graphics/Rogue/Overview.rst @@ -48,12 +48,12 @@ Introduction For more information about OpenGL\ |reg| ES see :doc:`../Common/OpenGL_ES`. -These devices do not utilize static memory carveouts. The only reservations -made in device tree are for control registers. Memory is instead dynamically -allocated at runtime depending on the task and will scale accordingly. -Buffers are allocated from CMA and other runtime memory allocations are made -from standard pages. See the kernel module memory management subsystem for -more information. +These devices do not use static memory carve-outs. The only reservations made in +device tree are for control registers. Memory is instead dynamically allocated +at runtime depending on the task and will scale as needed. Scanout buffers come +from the Contiguous Memory Allocation (CMA) pool. Other runtime memory +allocations are from standard pages. See the kernel module memory management +subsystem for more information. .. note:: @@ -61,7 +61,8 @@ more information. ``_ -Other features of the Rogue series of GPUs include bilinear and trilinear filtering. +Other features of the Rogue series of GPUs include bilinear and trilinear +filtering. Support for the following pixel formats: @@ -108,10 +109,10 @@ Support for OS controlled Active Power Management, enabled by default. :doc:`/linux/How_to_Guides/Target/How_to_suspend_to_ram_on_AM62x` for more info. -Software Architecture +Software architecture ===================== -The picture below shows the software architecture of Graphics in +The following picture shows the software architecture of Graphics in |__SDK_FULL_NAME__|. .. figure:: /images/rogue-graphics-software-stack.png @@ -119,12 +120,12 @@ The picture below shows the software architecture of Graphics in PSDK Linux Rogue Graphics Software Stack -Please note that RGX-KM in this context refers to the pvrsrvkm kernel module, -which is currently provided at: +Please note that the Rogue Graphics Kernel Module (RGX-KM) in this context +refers to ``pvrsrvkm``, which is currently provided at: - ``_ -This is included by default in the SDK. The kernel module is located at: +The SDK includes this by default. The kernel module is at: .. code-block:: console @@ -133,14 +134,14 @@ This is included by default in the SDK. The kernel module is located at: Please see the :doc:`Build_Guide` for more information about integration of this software stack into other ecosystems. -Graphics Demos +Graphics demos ============== -Along with the graphics driver and userspace libraries, the SDK also includes -example applications. Some of the demos are based on the IMG -Native_SDK examples. +Along with the graphics driver and user space libraries, the SDK also includes +example applications. Some demos are from on the Imagination (IMG) Native_SDK +examples. -The following 3D Graphics demos are available. The table below provides a +The following 3D Graphics demos are available. The following table provides a list of these demos, with a brief description. .. list-table:: Demos @@ -149,17 +150,17 @@ list of these demos, with a brief description. * - Demo Name - Details - * - ChameleonMan + * - ``ChameleonMan`` - This demo shows a matrix skinned character in combination with bump mapping. - * - CoverFlow + * - ``CoverFlow`` - This is a demonstration of a coverflow style effect - * - ExampleUI + * - ``ExampleUI`` - This demo shows how to efficiently render sprites and interface elements. - * - Navigation + * - ``Navigation`` - This is a demonstration of how to implement rendering algorithms for Navigation software. - * - Kmscube + * - ``Kmscube`` - This demo shows how to render and display multi-colored spinning cube diff --git a/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info.rst b/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info.rst index e81932132..7d1d8698c 100644 --- a/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info.rst +++ b/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Debug_Info.rst @@ -1,7 +1,7 @@ .. The top level heading in this rst file would be level 2 header with `====` -Rogue Debug Info +Rogue debug info ================ Rogue graphics drivers include the following tools bundled with their user mode @@ -9,41 +9,41 @@ libraries: .. list-table:: Included rogue debug tools - * - pvrdebug + * - ``pvrdebug`` - Control debug verbosity and other device info - * - pvrlogdump + * - ``pvrlogdump`` - Dump diagnostic information for an application - * - pvrsrvctl + * - ``pvrsrvctl`` - Start, Stop, Restart and configure the GPU using a powervr.ini file - * - rgx_blit_test - - Attempt a number of blit opperations and display them to the screen - * - rgx_compute_test - - Attempt a number of compute tasks on the core - * - rgx_kicksync_test - - Attempt a number of processes on the core to stress the KickSync API - * - rgx_triangle_test + * - ``rgx_blit_test`` + - Try several blit operations and display them to the screen + * - ``rgx_compute_test`` + - Try several different compute tasks on the core + * - ``rgx_kicksync_test`` + - Try several processes on the core to stress the KickSync API + * - ``rgx_triangle_test`` - Render a triangle to the attached display - * - rgx_twiddling_test - - Attempt to twiddle a number of textures in a number of pixel formats + * - ``rgx_twiddling_test`` + - Twiddle several textures in several different pixel formats -While future releases of ti-img-rogue-umlibs may include more tools, this is -the core set expected to be available in most ti-img-rogue-umlibs releases and -are the most useful for verifying GPU functionality. +Future releases of ti-img-rogue-umlibs can include more tools. This is the core +set expected to be available in most ti-img-rogue-umlibs releases and are the +most useful for verifying GPU functionality. The order of operation to verify fundamental GPU functionality is as follows: - #. Use rgx_kicksync_test to verify the GPU can communicate with the kernel - module. + #. Use ``rgx_kicksync_test`` to verify the GPU can communicate with the + kernel module. - #. Use rgx_compute_test to verify that the GPU is able to handle a proper + #. Use ``rgx_compute_test`` to verify that the GPU is able to handle a proper compute load. - #. Use rgx_triangle_test to verify that the GPU is able to render to an + #. Use ``rgx_triangle_test`` to verify that the GPU is able to render to an output buffer. -If fundamental functionality has been verified and you are still experiencing -issues try checking the output of the following: +If you are still experiencing issues after verifying fundamental functionality, +try checking the output of the following: .. code-block:: console @@ -55,12 +55,12 @@ issues try checking the output of the following: this command if available. This will dump all device information as reported by the kernel module. Please -insure that the debug info reports: +ensure that the debug info reports: .. code-block:: text Comparison of UM/KM components: MATCHING -User mode and Kernel mode components must move in lockstep. If they do not -match this could lead to the kernel module failing to initialize or undefined +User mode and kernel mode components must move in lockstep. If they do not match +this could lead to the kernel module failing to initialize or undefined behavior. diff --git a/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info.rst b/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info.rst index 0feda73b7..d2b7fde6a 100644 --- a/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info.rst +++ b/source/linux/Foundational_Components/Graphics/Rogue/Rogue_Power_Management_Info.rst @@ -2,16 +2,16 @@ The top level heading in this rst file would be level 2 header with `====` ########################### -Rogue Power Management Info +Rogue power management info ########################### Rogue graphics drivers have supported active power management on AXE devices since TISDK release 8.6 and 8XE/BXS devices since release 9.0 with some discrepancy in the implementation between cores. -*** -APM -*** +*********************** +Active power management +*********************** .. ifconfig:: CONFIG_gpu_ip in ('Rogue_8XE', 'Rogue_BXS') @@ -27,44 +27,44 @@ APM In devices running a AXE core there is only one power domain for the GPU. -The "core" power domain is required for all interactions. This power domain is -controlled directly by Linux through APM hooks in the kernel module. This -domain is powered up for all transactions and subsequently powered down after -an idle period. +All interactions require the "core" power domain to be up. Linux controls this +domain through the Active Power Management (APM) hooks in the kernel module. +This domain remains online for all transactions and is offline after an idle +period. -Active Power Management is enabled by default, but it can be disabled at runtime -by setting the power control to "on" through the devices -:file:`/sys/devices/{path-to-device}/power/control` interface. Subsequently, it's -status can be checked by reading that device file. +Enabled by default, APM allows modification at runtime through the devices +:file:`/sys/devices/{path_to_device}/power/control` interface. Reading the +device file returns the current setting. -**************** -Suspend & Resume -**************** +****************** +Suspend and resume +****************** -Suspend and resume features are also enabled for Rogue cores. To test this -manually the following procedure can be used on products supporting full device -suspend / resume features: +Suspend and resume features are also enabled for Rogue cores. The following +procedure will test this on products supporting full device suspend and resume +features: -Initiate a load to wake up the GPU using ``glmark2``: +Start a task to wake up the GPU by using ``glmark2``: .. code-block:: console # glmark2-es2-wayland & -Trigger a suspend event with a scheduled wakeup: +Trigger a suspend event with a scheduled wake-up: .. code-block:: console # rtcwake -s 3 -m mem -Wait for the scheduled wakeup. +Wait for the scheduled wake-up. -The above sequence should result in the background compute task being paused -for the suspend action and then resumed after the scheduled wakeup 3 seconds +The earlier sequence should result in the background compute task pausing during +the suspend action and then resuming after the scheduled wake-up 3 seconds later. .. note:: - Driver specific unit tests (like ``rgx_compute_test``) will hold the device - in the powered on state starting with driver version 24.1. You cannot use - these tests as a load when attempting to test suspend/resume functionality. + Driver specific unit tests (such as ``rgx_compute_test``) will hold the + device in the powered on state starting with driver version 24.1. You cannot + use these tests as a load when attempting to test suspend and resume + functionality. diff --git a/source/linux/Foundational_Components/Graphics/SGX/AM3_Beagle_Bone_Black_Configuration.rst b/source/linux/Foundational_Components/Graphics/SGX/AM3_Beagle_Bone_Black_Configuration.rst index b515dc20e..313d46f0a 100644 --- a/source/linux/Foundational_Components/Graphics/SGX/AM3_Beagle_Bone_Black_Configuration.rst +++ b/source/linux/Foundational_Components/Graphics/SGX/AM3_Beagle_Bone_Black_Configuration.rst @@ -3,18 +3,18 @@ ######################################### -AM3 Beagle Bone Black Board Configuration +AM3 Beagle Bone Black board configuration ######################################### -AM335x has a HW bug, chapter 3.1.1 in the errata: "The blue and red -color assignments to the LCD data pins are reversed when operating in -RGB888 (24bpp) mode compared to RGB565 (16bpp) mode." Therefore, the -applications need to always use either 24 or 16 bpp modes, depending on -the display HW connected to the board. The default pixel format XRGB8888 -of the graphics application back ends and drivers within PSDK is not -supported at the AM3 Beagle Bone Black Board where it is in 16bpp mode. -To enable appropriate graphics display, make the following changes at -various graphics related configuration files: +AM335x has a HW bug, chapter 3.1.1 in the errata: ``The blue and red color +assignments to the LCD data pins are reversed when operating in RGB888 (24bpp) +mode compared to RGB565 (16bpp) mode.`` Therefore, the applications need to +always use either 24 or 16 Bit Per Pixel (BPP) modes, depending on the display +HW connected to the board. The default pixel format ``XRGB8888`` of the graphics +application backends and drivers within PSDK are not supported with the AM3 +Beagle Bone Black Board when it is in 16bpp mode. To enable an appropriate +graphics display, make the following changes at various graphics related +configuration files: - :file:`/etc/powervr.ini`: add ``DefaultPixelFormat=RGB565`` @@ -23,22 +23,22 @@ various graphics related configuration files: - :file:`/etc/profile.d/qt_env.sh`: add ``export QT_QPA_EGLFS_INTEGRATION=none`` -Another restriction of AM335x-based platform is that the width of -display resolution must be multiple of 32. For example, 1360x768 will -not work. The simple workaround is to specify the display resolution as -one of the kernel boot parameters for non-Weston application and at -:file:`/etc/weston.ini` for Weston server. +Another restriction of AM335x-based platform is that the width of display +resolution must be divisible by 32. For example, 1360x768 will not work. The +simple workaround is to specify the display resolution as one of the kernel boot +parameters for non-Weston applications and at :file:`/etc/weston.ini` for Weston +itself. For example: - #. The following commands need to be executed at boot prompt: + #. The following commands should run at u-boot: .. code-block:: text => setenv optargs video=HDMI-A-1:1024x768 => saveenv - #. Add the HDMI-A configuration to :file:`/etc/weston.ini` in a new + #. Add the ``HDMI-A`` configuration to :file:`/etc/weston.ini` in a new ``output`` section, as shown below: .. code-block:: ini diff --git a/source/linux/Foundational_Components/Graphics/SGX/Build_Guide.rst b/source/linux/Foundational_Components/Graphics/SGX/Build_Guide.rst index a268313a6..6607d4038 100644 --- a/source/linux/Foundational_Components/Graphics/SGX/Build_Guide.rst +++ b/source/linux/Foundational_Components/Graphics/SGX/Build_Guide.rst @@ -1,23 +1,23 @@ ############### -SGX Build Guide +SGX build guide ############### -The graphics stack on SGX has been frozen. The last major change occured in -release 09.01. This will capture the build process and some of the caviots of -this legacy driver. +The graphics stack on SGX will not receive any new major updates. The last major +change occurred in release 09.01. This will capture the build process and some +of the caveats of this legacy driver. -This driver has been reworked as part of the kernel 6.1 support effort to mimic -the build and structure of rogue. The stack consists of 3 main components with -varying classifications: +As part of the kernel 6.1 support effort, this driver now mimics the build and +structure of rogue. The stack consists of 3 main components with varying +classifications: - The kernel module (KM) (Open Source, but out-of-tree) - - The GLES 2.0 implementation (UM) (Closed Source, binary release) + - The GLES 2.0 user mode (UM) libraries (Closed Source, binary release) - The mesa shim (Open Source, but out-of-tree) -All 3 of these components are required for GLES support. +All 3 of these components are mandatory for GLES support. ***************** -SGX Kernel Module +SGX kernel module ***************** The kernel module is responsible for: @@ -25,64 +25,62 @@ The kernel module is responsible for: - Memory and power management - Monitoring device state - Orchestrating hardware recoveries - - Creating an interface for the userspace server + - Creating an interface for the user space server -The source for the component is available at: +The source for this is available at: https://git.ti.com/cgit/graphics/omap5-sgx-ddk-linux -Building the SGX Kernel Module +Building the SGX kernel module ============================== -The latest branch contains the most bugfixes and has been adapted for the widest -general compatibility in modern applications. This is -``1.17.4948957/mesa/k6.1``, and despite being tagged for kernel 6.1 it is also -interoperable with kernel 6.6. +The latest branch has the most bug-fixes and has the widest general +compatibility in modern applications. This is ``1.17.4948957/mesa/k6.1``, and +despite the mention of kernel 6.1 it is also interoperable with kernel 6.6. The :file:`INSTALL` file gives a brief overview of how to build and install the -module. This gives you the common variables, but it does leave out some of the -more important ones for the build. The following variables are key and *must* -match with the values used in the UM release: +module. This gives you the common variables, but it does omit some of the more +important ones for the build. The following variables are key and *must* match +with the values used in the UM release: - ``BUILD`` -- Options: ``release`` or ``debug`` - ``PVR_BUILD_DIR`` -- Options: ``_linux``, for example ``ti572x_linux`` - - ``WINDOW_SYSTEM`` -- Options: ``lws-generic``, ``xorg``, ``wayland``, ... + - ``WINDOW_SYSTEM`` -- Options: ``lws-generic``, ``xorg``, ``wayland``, among + others -These variables must be set for the build. To check for updated build variables -please see the ``EXTRA_OEMAKE`` variable in the `ti-sgx-ddk-km recipe in -meta-ti`_. This will always contain the latest required variables to compile the -driver. +These variables are mandatory. To check for updated build variables see the +``EXTRA_OEMAKE`` variable in the `ti-sgx-ddk-km recipe in meta-ti`_. This will +always contain the latest required variables to compile the driver. .. _ti-sgx-ddk-km recipe in meta-ti: https://git.ti.com/cgit/arago-project/meta-ti/tree/meta-ti-bsp/recipes-bsp/powervr-drivers/ti-sgx-ddk-km_1.17.4948957.bb -As previously mentioned these build options must match with the corresponding UM +As before mentioned these build options must match with the corresponding UM build options. Currently we only release binaries with ``BUILD=release`` and ``WINDOW_SYSTEM=lws-generic``. The UM section will go previous exceptions to this. -************************ -SGX Userspace Components -************************ +************************* +SGX user space components +************************* -The proprietary userspace components are required for all interactions with the -GPU. It contains the firmware, GLES implementation, and the primary control -server. Unlike rogue, the firmware is packaged as part of the control sever -library. +The proprietary user space components are necessary for all interactions with +the GPU. It has the firmware, GLES implementation, and the primary control +server. Unlike rogue, the firmware part of the control sever library. -The binary release for this component is available at: +The binary release is available at: https://git.ti.com/cgit/graphics/omap5-sgx-ddk-um-linux -Installing the SGX Userspace Components -======================================= +Installing the SGX user space components +======================================== -The repository contains binaries for each platform in release specific branches. -The newest release, which matches with the above mentioned kernel module branch -is ``1.17.4948957/mesa/glibc-2.35``. This branch deviates from the existing -naming pattern to indicate that unlike previous releases it required a new -version of mesa and was linked against glibc-2.35. +The repository has binaries for each platform in release specific branches. The +newest release, which matches with the earlier mentioned kernel module branch is +``1.17.4948957/mesa/glibc-2.35``. This branch deviates from the existing naming +pattern to indicate that unlike previous releases it required a new version of +mesa and was linked against glibc-2.35. -In the repository the following structure can be seen: +The repository has the following structure: .. code-block:: text @@ -113,7 +111,7 @@ Under the :file:`targetfs` directory there is a subdirectory for each corresponding to the ``WINDOW_SYSTEM`` build variable. Finally, under that directory is a subdirectory corresponding to the ``BUILD`` build variable. -This is reflected in the :file:`Makefile` as: +This is in the :file:`Makefile` as: .. code-block:: Makefile @@ -121,31 +119,31 @@ This is reflected in the :file:`Makefile` as: The :file:`Makefile` simply unpacks this directory structure and installs the corresponding files into ``DESTDIR`` in the install step. Do not worry about the -clean step, as this is used for development. +clean step, as this is for development. -Unlike rogue, there is an additional :file:`common` directory that contains +Unlike rogue, there is an additional :file:`common` directory that has startup script templates. These templates are automatically modified by the :file:`Makefile` as part of the install step. These are not strictly required, but you will need to manually start the device -with :command:`pvrsrvctl` if you choose not to use these templates. Please note +with :command:`pvrsrvctl` if you decide not to use these templates. Please note that this binary is, and always has been brittle. It likely will not realize what kernel you are running so you should specify ``--no-module`` when interacting with it. ******************* -SGX Mesa Components +SGX mesa components ******************* -Mesa, at this point in time, is a collection of GFX tools and utilities for -setting up and interacting with rendering contexts. It contains everything from -a DRI "megadriver" to full GLES/GL implementations. If you're interested in -learning GFX under Linux it's worth familiarizing yourself with everything else -it provides. +Mesa, at this point in time, is a collection of Graphics (GFX) tools and +utilities for setting up and interacting with rendering contexts. It has +everything from a DRI "megadriver" to full GLES/GL implementations. If you're +interested in learning GFX under Linux it is worth familiarizing yourself with +everything else it provides. For us, the important part is that DRI "megadriver." This is the mechanism used -to determine what GLES / GL implementation is picked when you bind one of the -previously mentioned API to a EGL context. This is also where things get tricky. +to decide what GLES / GL implementation gets selected when you bind one of the +before mentioned API to a context. This is also where things get tricky. Historically there has been some issues with embedded GFX because, unlike your standard PC GPU, we tend to mix and match actual Graphics Processing Units and @@ -153,20 +151,20 @@ Display Controllers. The megadriver uses the display device name to coordinate between API implementations. As such, we need a shim to act as a DRI driver and coordinate the link with the SGX GLES implementation. -This shim, currently, is provided in the form of a Gallium Frontend. This is the -main reason for the fork and the 60 odd patches we carry at the following repo: +This shim, currently, is in the form of a Gallium Frontend. This is the main +reason for the fork and the 60 odd patches we carry at the following repository: https://gitlab.freedesktop.org/StaticRocket/mesa There are also other nice-to-have features there such as additional pixel -formats, minor fixups, and a few performance tweaks IMG have picked up over the -years, but the main reason we need it is for that shim. +formats, minor fix-ups, and a few performance tweaks IMG have picked up over the +years. The main reason we need it is for that shim. -Building the SGX Mesa Components +Building the SGX mesa components ================================ -We recommend following the `Mesa build guide`_ for general options. Right now -the mesa components use a standard interface that allows you to pick any +We recommend following the `Mesa build guide`_ for general options. Currently +the mesa components use a standard interface that allows use of any ``powervr/*`` branch equal to or greater than ``22.3.5``. The only necessary build options are: @@ -184,31 +182,30 @@ earlier: - :file:`sgx_dri.so` -- Main DRI interface - :file:`pvr_dri.so` -- GPU interface that points back to :file:`sgx_dri.so`. - This is required in the case an application attempts to interact with the - GPU directly because the DRI device is still registered with the name - ``pvr``. + This is for an application that attempts to interact with the GPU directly + because the DRI device is still registered with the name ``pvr``. - :file:`_dri.so` -- Display controller interface that points back - at :file:`sgx_dri.so`. Will be named after the value specified with + at :file:`sgx_dri.so`. This is from the value specified with ``-Dgallium-sgx-alias``. ******************* -Using the SGX Stack +Using the SGX stack ******************* -Assuming you're using the SDK or you've built and installed the above correctly, -you should see a message similar to the following in :command:`dmesg` after the -kernel module is loaded: +Assuming you're using the SDK or you've built and installed the preceding +correctly, you should see a message similar to the following in :command:`dmesg` +after the kernel module loads: .. code-block:: dmesg [ 17.344567] [drm] Initialized pvr 1.17.4948957 20110701 for 56000000.gpu on minor 1 If the module loads but does not detect the device, make sure your device tree -has defined the node properly, corresponding to one of the values of +has defined the node properly. This corresponds to one of the values of ``powervr_id_table`` in the :file:`services4/srvkm/env/linux/module.c`. -Upon starting the userspace daemon you should see the following message: +Upon starting the user space daemon you should see the following message: .. code-block:: dmesg @@ -220,7 +217,7 @@ using the correct driver: .. code-block:: console - root@am335x-evm:~# glmark2-es2-drm + root@am335x-evm:~# glmark2-es2-drm MESA: info: Loaded libpvr_dri_support.so ======================================================= glmark2 2021.12 diff --git a/source/linux/Foundational_Components/Graphics/SGX/OMAP_DRM.rst b/source/linux/Foundational_Components/Graphics/SGX/OMAP_DRM.rst index 212dc7f03..92c5670bf 100644 --- a/source/linux/Foundational_Components/Graphics/SGX/OMAP_DRM.rst +++ b/source/linux/Foundational_Components/Graphics/SGX/OMAP_DRM.rst @@ -1,29 +1,25 @@ -################ -DSS Applications -################ +############################### +Display sub-system applications +############################### -DSS applications are omapdrm based. These will demonstrate the clone -mode, extended mode, overlay window, z-order and alpha blending -features. To demonstrate clone and extended mode, HDMI display must be -connected to board. +Display sub-system (DSS) applications are ``omapdrm`` based. These will show the +clone mode, extended mode, overlay window, z-order and alpha blending features. +To show the clone and extended mode, an HDMI display must be present. -************************ -Running DSS Applications -************************ - -These applications require the supported mode information -of connected displays and plane ids. One can get these information by -running the *modetest* application in the filesystem. +These applications require the supported mode information of connected displays +and plane ids. One can get these information by running the :command:`modetest` +application in the filesystem. .. code-block:: console # modetest -Running drmclone -================ +******** +drmclone +******** This displays the same test pattern on both LCD and HDMI (clone). Overlay -windows are also displayed on LCD. To test clone mode, execute the following +windows are also displayed on LCD. To test clone mode, run the following command: .. code-block:: console @@ -36,14 +32,15 @@ For example: # drmclone -l 1280x800 -p 320x240:0+0 -h 640x480 -We can change position of overlay window by changing x+y values. eg. -240+120 will show @ center +We can change position of overlay window by changing x+y values. For example, +240+120 will display this at the center. -Running drmextended -=================== +*********** +drmextended +*********** This displays different test pattern on LCD and HDMI. Overlay windows are also -displayed on LCD. To test extended mode, execute the following command: +displayed on LCD. To test extended mode, run the following command: .. code-block:: console @@ -55,15 +52,16 @@ For example: # drmextended -l 1280x800 -p 320x240:0+0 -h 640x480 -Running drmzalpha -================= +********* +drmzalpha +********* This displays alpha blended patters on the given display. To use it the -following paramters must be specified: +following parameters are mandatory: **Z-order**: -It determines, which overlay window appears on top of the other. +It determines, which overlay window is displayed on top of the other. Range: 0 to 3 - lowest value for bottom @@ -71,19 +69,19 @@ Range: 0 to 3 **Alpha Blend**: -It determines transparency level of image as a result of both global -alpha & pre multiplied alpha value. +It determines transparency level of image as a result of both global alpha and +pre-multiplied alpha value. Global alpha range: 0 to 255 - 0 - fully transparent - 127 - semi transparent - 255 - fully opaque -Pre multipled alpha value: 0 or 1 - - 0 - source is not premultiply with alpha - - 1 - source is premultiply with alpha +Pre-multipled alpha value: 0 or 1 + - 0 - source is not pre-multiply with alpha + - 1 - source is pre-multiply with alpha -To test ``drmzalpha``, execute the following command: +To test ``drmzalpha``, run the following command: .. code-block:: console diff --git a/source/linux/Foundational_Components/Graphics/SGX/Overview.rst b/source/linux/Foundational_Components/Graphics/SGX/Overview.rst index 93b9b439c..ff549892d 100644 --- a/source/linux/Foundational_Components/Graphics/SGX/Overview.rst +++ b/source/linux/Foundational_Components/Graphics/SGX/Overview.rst @@ -3,20 +3,20 @@ Introduction ============ -TI SOCs like AM335x, AM437x, AM57xx and AM65xx are enabled with 3D cores, -capable of accelerating 3D operations with dedicated hardware. The -dedicated hardware is based on SGX series of devices from Imagination -Technologies. The graphics cores only accelerate graphics operations, -and do not perform video decode operations. For video acceleration, -refer to respective Technical Reference Manuals for the SOCs. +TI SOCs such as AM335x, AM437x, AM57xx and AM65xx have 3D cores capable of +accelerating 3D operations with dedicated hardware. The dedicated hardware is +using the SGX series of devices from Imagination Technologies (IMG). The +graphics cores only accelerate graphics operations, and do not perform video +decode operations. For video acceleration, see the Technical Reference Manuals +for the associated SoC. -Below table lists the various TI families supported by this SDK, and the -SGX core information +The following table lists the various TI families supported by this SDK, and the +SGX core information: .. list-table:: TI System on Chips, and SGX cores :header-rows: 1 - * - TI SOC Name + * - TI SoC Name - SGX Core - SGX Core Revision - Max SGX Core Frequency (MHz) @@ -40,17 +40,17 @@ SGX core information The SGX cores in AM family support OpenGL\ |reg| ES 1.1 and OpenGL\ |reg| ES 2.0 APIs. -These devices do not utilize static memory carveouts. The only reservations -made in device tree are for control registers. Memory is instead dynamically -allocated at runtime depending on the task and will scale accordingly. -Buffers are allocated from CMA and other runtime memory allocations are made -from standard pages. See the kernel module memory management subsystem for -more information. +These devices do not use static memory carve-outs. The only reservations made in +device tree are for control registers. Memory is instead dynamically allocated +at runtime depending on the task and will scale as needed. Scanout buffers come +from the Contiguous Memory Allocation (CMA) pool and other runtime memory +allocations come from standard pages. See the kernel module memory management +subsystem for more information. -Software Architecture +Software architecture ===================== -The picture below shows the software architecture of Graphics in +The following picture shows the software architecture of Graphics in |__SDK_FULL_NAME__|. .. figure:: /images/Graphic_software_stacks_DRM.png @@ -61,12 +61,11 @@ The picture below shows the software architecture of Graphics in Please see the :doc:`Build_Guide` for more information about integration of this software stack into other ecosystems. -Graphics Demos +Graphics demos ============== -Along with the graphics driver and userspace libraries, the SDK also includes -example applications. Some of the demos are based on the IMG -Native_SDK examples. +Along with the graphics driver and user space libraries, the SDK also includes +example applications. Some of the demos are from the IMG Native_SDK examples. The following demos are available to run under the Wayland windowing system. @@ -82,18 +81,16 @@ The following demos are available to run under the Wayland windowing system. # /usr/bin/SGX/demos/Wayland/OpenGLESNavigation3D # /usr/bin/SGX/demos/Wayland/OpenGLESParticleSystem -Running demos in Null Window system mode +Running demos in null window system mode ---------------------------------------- -The graphics demos can also be run in null-window system mode outside of Wayland -windowing system as full screen applications. In order to do so, exit Weston by -pressing Ctrl-Alt-Backspace from the keyboard which connects to the EVM. Then, -if the LCD screen stays in "Please wait...", press Ctrl-Alt-F1 to go to the -command line on LCD console. After that, the command line can be used from -serial console, SSH console, or LCD console. +The graphics demos can also run in null-window system mode outside of Wayland +windowing system as full screen applications. To do so, :ref:`stop Weston +`. After that, access the command line from serial console, SSH +console, or LCD console. -Please make sure the board is connected to at least one display before -running these demos. +Please make sure the board has at least one display connected before running +these demos. .. code-block:: console @@ -102,10 +99,10 @@ running these demos. # /usr/bin/SGX/demos/DRM/OGLES2ExampleUI # /usr/bin/SGX/demos/DRM/OGLES2Navigation -After you see the output on the display interface, hit *q* to terminate -the application. +After you see the output on the display interface, press *q* to exit the +application. Some of the demos under null windowing system require the user to pass in -the drm connector id. For information on how to get connector id please -refer to the :doc:`../Common/Display` section. +the DRM connector id. For information about how to get connector id, +see the :ref:`finding_the_connector_id` section. diff --git a/source/linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info.rst b/source/linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info.rst index 0fc330e24..814907f10 100644 --- a/source/linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info.rst +++ b/source/linux/Foundational_Components/Graphics/SGX/SGX_Debug_Info.rst @@ -1,7 +1,7 @@ .. http://processors.wiki.ti.com/index.php/SGXDbgInfo ############## -SGX Debug Info +SGX debug info ############## ************ @@ -9,15 +9,14 @@ Introduction ************ The TI OMAP/AM/DM SGX Graphics Driver is closely tied to the environment it is -running under and the configuration it is built with. This article mentions -debugging methods specific to Linux. +running under and the build configuration. This article mentions debugging +methods specific to Linux. -********************************************* -Baselining the current SGX driver environment -********************************************* +********************************************** +Baselin-ing the current SGX driver environment +********************************************** -The current SGX driver environment on the target can be observed using -the below script: +The the following script shows the current SGX driver environment on the target: .. code-block:: sh :caption: gfx_check.sh @@ -48,39 +47,36 @@ the below script: echo "Linux Kernel version" uname -a -*********************************************** -Run-time checks/configuration of the SGX driver -*********************************************** +************************************************** +Runtime checks and configuration of the SGX driver +************************************************** One can confirm whether the SGX drivers have been properly installed by checking the following: - One should have seen the message on serial console: ``Initializing the - graphics driver ...`` just before getting the Linux command prompt. + graphics driver ...`` just before getting the Linux shell prompt - The ``lsmod`` command shows ``pvrsrvkm`` module inserted successfully without any error messages on console. -The SGX driver can be configured at run-time on the target using a configuration -file. +The SGX driver supports some runtime configuration on the target by using a +configuration file. The optional configuration file is present in the Processor +SDK at :file:`/etc/powervr.ini`. -The optional configuration file is installed by the Processor SDK installer at -:file:`/etc/powervr.ini`. - -Configuration items are specified using the below syntax +Configuration items use the following syntax: .. code-block:: text KeyWord=ParamValue -Important configuration parameters are mentioned below. - +The following sections go over some important configuration parameters. WindowSystem ============ This configuration item controls the low level window system that the EGL -implementation should hook it up. This item takes the below values: +implementation should hook it up. This item takes the following values: - ``libpvrDRMWSEGL.so`` (DRM-based WS for VSync synchronised writes to Framebuffer - slower, but avoids tearing) @@ -91,7 +87,8 @@ implementation should hook it up. This item takes the below values: DisableHWTextureUpload ====================== -This configuration item enables/disables the use of SGX Transfer queue hardware. +This configuration item enables or disables the use of SGX Transfer queue +hardware. If set to 1, the driver uses software upload (copying from driver to SGX) of textures, rather than transfer queue (using the SGX hardware). @@ -110,53 +107,53 @@ If one wants to configure the default pixel format, then edit DefaultPixelFormat=ARGB8888 -For AM3 Beagle Bone Black EVM: +For AM3 Beagle Bone Black evaluation module (EVM): .. code-block:: text DefaultPixelFormat=RGB565 *************************************** -SGX Driver Failure Modes (Installation) +SGX driver failure modes (installation) *************************************** Unable to install the kernel modules (pvrsrvkm.ko) ================================================== -1. The Linux kernel has to be built with "modules" support. +1. The Linux kernel must have "modules" support. -2. The kernel module for the Graphics driver have to be built against a version - of the kernel that will be run on the target. +2. The kernel module for the Graphics driver must use a kernel source that + matches what is running on the target. 3. If the services kernel module (``pvrsrvkm.ko``) does not load, it is likely because of mismatches between user mode binaries and kernel module. If the - kernel module is built correctly, post the issue on the E2E forum with the + kernel module built correctly, post the issue on the E2E forum with the output of the :ref:`gfx-check-sh` script. -*********************************** -SGX Driver Failure Modes (Run time) -*********************************** +********************************** +SGX driver failure modes (runtime) +********************************** -Vertical Tearing / Artifacts / Clipping issues / Missing objects +Vertical tearing, artifacts, clipping issues, or missing objects ================================================================ -This could be due to an incorrect usage of OpenGL or an issue in the driver. -Note that the deferred rendering mode of the SGX hardware will cause different -behaviour compared to the immediate renderers found on desktops. +This could be due to a wrong usage of OpenGL or an issue in the driver. Note +that the deferred rendering mode of the SGX hardware will cause different +behaviour compared to the immediate rendering used on desktops. Please contact TI through the Linux `E2E forums`_. -Demos are not running at required speed, How to check SGX clock rate? -===================================================================== +Demos are not running at required speed or How to check SGX clock rate +====================================================================== If the demos are running slower than expected, check and ensure that the clock -frequency set for the SGX driver is correct. This can be done using the -following code in the KM kernel driver: +frequency set for the SGX driver is correct. Use the following code in the KM +kernel driver: | File - :file:`eurasia_km/services4/system/omap/sysutils_linux.c` | Function - ``EnableSGXClocks()`` -You can print the SGX clock rate in a debug build as below: +You can print the SGX clock rate in a debug build by using the following: .. code-block:: c @@ -167,23 +164,23 @@ Depending on the TI platform used, this will vary from 200 to 532 MHz. Ensure that SGX is running at the right clock. If the clock values are correct and demos are still not running with expected -performance, then application specific optimization will be required. +performance, then application specific optimization is necessary. -Qt demos do not work when PowerVR is enabled -============================================ +Qt demos do not work with PowerVR +================================= 1. Confirm that the GLES2 demos provided in the Graphics SDK are running properly with default SDK configuration of the window system. 2. Confirm that kernel module ``pvrsrvkm.ko`` is successfully loaded. -3. Confirm that the alpha value is non-zero using the ``fbset`` command. If not, - set it to the appropriate value using ``fbset``. QT supports 16 and 32 bpp, - but it expects a non-zero alpha value when using 32 bpp. +3. Confirm that the alpha value is nonzero using the ``fbset`` command. If not, + set it to the appropriate value using ``fbset``. QT supports 16 and 32 bits + per pixel (BPP), but it expects a nonzero alpha value when using 32 BPP. -If above has been confirmed and there are still issues, post to E2E forum with -the output of the :ref:`gfx-check-sh` script. Also attach the console log, with -the below environment variable set: +If there are still issues, post to E2E forum with the output of the +:ref:`gfx-check-sh` script. Also attach the console log, with the following +environment variable set: .. code-block:: console @@ -194,8 +191,7 @@ Posting to E2E forum ******************** For suggestions or recommendations or bug reports, post details of your -application as below to the `E2E forums`_, with below -information: +application to the `E2E forums`_ with following information: - Output of GFX environment baseline script :ref:`gfx-check-sh`.