3.9. Graphics and Display¶

3.9.1. 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.

Below table lists the various TI families supported by this SDK, and the SGX core information

Table: TI System on Chips, and SGX cores

Since the 3D accelerator (SGX core) is outside the ARM core, the Graphics drivers run on ARM core, and contain OS specific driver code to memory map the SGX core and program the engine from the OS running on the ARM core. The current version of SGX DDK provides OpenGLES2.0 and EGL libraries which are used by the graphics stacks in Processor SDK, such as QT5 and Wayland/Weston, Mesa-EGL based apps are currently not supported.

This Processor SDK Graphics and Display page will cover the following topics:

• Software architecture of Graphics
• Instructions on how to run graphics demos
• Instructions on how to run PVR tools
• Instructions on how to run DSS application
• Migration Guide
• AM3 Beagle Bone Black Board Configuration
• SGX Debugging Tips

3.9.2. Software Architecture¶

The picture below shows the software architecture of Graphics in Processor SDK.

3.9.3. Graphics Demos Available via Matrix¶

The following 3D Graphics demos are available via Matrix. The table below provides a list of these demos, with a brief description.

Note that some of the 3D Graphics demos are from Imagination’s PowerVR SDK.

3.9.4. Graphics Demos from Command Line¶

The graphics driver and userspace libraries and binaries are distributed along with the SDK.

Graphic demos can also run from command line. 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.

Please make sure the board is connected to at least one display before running these demos.

target # /usr/bin/SGX/demos/Raw/OGLES2Coverflow
target # /usr/bin/SGX/demos/Raw/OGLES2ChameleonMan
target # /usr/bin/SGX/demos/Raw/OGLES2ExampleUI
target # /usr/bin/SGX/demos/Raw/OGLES2Navigation

target #  modetest

Connectors:
id      encoder status          type    size (mm)       modes   encoders
4       3       connected       HDMI-A  480x270         20      3
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  1920x1080 60 1920 2008 2052 2200 1080 1084 1089 1125 flags: phsync, pvsync; type: preferred, driver
...
16      15      connected       unknown 0x0             1       15
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  800x480 60 800 1010 1040 1056 480 502 515 525 flags: nhsync, nvsync; type: preferred, driver

target #  modetest

Planes:
id      crtc    fb      CRTC x,y        x,y     gamma size
19      0       0       0,0             0,0     0
 formats: RG16 RX12 XR12 RA12 AR12 XR15 AR15 RG24 RX24 XR24 RA24 AR24 NV12 YUYV UYVY
 props:
 ...
20      0       0       0,0             0,0     0
 formats: RG16 RX12 XR12 RA12 AR12 XR15 AR15 RG24 RX24 XR24 RA24 AR24 NV12 YUYV UYVY
 props:
 ...

target # kmscube

target # kmscube -c <connector-id>
target # kmscube -c 16 #For example, the connector id for secondary display is 16.

target # kmscube -a

target # unset WAYLAND_DISPLAY

target # weston --tty=1 --connector=<default connector-id>

target # weston --tty=1 --connector=<secondary connector-id>

target # weston --tty=1

--idle-time=<number of seconds>

weston --tty=1 --idle-time=600

weston --tty=1 --idle-time=0

# /usr/bin/weston-flower
# /usr/bin/weston-clickdot
# /usr/bin/weston-cliptest
# /usr/bin/weston-dnd
# /usr/bin/weston-editor
# /usr/bin/weston-eventdemo
# /usr/bin/weston-image /usr/share/weston/terminal.png
# /usr/bin/weston-resizor
# /usr/bin/weston-simple-egl
# /usr/bin/weston-simple-shm
# /usr/bin/weston-simple-touch
# /usr/bin/weston-smoke
# /usr/bin/weston-info
# /usr/bin/weston-terminal

target # gst-launch-1.0 playbin uri=file://<path-to-file-name> video-sink=waylandsink

3.9.5. Using the 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 https://community.imgtec.com/developers/powervr/graphics-sdk/ for additional details on the tools and detailed documentation.

The target file system includes a subset of PowerVR tools such as PVRScope and PVRTrace recorder libraries from Imagination PowerVR SDK to profile and trace SGX activities. In addition, it also includes PVRPerfServerDeveloper tool.

target # /opt/img-powervr-sdk/PVRHub/PVRPerfServer/PVRPerfServerDeveloper

target # cp /opt/img-powervr-sdk/PVRHub/Scripts/start_tracing.sh ~/.
target # ./start_tracing.sh <log-filename> <application-to-be-traced>

target # ./start_tracing.sh westonapp weston-simple-egl

3.9.6. Running DSS application¶

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. Application requires the supported mode information of connected displays and plane ids. One can get these information by running the modetest application in the filesystem.

target #  modetest

Running drmclone application

This displays same test pattern on both LCD and HDMI (clone). Overlay window also displayed on LCD. To test clone mode, execute the following command:

target #  drmclone -l <lcd_w>x<lcd_h> -p <plane_w>x<plane_h>:<x>+<y> -h <hdmi_w>x<hdmi_h>

e.g.: target # 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

Running drmextended application

This displays different test pattern on LCD and HDMI. Overlay window also displayed on LCD. To test extended mode, execute the following command:

target # drmextended -l <lcd_w>x<lcd_h> -p <plane_w>x<plane_h>:<x>+<y> -h <hdmi_w>x<hdmi_h>

e.g.: target # drmextended -l 1280x800 -p 320x240:0+0 -h 640x480

Running drmzalpha application

Z-order:

It determines, which overlay window appears on top of the other.

Alpha Blend:

It determines transparency level of image as a result of both global alpha & pre multiplied alpha value.

Pre multipled alpha value: 0 or 1

0 - source is not premultiply with alpha

1 - source is premultiply with alpha

To test drmzalpha, execute the following command:

target # drmzalpha -s <crtc_w>x<crtc_h> -w <plane1_id>:<z_val>:<glo_alpha>:<pre_mul_alpha> -w <plane2_id>:<z_val>:<glo_alpha>:<pre_mul_alpha>

e.g.: target # drmzalpha -s 1280x800 -w 19:1:255:1 -w 20:2:255:1

3.9.7. QT Graphics Framework¶

Qt is a powerful C++ toolkit for writing cross-platform graphics applications, enabling a single code base to run predictably and perform well on Windows and embedded platforms,

Please refer https://www.qt.io/ for additional details on Qt.

The PSDK target file system includes the pre-built Qt libraries under /usr/lib and a rich set of QT demo applications under /usr/share/qt5/examples. A small subset of QT demo applications such as Calculator and Animatedtiles can also be invoked through Matrix.

QT QPA

The QT5 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”.

3.9.8. 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 projects ranging from small one-off tools to complete application suites.

Please refer https://www.gtk.org/ for additional details on GTK+.

The PSDK target file system includes the pre-built GTK+ libraries under /usr/lib for GTK+3 over Wayland support. There is also a comprenhensive GTK+3 demo application gtk3-demo under /usr/bin to demonstrate GTK+3 APIs and their usages.

3.9.9. Migration from prior releases¶

3.9.10. 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:

• /etc/powervr.ini: add DefaultPixelFormat=RGB565
• /etc/weston.ini: add gbm-format=rgb565 at section [core]
• /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 /etc/weston.ini for Weston server. For example,

• the following commands need to be executed at boot prompt

=> setenv optargs video=HDMI-A-1:1024x768
=> saveenv

• add the HDMI-A configuration to /etc/weston.ini in a new “output” section, as shown below:

[output]
name=HDMI-A-1
mode=1024x768

3.9.11. SGX Debug Info¶

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.

Baselining the current SGX driver environment

The current SGX driver environment on the target can be observed using the below script.

https://gforge.ti.com/gf/download/docmanfileversion/203/3715/gfx_check.sh

This script performs the below actions:

#!/bin/sh
echo "WSEGL settings"
cat /etc/powervr.ini
echo "------"
echo "ARM CPU information"
cat /proc/cpuinfo
echo "------"
echo "SGX driver information"
cat /proc/pvr/version
echo "------"
echo "Framebuffer settings"
fbset -i
echo "------"
echo "Rotation settings"
cat /sys/class/graphics/fb0/rotate
echo "------"
echo "Kernel Module information"
lsmod
echo "------"
echo "Boot settings"
cat /proc/cmdline
echo "------"
echo "Linux Kernel version"
uname -a

Run-time checks/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.
• lsmod 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 optional configuration file is installed by the Processor SDK installer at,

/etc/powervr.ini

Configuration items are specified using the below syntax

KeyWord=ParamValue

Important configuration parameters are mentioned below.

WindowSystem

* WindowSystem - This configuration item controls the low level window system that the EGL implementation should hook it up. This item takes the below values

* libpvrDRMWSEGL.so (DRM-based WS for VSync synchronised writes to Framebuffer - slower, but avoids tearing)

* libpvrGBMWSEGL.so (GBM-based WS where it is up to application to perform KMS operations)

DisableHWTextureUpload

* DisableHWTextureUpload - This configuration item enables/disables the use of SGX Transfer queue hardware.
* If set to 1, uses software upload (copying from driver to SGX) of textures, rather than transfer queue (using the SGX hardware).
* Useful to rule out problems in TQ.

DefaultPixelFormat

* DefaultPixelFormat - This configuration item sets the default display pixel format.

For eg if one wants to configure the default pixel format, then edit /etc/powervr.ini to have following line

DefaultPixelFormat=ARGB8888

For AM3 Beagle Bone Black EVM

DefaultPixelFormat=RGB565

SGX Driver Failure Modes (Installation)

Unable to install the kernel modules (pvrsrvkm.ko)

1. The Linux kernel has to be built with “modules” support (make ti-sgx-ddk-km and make ti-sgx-ddk-km_install)

2. The kernel modules of the Graphics driver have to be built, after the linux kernel is built in the above manner. ie, the kernel modules need to match the kernel version that will actually run 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 modules. If the kernel modules are built correctly as specified, post the issue on the E2E forum with the output of the gfx_check.sh script linked in earlier section.

SGX Driver Failure Modes (Run time)

Vertical Tearing/ Artifacts/ Clipping issues/ Missing objects

This could potentially be due to an incorrect usage in the OpenGL application, or point to an issue in the driver. Note that the deferred rendering mode of the SGX HW, will cause different behaviour compared to the immediate renderers found on desktops.

Please contact TI through the Linux E2E forums (https://e2e.ti.com/)

Demos are not running at required speed, 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 by the following code in the KM kernel drivers -

File - eurasia_km/services4/system/omap/sysutils_linux.c Function - EnableSGXClocks()

You can print the SGX clock rate in debug build as below -

IMG_UINT32 rate = clk_get_rate(psSysSpecData->psSGX_FCK);
PVR_TRACE(("Sgx clock is %dMHz", HZ_TO_MHZ(rate)));

Depending on the TI platform used, this will vary from 200 to 532 MHz. Ensure that SGX is running at the right clock.

If this is right & still demos are not running with expected performance, it is needed to optimize the application, and its usage of OpenGL API.

Qt demos do not work when powerVR is enabled

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 with fbset command to check alpha to be non zero. If not set to appropriate value using fbset. QT supports 16, 32 bpp but expects alpha to be non zero for 32 bpp.

4. If above steps are correct, post to E2E forum with the output of the gfx_check.sh script linked in earlier section. Also attach the console log, with the below option enabled in the environment

"QT_DEBUG_PLUGINS=1"

Posting to E2E forum

For suggestions or recommendations or bug reports, post details of your application as below to the E2E forums (https://e2e.ti.com/), with below information:

• Output of gfx environment baseline script available below, run on the target:

https://gforge.ti.com/gf/download/docmanfileversion/203/3715/gfx_check.sh

• Details of UI application, as shown in below sheet.

https://gforge.ti.com/gf/download/docmanfileversion/220/3798/UI_graphics_reqs_sheet_v1.xls

These two outputs will help in debugging common issues.