IntroductionThe STMicroelectronics STM32MP157 line microprocessors embed a Vivante GPU (graphics processor unit) that uses theKhronos® Group OpenGL® ES (embedded system) and OpenVG™ standards.

This document describes the STM32MP157 GPU tool kit (STM32MP157GPUTK), a set of applications allowing developers torapidly develop and port graphic applications.

Thanks to STM32MP157GPUTK, any graphics-based application can be accelerated, improving the eye-catching visuals andminimizing the system resources loading (CPU, memory, bandwidth, power).

Good understanding of OpenGL®/OpenGL® ES programming fundamentals, is recommended before reading this user manual.

See the related STM32MP157 documentation [1], [2] for more technical details.

This document contains proprietary copyright material disclosed with permission of Vivante Corporation.

Reference documents

[1] STM32MP157 advanced Arm®-based 32-bit MPUs reference manual (RM0436)

[2] STM32MP157 GPU application programming manual (PM0263)

STM32MP157 GPU tool kit

UM2547

User manual

UM2547 - Rev 1 - March 2019For further information contact your local STMicroelectronics sales office.

www.st.com

1 STM32MP157GPUTK overview

This tool kit applies to the STM32MP157 Arm®-based microprocessors (MPUs).

Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

1.1 STM32MP157GPUTK components overviewSTM32MP157GPUTK includes the following components (also named vTools):• vProfiler: driver and hardware performance profiling utility• vAnalyzer: visual analyzer for graphing the performance metrics

The following pre-processing utilities are also provided:• vShader for standalone development of optimized shader programs• vCompiler for compiling shader code into binary executables• vTexture for image transfer providing compression and decompression options

Figure 1. STM32MP157GPUTK vTools components

STM32MP157GPUTKon-target utility

STM32MP157 MPU

STM32MP157GPUTKWindows or Linux on-host utilitiesGraphics

applicationsvShader

Prototype and optimize shader

programs

vTextureCompress and

decompress images

vCompilerShader programs compile and link

vAnalyzerVisual analysis of

performance metrics

Application framework

OpenGL ESOpenVG

vProfilerCollect real-time

performance metrics

1.2 STM32MP157GPUTK operating system requirementsMost vTools applications are designed to run on Windows® 32- and 64-bit operating systems (OS).Some components, such as vProfiler and vCompiler, are run on other platforms. Refer to the individual vToolsdetailed description in the next sections.

UM2547STM32MP157GPUTK overview

UM2547 - Rev 1 page 2/39

1.3 STM32MP157GPUTK installationSTM32MP157GPUTK contains a vtools folder, including four .zip packages that can be individually extracted. Asan example, if the system has 7-Zip installed, right click and select Extract Here. A folder is then created with thesame name as the .zip file, as listed below:• vAnalyzer.zip• vCompiler.zip• vShader.zip• vTexture.zip

Note: vProfiler is not included in the .zip package because it is integrated in the GPU graphics drivers build processand runs on the hardware target.Each vTools extracted folder contains a setup.exe and a vToolName.msi files. The tool can be installedindependently by running the setup.exe located in that folder. Typical licensing and folder placement options mayappear as part of the installation prompts.vAnalyzer and vShader have a Windows GUI (graphical user interface). vCompiler and vTexture are utilities runfrom the command line.The STM32MP157GPUTK default installation location is usually a folder named for exampleC:\Program Files\Vivante\vToolName, where vToolName is the name of the tool being installed. Some systemsmay install to a Program Files (x86) folder.

Note: Windows navigation instructions such as Control Panel navigation vary with the different Windows OS.Administrator rights may be required to install the tool. To install an updated version, use Windows Add/Removeprograms to remove the installed version of the tool before installing the new one.

UM2547STM32MP157GPUTK installation

UM2547 - Rev 1 page 3/39

2 vShader

vShader is a complete off‐line environment for editing, previewing, analyzing, and optimizing shader programs.Thanks to vShader, users can perform all the following tasks:• Map any texture onto shaders• Import user‐defined meshes• Bind mesh attributes to shaders• Set uniforms in shaders• View shader compiler output for optimization hints• Predict hardware performance

2.1 vShader componentsBy default, the vShader executable installs in the following location within STM32MP157GPUTK directories:C:\Program Files\Vivante\vShadervShader includes samples of shader programs, a number of standard meshes (such as sphere, cube, tea pot andpyramid) and a text editor.By combining vertex shaders and fragment shaders into a single shader program, an application can produce ashader effect. A project can use many shader effects, that can share vertex and fragment shaders, mixing andmatching to achieve the desired results.Next sections cover the vShader user interface. Tutorials provided with the vShader package are there to help thereader learn about shaders.

2.2 Getting started with vShaderOnce vShader is launched (clicking on a shortcut or directly on the vShader.exe executable), projects can becreated, developed and saved. Project files have a .vsp extension.

2.2.1 Creating a new projectTo create a new project, locate the main menu bar Select File then New Project…Depending on the current project status, one of three things happens:• If vShader is launched for the first time, there is no project already open and selecting File > New Project…

has no effect.• If there have been no changes to the current project since the last save, the current project closes and a

new empty project is opened.• If the current project has been modified, a dialog box pops up to ask if changes must be saved. Choosing

Yes commits the changes to the current project and close it. A new empty project is opened.

2.2.2 Opening an existing projectThe following steps are needed to open an existing project:1. Locate the main menu bar.2. Select File then Open Project…3. Double-click on the desired project from the list that pops up or single-click on the project name and click

OK.The project is loaded into vShader and appears in the last saved state.

UM2547vShader

UM2547 - Rev 1 page 4/39

2.2.3 Saving a projectThe following steps are needed to save a project:1. Locate the main menu bar.2. Select File then Save Project…3. Indicate where to save the project in the resulting dialog box, then click OK.

2.3 vShader navigationvShader runs on Windows platforms and is driven from a GUI shown in the figure below.

Figure 2. vShader GUI main window

The main GUI components are listed below:• menu bar and icons (on the upper part of the window)• Preview and Project Explorer panes (on the left)• Shader Editor pane (on the right)• InfoLog pane (on the lower part)

UM2547vShader navigation

UM2547 - Rev 1 page 5/39

2.3.1 vShader menu barThe main window opens when a user launches vShader. The main menu bar contains drop‐down menus for File,Edit, View, Mesh, Build, and Help, detailed in the table below.

Table 1. vShader menu commands

Menu Command Description

File

New Project… Creates a new project file. If a project is currently open, the user isprompted to choose whether to save it first.

Open Project… Browses for and loads a .vsp vShader project.

Save Project… Saves the current project. If this is the first time saving this project, theuser is prompted to choose where to save it.

Load Vertex… Browses for and loads a vertex shader fromanexisting text file.

Load Fragment… Browse for and load a fragment shader fromanexisting text file.

Save VertexShader As… Prompts for filename and location to save the active vertex shader

Save FragmentShader As… Prompts for filename and location to save the active fragment shader

Exit Closes all open files and exit vShader.

Edit

Undo [Ctrl-z] Reverts to a previous edit state (only 1-level deep).

Redo [Ctrl-z] Re-applies the last “undone” edit command (only 1-level deep).

Cut [Ctrl-x] Deletes the selected items and saves a copy in the paste buffer.

Copy [Ctrl-c] Saves a copy of the selected items in the paste buffer.

Paste [Ctrl-v] Inserts the contents of the paste buffer.

Delete [Del or Bkspc] Removes the selected items.

Select All [Ctrl-a] Highlights all items in the current view.

View

Reset Preview Resets Preview window.

Snapshot Saves current preview image to a bitmap bmp file. A dialog is displayedto let the user choose where to save the bmp.

Perspective Uses perspective projection in the Shader Preview pane.

Ortho Uses orthographic projection in the Shader Preview pane.

Tool Bar Shows or hides toolbar icons.

Preview Window Shows or hides Preview window.

Project Explorer Shows or hides Project Explorer window.

Shader Editor Shows or hides Shader Editor window.

InfoLog Shows or hides InfoLog window.

UM2547vShader navigation

UM2547 - Rev 1 page 6/39

Menu Command Description

Mesh

Conic Spiral horn

Cube 3D cube

Klein Klein bottle

Plane 2D square

Sphere Ball

Teapot Utah teapot

Torus Donut

Trefoil Trefoil knot

Custom Mesh… Browses for and opens a 3DS mesh file.

Build

Compile Compiles the active shader. This command is also available via theCompile button in the Shader Editor window pane.

Link Links the vertex and fragment shaders into a shader program andapplies it to the mesh showed in the Shader Preview window pane.

Clear InfoLog Removes all text currently showed in the InfoLog window pane.

Help About Information about the used vShader version

UM2547vShader navigation

UM2547 - Rev 1 page 7/39

2.3.2 vShader window panesThere are four window panes in the vShader GUI: Preview, Project Explorer, Shader Editor and InfoLog.Each pane can be resized by left‐mouse‐dragging the pane edge. A pane can be hidden by clicking the X in theupper‐right corner of the pane, or by un‐checking the box next to its name in the View pull‐down of the mainmenu. Restoring a hidden window pane is done by checking the appropriate box in the View pull‐down menu.Individual vShader panes can be resized, relocated or converted to detached windows, as in the figure below.

Figure 3. vShader moveable panes example

Note: Changes made to pane arrangement are not restored on application or project relaunch.

2.3.2.1 Preview pane

The vShader Preview pane shows the current effect of the shaders on the chosen mesh geometry. A differentmesh may be chosen either via the Mesh pull-down menu in the menu bar near the top of the vShader mainwindow, or by right-mouse clicking in the Preview pane.When using the right-click method, the user can also choose between perspective and orthographic views of themesh, can reset the view orientation to the default, or can save the current view in the Preview window as abitmap file by selecting Snapshot.The object in the Preview window can be rotated, translated and scaled. Rotation is controlled by left-mouse-drag.The translation is done by holding the Ctrl key plus left-mouse-drag. The image scaling is seen by holding the Altkey while applying left-mouse-drag.When shader variables are changed, the Preview pane is automatically updated . When shader programs arechanged, they must be recompiled and relinked by the user through the Build menu. The Preview pane isautomatically updated to reflect the new Build.

2.3.2.2 Project Explorer paneThe vShader Project Explorer pane displays all the project resources in a familiar tree structure. The root of thetree is the project name and the branches and leaves classify the resources. Folders can be expanded by clickingon the plus sign next to them. They can be collapsed by choosing the minus sign. By right-mouse clicking on anyresource name, the user can view and usually edit that resource.

2.3.2.3 Shader Editor paneThe Shader Editor pane is a work area for entering and modifying shader programs, including two tabs: one forvertex shader and one for fragment shader. Changes made to a shader must be compiled and linked in order fortheir effect to appear in the Shader Preview pane.Compiling can be done by selecting Build then Compile from the main menu bar. Likewise, linking and applyingthe shaders is performed by choosing Build then Link.

2.3.2.4 InfoLog paneThe vShader InfoLog pane receives diagnostic messages from the compiler and linker, so that the user can see ifthe current shaders have built without errors. This pane can be cleared by selecting the Build then Clear InfoLogentry in the main menu.

UM2547vShader navigation

UM2547 - Rev 1 page 8/39

2.4 vShader project resourcesThe following project resources are accessible from the Project Explorer pane: header, fixed states, mesh,shaders, attributes, uniforms, and texturesClick on the item and an Editor pop‐up dialog appears where the user can enter alternate values.

2.4.1 Header Editor paneThe Header Editor pane groups project version, author and company. Expand the folder to see the settings, orright‐click (or double‐click) the folder to edit them.

Figure 4. Header Editor pane

2.4.2 Fixed State Editor paneThe Fixed State Editor pane is a list of OpenGL ES 2.0 fixed states settings (such as depth test enable/disable). Itallows the user to set all fixed states manually. Right‐click or double click to display an edit dialog.

Figure 5. Fixed State Editor pane

UM2547vShader project resources

UM2547 - Rev 1 page 9/39

2.4.3 MeshThis resource shows the name of the mesh that is currently being displayed in the Preview pane. It does not havea pop‐up window. Right‐click on the mesh name to select it. A different mesh can be selected from the resultingpull‐down menu.

2.4.4 ShadersLeft‐click on the plus sign next to the shaders folder to reveal the two sub nodes in this section, vertex andfragment. Double‐click (or right‐click and then choose Active) on either shader to bring it forward in the ShaderEditor for editing.

2.4.5 Attribute Editor dialogThe Attribute Editor dialog displays all attributes bound to the current project. It allows the user to add newattributes, and to edit or remove existing attributes. Right click on Attributes to add a new one. Click on the plussign to expand the attributes list, and then double‐click to edit a particular attribute. An attribute can also be editedor removed by right‐clicking on it. A new one can be added. Up to 12 attributes are allowed.

Figure 6. Attributes Editor dialog

2.4.6 Uniform Editor dialogUniform Editor displays all uniforms bound to the current project. Right click on Uniforms to add a new one or toexpand the list and double‐click on a given uniform to bring up the Uniform Editor dialog. When a uniform is right‐clicked, the user can add new uniforms or edit/remove existing uniforms. Up to 160 uniforms are allowed.

Figure 7. Uniform Editor dialog

UM2547vShader project resources

UM2547 - Rev 1 page 10/39

2.4.7 Texture Editor dialogTexture Editor allows the user to select a texture for each of up to 8 texture units. The effect of applying eachtexture is seen immediately in the vShader Preview pane.

Figure 8. Texture Editor dialog

The texture selection option list is created from the texture files located in the textures sub-folder of the project.The list can be expanded by adding textures to the textures folder, formatted as bitmap files.

UM2547vShader project resources

UM2547 - Rev 1 page 11/39

3 vCompiler

vCompiler is an off‐line compiler and linker for translating vertex and fragment shaders written in OpenGL ESSL(ES shading language) into binary executables. vCompiler is driven by a simple command‐line interface.

3.1 vCompiler command line syntaxWindows® and Linux® command line syntax are the same.

3.1.1 SyntaxOptional inputs are indicated by brackets. A fixed order for options in the command is not required.

vCompiler [–f <gpuConfigurationFile>] <shaderInputFileName> [shaderInputFileName_2][ –c ] [–h] [ –l ] [–o <outputFileName> ] [–On ] [ –v ] [–x <shaderType> ]

3.1.2 Required input parameterThe table below details the required input parameter.

Table 2. vCompiler required input parameter

Parameter Description

shaderInputFileName

Shader input file name that must contain one of the following file extensions:• vert: vertex shader source file• frag: fragment shader source file• vgcSL: previously compiled vertex shader input/output file• pgcSL: previously compiled pixel shader input/output file

UM2547vCompiler

UM2547 - Rev 1 page 12/39

3.1.3 Optional input parametersThe table below details the optional input parameters.

Table 3. vCompiler optional input parameters

Parameter Description

shaderInputFileName_2

Up to two shader files can be specified. The second shader file is optional but must have oneof the file extensions listed in Table 2.

If the first shader is a vertex shader, this second shader must be a fragment shader.

If the first shader is a fragment shader, the second must be a pixel shader.

Note: Pre-compiled and compiled shaders may be mixed, as long as one is a vertex shaderand the other a fragment shader.

-c

Compile each vertex .vert file into a vgcSL file, and/or each fragment shader .frag file into apgcSL only (no merged result .gcPGM file) .

If this option is not specified, the following occurs:• When only one shader is specified, it is compiled into a .[v/p]gcSL file.• When two shaders are specified, one is assumed to be a vertex shader and the other a

fragment shader. Each shader can be either a previously compiled .vgcSL or .pgcSL file,or a .vert or .frag file still to be compiled. The two are merged into a .gcPGM file aftersuccessful compilation.

-f <gpuConfigurationFile>

Specifies a configuration file.

If this option is not specified, the viv_gpu.config file in the vCompiler working directory is usedas default configuration file.Syntax example: vCompiler –f viv_gpu_880.config foo.vert bar.fragNote: vCompiler does not work correctly if the GPU configuration file cannot be found orcontains incorrect content (see Section 3.2 ).

-h Shows a help message on all the command options.

-l

Creates a log file.

The log file name is created by taking the first input file name, then replacing its file extensionwith .log. If the input file name does not have a file extension, .log is appended.

Examples: myvert.vert becomes myvert.log or inputfrag becomesinputfrag.log.

-o <outputFileName>

Specifies the output file name.

If the path is other than the current directory, it must also be specified. Any extension can bespecified. If the extension is not specified, the following default types are supported :• vgcSL: compiled vertex shader output file, usually compiled from a .vert input source file

(default result for a single-file compile)• pgcSL: compiled pixel shader output file, usually compiled from a .frag source input file• gcPGM: compiled file merging vertex shader and fragment/pixel shader into a single

output file

-OnOptimization level• O0: all optimizations disabled• O1: all optimization levels enabled (default)

-vVerbose

Prints compiler version and diagnostic messages to stdout.

-x<shaderType>

Explicitly specifies the type of shader instead of relying on the file extension.

This option applies to all the following shaderType input files until the next -x option:• vert: vertex shader source file• frag: fragment shader source file• vgcSL: compiled vertex shader input/output file• pgcSL: compiled pixel shader input/output file

-x none Reverts back to recognizing shader type according to the file name extension.

UM2547vCompiler command line syntax

UM2547 - Rev 1 page 13/39

3.1.4 vCompiler output filesOutput files are placed in the current directory unless another directory is specified with the –o option.

3.1.5 vCompiler syntax examplesSome vCompiler commands examples are listed below:• vCompiler foo.vert produces foo.gcSH.• vCompiler bar.frag produces bar.gcSH.• vCompiler foo.vertbar.frag produces foo.gcPGM.• vCompiler -v -l -O1 foo.vertbar.frag produces foo.gcPGM and foo.log.• vCompiler -v -l -O1 -o foo_barfoo.vertbar.frag produces foo_bar.gcPGM and foo_bar.log.

3.2 Core-specific configurationTo ensure the shader binaries generated by vCompiler work correctly and optimally, the GPU must be specifiedbefore starting to run vCompiler.There are two or more configuration files in the installation directory.For example:• viv_gpu.config configuration file for GC7000XS-6008 (default)• viv_gpu_400t.config configuration file for GC400

To change the GPU configuration, rename the GPU file to viv_gpu.config. For example, on a Linux platform, thefollowing commands can be used:

mv viv_gpu.config viv_gpu_7000xs.configmv viv_gpu_400t.config viv_gpu.config

The content of these files must not be modified, and the viv_gpu.config file must be in the vCompiler workdirectory. If customization is required, the format for the file contents is fixed and only the value for eachparameter may be changed. The gpu config file needs five IDs to identify the target GPU for the offline compilersince the driver has a complete feature table to set up GPU configurations correctly based on these IDs.Here is the default viv_gpu.config file :

chipModel = 0x7000;chipRevision = 0x6008;productID = 0x70004;ecoID = 0x0;customerID = 0x0

UM2547Core-specific configuration

UM2547 - Rev 1 page 14/39

4 vTexture

vTexture is a command line tool that provides compression and decompression functions to transfer imageformats.

4.1 Formats

4.1.1 Supported file formatsvTexture supports the following:• compression of uncompressed tga, bmp and png files to any of the following formats:

– dxt1– dxt3– dxt5– etc1– etc2

• decompression to uncompressed tga files of the following compressed format file types:– dxt1– dxt3– dxt5– etc1– etc2

The compressed dxtn format image file is stored as a dds file, and the etcn format image is stored as a pkm or ktxfile.The tga format follows the RGBA or RGB color model and etcn format provides an image following the RGB888color model.

Note: Compressing a tga image of RGBA format to an etcn format results in a loss of alpha values.

4.1.2 Supported formats for tile and de-tile conversionsvTexture supports conversions between linear textures and the following tile configurations:• Linear: no tiling• Tile: 4x4 tile• Supertile: 64x64 tile

Formats supported for tile format conversions are the following:• source data

– bmp– png– tga

• output data– bmp– raw data of a specified type (such as RGBA8888, BGRA8888, RGB888, BGR888, RGB565, BGR565

or ARGB1555)

UM2547vTexture

UM2547 - Rev 1 page 15/39

4.1.3 Output formatsOutput from the compress option:• dxtn format image file, stored as a dds file• etc1 and etc2 format images, stored as a pkm or ktm file

Output from the decompress option: all supported formats are decompressed to an uncompressed tga file.Output from tile and de-tile options:• bmp if –r not specified• raw if –r specified

4.1.4 vTexture raw output file format definitionThe vTexture raw file is a Vivante-defined file, with .raw extension (see details in the table below).

Table 4. vTexture raw file details

Characteristic Size(bytes) Data type Description

Width in pixels 4 INT Number of width pixels

Height in pixels 4 INT Number of height pixels

Pixel format 4 INTInteger value of numeric for a supported format, as defined ingceSURF_FORMAT enumeration (see Table 5).These value canalso be found in samples (named TiledTexture).

Tile format 1 BOOL

bit 0: tile

bit 1 supertile

bit 5: flag for multi-tile

other bits reserved

Supertile format 1 INT

Integer value:• 0: supertile layout mode 0• 1: supertile layout mode 1• 2: supertile layout mode 2

Reserved 2 - Not used

Table 5. gceSURF_FORMAT enumeration

Supported format Numeric

ARGB_1555 208

RGB_565 209

BGR_888 210

BGRX_8888 211

BGRA_8888 212

BGR_565 302

RGB_888 303

RGBX_8888 305

RGBA_8888 306

UM2547Formats

UM2547 - Rev 1 page 16/39

4.2 Environment variableThe only environment variable that vTexture currently expects is PATH to be set as follows:

PATH=%PATH%;"C:\Program Files\Vivante\vTexture\”

4.3 Command line syntaxOpen a Command prompt.Navigate to the folder that contains the vTexture files (for example, C:/Program Files (x86)/Vivante/vTexture).Launch the vTexture or vTextureTools application using the command line syntax described in the next sections.

4.3.1 SyntaxThe usage of the command line tool is as follows:• For compression/decompression:

vTextureTools –c TYPE [–s SPEED] –src FILE [–dest FILE]

or

vTextureTools –d TYPE –src FILE [–dest FILE]

• For tiling and de-tiling:

vTextureTools –t|–st [–2 [–r|––raw=FORMAT] –m LAYOUT] –src FILE [–dest FILE]

or

vTextureTools –t|–st [–2 [–r|––raw=FORMAT] –m LAYOUT] –src FILE [–dest FILE]

4.3.2 General parametersvTexture general parameters are detailed in the table below.

Table 6. vTexture general parameters

Parameter Description

-h Shows help.

-src [FILE]

Source file - input image path and filename

vTexture uses the file extension type as image type.• For –c compress, the application expects an input filename with a tga extension.• For –d decompression, the application expects a dds, ktx or pkm extension.• For –t tile and –dt de-tile, the application expects a bmp or tga extension.

-dest [FILE]

Destination file - image path and filename

The application expects a filename with a tga, dds, ktx or pkm extension for compress/uncompress orbmp or raw for tile/de-tile.

If the -dest parameter is not set, vTexture automatically generates a name for the newly generated file,using the source file name as the prefix appending critical parameters and file type information.

UM2547Environment variable

UM2547 - Rev 1 page 17/39

4.3.3 Compression/decompression parametersParameters listed in the table below are used for compression and decompression.

Table 7. vTexture compression/decompression parameters

Parameter Description

-c

Compress a source image of uncompressed tga format.

[TYPE] specifies the target output compress image format:• dxt1 (default)• dxt3• dxt5• etc1• etc2

-d

Decompress a source image of format specified by the value [TYPE].

The resulting file type is uncompressed tga.

This option decompresses dxt1, dxt3, dxt5, etc1 or etc2 format image to tga format.

-s

Compression [SPEED] mode for etcn images:• fast (default)• slow• medium

4.3.4 Tile/de-tile parametersParameters listed in the table below are used for tiling and de-tiling between linear and tiled formats.

Table 8. vTexture tile/de-tile parameters

Parameter Description

-t Converts linear data to tiled texture output.

-stEnables supertile format

This option is an alternate to –t. If –st and –t are used together, -st is set.

-dt De-tile: converts tiled texture to linear texture output.

-2 Tile/de-tile in multi- format.

-m

[LAYOUT] defines the layout mode for supertiled textures:• 0: Legacy supertile mode (default)• 1: Supertile mode when hardware has HZ• 2: Supertile mode when hardware has NEW_HZ or FAST_MSAA

-r

Specifies output data as raw pixel output instead of bmp.

Use --raw=rgb565 to specify raw pixel [FORMAT].

Supported raw formats are RGBA8888, BGRA8888, RGB888, BGR888, RGB565, BGR565 andARGB1555.

UM2547Command line syntax

UM2547 - Rev 1 page 18/39

4.3.5 vTexture syntax examplesSome examples for compress are listed below.

vTextureTools -c dxt1 -src d:\myfile.png -dest c:\compress.ddsvTextureTools -c dxt1 -src d:\myfile.tga -dest c:\compress.ddsvTextureTools -c etc1 -s slow –src d:\myfile.png –dest c:\compress.pkmvTextureTools -c etc1 -s slow src d:\myfile.tga -dest c:\compress.pkmvTextureTools -c etc2 -s slow –src d:\myfile.bmp -dest c:\compress.ktxvTextureTools -c etc2 -s slow –src d:\myfile.tga -dest c:\compress.ktxvTextureTools -c etc2 -src d:\myfile.bmp -dest c:\compress.ktxvTextureTools -c etc2 -src d:\myfile.tga -dest c:\compress.ktxvTextureTools -c etc2 -src d:\myfile.tga -dest c:\compress.pkm

Some examples for decompress are listed below:

vTextureTools –d etc1 –src c:/vtexin/myfile2.pkm –dest c:/vtextout/myfile2.tgavTextureTools -d -src c:/vtexin/myfile3.dds -dest c:/vtextout/myfile3.tga (assumes DXT1)vTextureTools -d tga -src d:\myfile.dds -dest c:\decompress.tgavTextureTools -d tga -src d:\myfile.ktx -dest c:\decompress.tga

Some examples for tile (linear to tiled) conversion are listed below:• Tile linear texture to standard tile texture

vTextureTools.exe –t –src 123.bmp• Tile linear texture to supertiled texture

vTextureTools.exe –st –src 123.bmp

Some examples for de-tile (tiled to linear) conversion are listed below:• De-tile tiled texture to linear texture

vTextureTools.exe –dt –t –src 123-tiled.bmp• De-tile supertiled texture to linear texture

vTextureTools.exe –dt –st –src 123-supertiled.bmp

UM2547Command line syntax

UM2547 - Rev 1 page 19/39

5 vProfiler and vAnalyzer

vProfiler is a run-time environment for collecting performance statistics of an application and the graphics pipeline.vAnalyzer is an utility for graphically displaying the data gathered by vProfiler and aiding in visual analysis ofgraphics, compute and vision performance.Used together, these tools assist software developers in optimizing application performance. The GPU includesperformance counters that track a variety of GPU functions. vProfiler gathers data from these counters duringruntime and tracks data for a range of frames or a single frame from any application. Additional counters arepresent in the software drivers and hardware access layer.

5.1 Fundamentals of performance optimizationWhenever an application runs on a computer, it uses one or more of the available resources. These computeresources include the CPU, the graphics processor, caches and memory, hard disks, and possibly even thenetwork. Viewed simplistically, it is always the case that one of these resources is the limiting factor in how quicklythe application can finish its tasks. This limiting resource is the performance bottleneck. Remove this bottleneckand application performance is improved.The goal of optimizing or tuning application performance is to balance the use of resources so that none of themholds back the application more than any of the others. In practice there is no single or simple way to tune anapplication. The whole system needs to be considered, including the size and speed of individual components aswell as interactions and dependencies among components.vProfiler collects information on GPU usage and on calls to functions within the graphics pipeline. As such itprovides an excellent view into what happens on the GCCORE graphics processor at any point in time, down tothe individual frame. When the application performance is GPU-bound, vProfiler and vAnalyzer are the right toolsto help determine why.

Note: The initial determination of the component that is the performance bottleneck is the domain of systemperformance analyzers and is outside the scope of the GPU tools.

5.2 Setup for LinuxThe STM32MP157GPUTK Windows package includes vAnalyzer for the Windows environment. vProfiler can becompiled for Linux, as per the instructions below.vProfiler stores software and hardware counters captured per frame in the vprofiler.vpd file. vAnalyzer readsthe .vpd file and allows the user to browse counters, to visualize application performance bottlenecks and tomeasure system utilization of that application run.

Note: vProfiler does not store frame buffer images due to excessive overhead that changes the behavior ofapplications.

5.2.1 Enable vProfiler option in kernelThe Vivante GPU driver is built with the vProfiler capability. Add gpuProfiler=1 in the insmod command line toactivate the vProfiler functionality, as shown in the code below.

insmod /system/lib/modules/galcore.ko gpuProfiler=1 [OPTIONS]

UM2547vProfiler and vAnalyzer

UM2547 - Rev 1 page 20/39

5.2.2 Set environment variables for LinuxThe following table summarizes the environment variables supported by vProfiler.

Table 9. vProfiler environment variables for Linux

Environment variable Description

VIV_PROFILE

• 0: vProfiler disabled(default)• 1: vProfiler enabled• 2: control via application call• 3: control over which frames to profile with vProfiler

VP_OUTPUT Specifies vProfiler output file name (default is vprofiler.vpd).

VP_FRAME_NUM Specifies the number of frames dumped by vProfiler when VIV_PROFILE = 1 .

VP_FRAME_START Specifies the frame to start profiling with vProfiler when VIV_PROFILE = 3.

VP_FRAME_END Specifies the frame to end profiling with vProfiler when VIV_PROFILE = 3.

VP_USE_GLFINISHEnables [1] or disables [0] (default) the use of glFinish()/glFlush() APIs as the framedelimiter in addition to eglSwapBuffers. This variable enables application thread that doesnot use eglSwapBuffers() to generate useful GPU profiling data for analysis.

VP_PERDRAW_MODE Enables [1] or disables [0] (default). When enabled, vProfiler collects a counter for eachdraw call.

VP_DISABLE_PROBE Disables PROBE mode and makes vProfiler to use AHB counters for profiling.

VP_ENABLE_PRINT Enables vProfiler to print out the counter information to the console.

5.2.3 Environment variable detail

5.2.3.1 VIV_PROFILE

The environment variable VIV_PROFILE can be used to control enable /disable and set profiling modes forvProfiler.• VIV_PROFILE = 0

By default, vProfiler is disabled in the driver. If vProfiler has been enabled, it can be disabled by settingVIV_PROFILE to 0 with the code below.

export VIV_PROFILE=0

• VIV_PROFILE = 1To enable vProfiler, set VIV_PROFILE to 1 with the code below.

export VIV_PROFILE=1

To limit the number of frames to analyze, use the environment variable VP_FRAME_NUM (available onlywhen VIV_PROFILE = 1). For example, the code below makes vProfiler dump performance data for the first100 frames.

export VP_FRAME_NUM=100

• VIV_PROFILE = 2Mode VIV_PROFILE = 2 provides support for glEnable(GL_PROFILE_VIV) andglDisable(GL_PROFILE_VIV), that are used to choose which frames must be profiled. In this mode, vProfileris disabled by default. It begins to do profiling only after a glEnable(GL_PROFILE_VIV) call from theapplication. vProfiler stops profiling when glDisable(GL_PROFILE_VIV) is called. Note that the flag is onlychecked at every frame end, in eglSwapBuffers. To use this mode, set VIV_PROFILE to 2 with the codebelow.

export VIV_PROFILE=2

UM2547Setup for Linux

UM2547 - Rev 1 page 21/39

• VIV_PROFILE = 3Setting VIV_PROFILE to 3 provides support for two environment variables VP_FRAME_START andVP_FRAME_END, that are used to choose which frames must be profiled. In this mode, vProfiler is disabledby default. It begins to do profiling starting at the frame number specified by VP_FRAME_START and it endsthe profiling after the frame number specified by VP_FRAME_END. To use this mode, set VIV_PROFILE to3 with the code below.

export VIV_PROFILE=3export VP_FRAME_START=10export VP_FRAME_END=90

Note: The GPU profiling mode requires the GPU power management (PM) functions to be disabled to get the preciseprofiling data. When kernel module “galcore” is inserted with gpuProfiler=1, the PM functions in the driverare not disabled. The PM functions are disabled when VIV_PROFILE is set to 1, 2, or 3, and the applicationstarts. The PM functions are enabled when VIV_PROFILE is set to 0 and the application starts again.

5.2.3.2 VP_OUTPUTThe vProfiler output file is vprofiler.vpd by default. To specify an alternate filename, use the environment variableVP_OUTPUT (code example below).

Export VP_OUTPUT=sample.vpd

5.2.3.3 VP_USE_GLFINISHglFinish() and glFlush are treated as the frame delimiter as eglSwapBuffers(). By default, vProfiler only useseglSwapBuffers() as delimiter to check hardware counters. The command below enables vProfiler to use glFinish/glFlush as additional delimiter so application thread that does not use eglSwapBuffers(). It can generate usefulGPU profiling data for analysis.

export VP_USE_GLFINISH=1

5.2.3.4 VP_DISABLE_PROBEThis variable only applies to the GPU with the PROBE feature support. It disables PROBE mode and makesvProfiler use AHB counters for profiling. This variable does not affect the hardware only that supports the AHBcounter. The default value is off.

5.2.3.5 VP_ENABLE_PRINTThis variable provides a convenient way to check some critical profiling information without using the off-linevAnalyzer to open a VPD file. Once enabled, vProfiler prints out the counter information to the console. Thedefault value is off.

5.3 vProfiler setup for Android™

Next sections describe how to setup vProfiler to use it with Android.

5.3.1 Enable vProfiler option in kernelThe Vivante GPU driver is built with the vProfiler capability. Add gpuProfiler=1 in the insmod command line toactivate the vProfiler functionality, as shown in the code below.

insmod /system/lib/modules/galcore.ko gpuProfiler=1 [OPTIONS]

UM2547vProfiler setup for Android™

UM2547 - Rev 1 page 22/39

5.3.2 Set property optionsThe following table summarizes the property options that vProfiler supports through running the commandadb shell setprop [OPTIONS]. These options are similar to the environment variables available for Linux.

Table 10. vProfiler property options for Android

Option Description

setprop VIV_PROFILE 0 Disables vProfiler in the drivers.

setprop VIV_PROFILE 1 Enables vProfiler in the drivers.

setprop VIV_PROFILE 2 vProfiler enable/disable controlled by glEnable(GL_PROFILE_VIV) andglDisable(GL_PROFILE_VIV) calls

setprop VIV_PROFILE 3setprop VP_FRAME_STARTsetprop VP_FRAME_END

vProfiler start/stop at frames specified in VP_FRAME_START andVP_FRAME_END

setprop VP_PROCESS_NAMEappname

Specifies the application to profile. Change the app name as needed to profileanother application. There may be different sub-case names used by anapplication. Be sure to accurately specify a case name to match the name seenon the command line when using ps command.

Note: This option is only available for Android, not available for Linux.

setprop VP_OUTPUT newpath

Specifies a new location for vProfiler output. By default, the vpd file is createdunder /sdcard/. If an application has no access to the SD card, another path canbe specified where the application does have write permission.

Note: For applications initializing during the Android system boot startup, such aslauncher, the process must be killed after the change to a new path. When theapplication automatically restarts, the vpd file is accessible at the expected place.

setprop VP_FRAME_NUM xxx

Limits the number of frames to analyze. For example, to make vProfiler dumpperformance data for the first 100 frames: setprop VP_FRAME_NUM 100.This option can only be used when VIV_PROFILER = 1.

Note: When this option is not used, the profile file generated when running anapplication for a long time can be very large. This takes a large amount of diskspace and also makes it hard to view the data in vAnalyzer.

setprop VP_USE_GLFINISH 0setprop VP_USE_GLFINISH 1

Enables/disables the use of glFinish()/glFlush() as the frame delimiter in additionto eglSwapBuffers (default 0). By default eglSwapBuffers() is used as the framedelimiter. This command makes the application thread that does not useeglSwapBuffers() to generate useful GPU profiling data for analysis.

setprop VP_PERDRAW_MODE 0setprop VP_PERDRAW_MODE 1

Enables/disables the "per draw" mode. When enabled, vProfiler collects a counterfor each draw call.

setprop VP_DISABLE_PROBE Disables Probe mode and make vProfiler use AHB counters for profiling.

setprop VP_ENABLE_PRINT Enables vProfiler to print out the counter information to the console.

UM2547vProfiler setup for Android™

UM2547 - Rev 1 page 23/39

5.4 vProfiler performance countersvProfiler is implemented by utilizing hardware counters and a group of instrumentations inserted into drivers thatare controlled by compilation flags. These counters provide detailed per-frame runtime information about theapplication that can help the developer monitor and tune the application resource usage.The counters are divided into four sets detailed in the table below.

Table 11. Performance counters

Counter type Description

HALCounters Driver memory usage

Program Statistics of the shaders loaded in the GPU (available only for OpenGL ES 2.0)

OGLCounters Various OpenGL ES counters, such as API usage and primitives drawn

OVGCounters Various OpenVG counters, such as API usage and primitives drawn

5.5 vAnalyzer - view and analyze a runtime profilevAnalyzer is a GUI-based tool to view and analyze GPU performance data collected using counters during anapplication run. The performance data from a binary file(*.vpd) written by vProfiler is displayed by vAnalyzer bothin text lists and as line graphs. vAnalyzer features a multi-tab, multi-pane graphical user interface that gives theuser several ways to inspect any frame in a captured animation sequence.

5.5.1 Load profile filesvAnalyzer accepts a profile for input, that is a .vpd file of performance data created by vProfiler during a run. Forexample, the saved file may have a name such as sample.vpd.A .vpd file can be selected using the File/Load Profile Data menu option.When a performance profile is loaded, vAnalyzer populates the title bar with information about the GPU and theCPU.

UM2547vProfiler performance counters

UM2547 - Rev 1 page 24/39

The vAnalyzer screen shot below shows the vAnalyzer GUI immediately after loading a .vpd performance file andmoving the frame number slider to frame 700. By default, the vAnalyzer main pane displays the Charts tab thatprovides charts for frame time, driver time and GPU idle cycles. Additional charts, selected from the list ofvariables on the right, can be added in the graph window. Different combinations of counters can be displayed ingraphical and list form to illustrate resource utilization for any portion of the profiled application. A second tabcontains system information.

Figure 9. vAnalyzer GUI main window

5.5.2 vAnalyzer menu barThe vAnalyzer main menu bar contains the following drop-down menus:File• Load Profile Data: loads a .vpd profile file.• Export Current Frame Data: dumps all the counters for the frame being viewed to a .cvs file.• Exit: exits vAnalyzer.

Chart• Create chart: creates a new chart.• Customize chart: adds or deletes counters in an existing chart.• Remove chart: deletes a chart.• Export data from chart: dumps the counters in a chart to a .csv file.• Save chart to png: dumps the chart to a .png file.• View: zooms in/out or fits the chart.

Viewer• OpenGL function call viewer: displays the OpenGL function call statistics.• Program viewer: displays the shader program statistics.

Help• About: gives version information for vAnalyzer.

UM2547vAnalyzer - view and analyze a runtime profile

UM2547 - Rev 1 page 25/39

5.6 vAnalyzer charts

5.6.1 vAnalyzer Chart tab and menu optionsOn the Chart tab in the vAnalyzer main window (upper-left pane), two default line graphs are displayed (see thefigure below).

Figure 10. vAnalyzer performance counter charts

UM2547vAnalyzer charts

UM2547 - Rev 1 page 26/39

5.6.2 Chart customizationThe Create New Chart dialog window shown in the figure below, can be invoked from the drop menu Chart/Customize Chart, or by right-clicking in the Chart tab area.

Figure 11. vAnalyzer Create New Chart dialog

• Chart/Customize Chart: Additional performance counters can be added to an existing chart.• New Chart: A new chart can be added. A single chart can display up to four counters and the Chart pane

can hold up to eight charts. Thus a maximum of 32 counters can be graphed at the same time.• Remove Chart: Any chart can be removed from the display using the drop menu Chart/Remove Chart.

5.6.2.1 Chart components and navigation

On the plots displayed in Figure 10, there is a blue vertical frame marker, that marks the current frame position inthe timeline.Zooming in on a set of frames can be achieved in one of the two following ways:• Hold down the left mouse button and then sweep a selection box across a range of frame numbers, either

on a plot itself or in the common X-axis (frame numbers) in the Chart pane, before releasing the mousebutton. All charts in the Chart pane zoom in to the same range of frames.

• If the mouse has a scroll wheel, zoom can be reached by rolling the wheel forward--toward (zomm in) orbackward (zoom out) the screen.

To reset zoom to the default (show the entire timeline), press the escape key (ESC) on the keyboard. The chartview changes to include all frames, from start to end.

5.6.2.2 Data exportThe performance counters in a chart can be dumped to a .csv file by selecting from the dropdown menu Chart/Export data from chart. The .csv file can be viewed using Excel or another text viewer.The chart can also be dumped to a .png file by selecting from the main menu Chart/Save chart to PNG.

UM2547vAnalyzer charts

UM2547 - Rev 1 page 27/39

5.6.3 vAnalyzer Frame Number slider barIn the lower-left pane of the vAnalyzer window, there is a Frame Number gauge in the form of a slider bar.Numbers at each end of the bar indicate the initial frame (0) and the last frame available in the loaded sample. Byleft-clicking and holding the slider, the user can change the selected frame to analyze. When the frame number ischanged, the blue vertical line that indicates the current frame moves and the reported Frame Number changes inthe upper-right pane Frame Analysis Summary.

Figure 12. vAnalyzer Frame Number slider bar

5.6.4 vAnalyzer System Info tabWhen a .vpd profile is loaded, system information about the profiled machine populates the fields on the SystemInfo tab (see the figure below). Some information is repeated in the title bar of the main GUI for quick reference.

Figure 13. vAnalyzer System Info tab

UM2547vAnalyzer charts

UM2547 - Rev 1 page 28/39

5.6.5 vAnalyzer Frame AnalysisA selection of performance counters for the frame being viewed are displayed on the right side of the vAnalyzermain GUI. The user can convert this pane to a pop-up window by dragging the pane outside the applicationwindow. Drag it back to the right pane area of the application window to reintegrate the pane.

Figure 14. vAnalyzer Frame Analysis Summary and Detail tabs

5.6.5.1 Summary tab

The Summary tab displays summary information for the frame being viewed.The selected Frame Number can be changed by entering a new frame number in the text box at the top of the list.The user must press Enter after the input to activate the change. Then Summary values, sliders, and chartschange to reflect the newly entered frame number.The Summary values below Frame Number are not directly changeable. They change only when the framenumber is changed, either in the Summary tab, by moving the Frame Number slider, or by selecting a frame fromthe Frame Selection pane.Clicking the “…” button to the right of a Summary item brings up the corresponding counters in the Detail tab. Forexample:• Clicking the “…” button to the right of Primitive Rate switches the view to the Detail tab and expands the

primitive processing category.• Clicking the “…” button for Driver Utilization brings up the pop-up window OpenGL function call viewer.

5.6.5.2 Detail tabThe Detail tab reports values for overall performance evaluation, such as the frame rate, the driver utilization andthe GPU cycles. Additionally counter detail is accessible on this tab. The categories of available counters in theDetail tab are the following: overall, OpenGL ES, vertex processing, primitive processing, pixel processing, shaderprocessing and bandwidth.

5.6.6 vAnalyzer Frame SelectionAs with the Frame Analysis pane, the Frame Selection pane can be dragged to display as an independent pop-upwindow.

UM2547vAnalyzer charts

UM2547 - Rev 1 page 29/39

5.6.6.1 Slow Frames tab

The Slow Frames tab lists the 10 slowest frames in the animation sequence, by time in ascending order fromslowest to tenth slowest (see the figure below).

Figure 15. vAnalyzer Frame Selection-Slow Frames tab

The user can left click on any entry or can use the arrow keys to move up and down the list, and the display ineach of the other GUI panes changes to match that frame.

5.6.6.2 Critical Frames tabSelect the Critical Frames tab to customize the criteria by which a frame is chosen for inspection. One or more ofthe performance counters can be specified in building the query, that also allows for AND and OR logic.Queries must follow a pattern such as: “counter name” condition(‘<’/’>’/’==’) valuesUsers can identify counter names from those in the Frame Analysis Detail tab. An example is provided just belowthe Query input text box.

Figure 16. vAnalyzer Frame Selection-Critical Frames tab

UM2547vAnalyzer charts

UM2547 - Rev 1 page 30/39

5.7 vAnalyzer ViewerThe Viewer information pop-up windows can be launched by selecting Viewer/OpenGL function call viewer orViewer/Program viewer from the main menu. The selected Viewer appears in a pop-up window.

Figure 17. Main menu Viewer selection

5.7.1 OpenGL Function Call ViewerThe OpenGL Function Call Viewer includes the three following information areas:• The OGL Function Name area contains a table that lists the available OpenGL ES functions by function

name and function type, the run time and the number of times each has been called for this frame. Functionscan be sorted by clicking in the column heading area. For example, the functions can be sorted by call countor run time by clicking the title bar of “# of Call” or “Time (ms)”.

• The Top 5 Functions area contains a histogram that shows the top five call count of the listed OpenGLfunctions.

• The Property View area shows the summary when no function is selected. While it shows performance hintsfor the function when one is selected.

Figure 18. vAnalyzer OpenGL Function Call Viewer window

UM2547vAnalyzer Viewer

UM2547 - Rev 1 page 31/39

5.7.2 Program ViewerFor a given frame number, the Program Viewer gives the statistics for shader programs: uniforms, attributes andnumber of instructions in the shader (only for OpenGL ES 2 profile data). The item description is displayed in thelower text window when selecting the item. Expand by clicking on VS or PS sub-menu to expand the detail for thatshader source code.

Figure 19. vAnalyzer Program Viewer

UM2547vAnalyzer Viewer

UM2547 - Rev 1 page 32/39

Revision history

Table 12. Document revision history

Date Version Changes

26-Mar-2019 1 Initial release.

UM2547

UM2547 - Rev 1 page 33/39

Contents

1 STM32MP157GPUTK overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

1.1 STM32MP157GPUTK components overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 STM32MP157GPUTK operating system requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.3 STM32MP157GPUTK installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 vShader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

2.1 vShader components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2 Getting started with vShader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2.1 Creating a new project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2.2 Opening an existing project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2.3 Saving a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.3 vShader navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.3.1 vShader menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.3.2 vShader window panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.4 vShader project resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.4.1 Header Editor pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.4.2 Fixed State Editor pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.4.3 Mesh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.4.4 Shaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.4.5 Attribute Editor dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.4.6 Uniform Editor dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.4.7 Texture Editor dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 vCompiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

3.1 vCompiler command line syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.1.1 Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.1.2 Required input parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.1.3 Optional input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.1.4 vCompiler output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.1.5 vCompiler syntax examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.2 Core-specific configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4 vTexture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

UM2547Contents

UM2547 - Rev 1 page 34/39

4.1 Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.1.1 Supported file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.1.2 Supported formats for tile and de-tile conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.1.3 Output formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.1.4 vTexture raw output file format definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.2 Environment variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.3 Command line syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.3.1 Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.3.2 General parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.3.3 Compression/decompression parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.3.4 Tile/de-tile parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4.3.5 vTexture syntax examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 vProfiler and vAnalyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

5.1 Fundamentals of performance optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.2 Setup for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.2.1 Enable vProfiler option in kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.2.2 Set environment variables for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.2.3 Environment variable detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.3 vProfiler setup for Android™. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.3.1 Enable vProfiler option in kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.3.2 Set property options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.4 vProfiler performance counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.5 vAnalyzer - view and analyze a runtime profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.5.1 Load profile files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.5.2 vAnalyzer menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.6 vAnalyzer charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.6.1 vAnalyzer Chart tab and menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.6.2 Chart customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.6.3 vAnalyzer Frame Number slider bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.6.4 vAnalyzer System Info tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

5.6.5 vAnalyzer Frame Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

5.6.6 vAnalyzer Frame Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

UM2547Contents

UM2547 - Rev 1 page 35/39

5.7 vAnalyzer Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

5.7.1 OpenGL Function Call Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

5.7.2 Program Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

UM2547Contents

UM2547 - Rev 1 page 36/39

List of tablesTable 1. vShader menu commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Table 2. vCompiler required input parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Table 3. vCompiler optional input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Table 4. vTexture raw file details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Table 5. gceSURF_FORMAT enumeration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Table 6. vTexture general parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Table 7. vTexture compression/decompression parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Table 8. vTexture tile/de-tile parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Table 9. vProfiler environment variables for Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Table 10. vProfiler property options for Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Table 11. Performance counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Table 12. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

UM2547List of tables

UM2547 - Rev 1 page 37/39

List of figuresFigure 1. STM32MP157GPUTK vTools components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Figure 2. vShader GUI main window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Figure 3. vShader moveable panes example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Figure 4. Header Editor pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Figure 5. Fixed State Editor pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Figure 6. Attributes Editor dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Figure 7. Uniform Editor dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Figure 8. Texture Editor dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Figure 9. vAnalyzer GUI main window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Figure 10. vAnalyzer performance counter charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Figure 11. vAnalyzer Create New Chart dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Figure 12. vAnalyzer Frame Number slider bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Figure 13. vAnalyzer System Info tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Figure 14. vAnalyzer Frame Analysis Summary and Detail tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Figure 15. vAnalyzer Frame Selection-Slow Frames tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Figure 16. vAnalyzer Frame Selection-Critical Frames tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Figure 17. Main menu Viewer selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Figure 18. vAnalyzer OpenGL Function Call Viewer window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Figure 19. vAnalyzer Program Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

UM2547List of figures

UM2547 - Rev 1 page 38/39

IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to STproducts and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. STproducts are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.

Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design ofPurchasers’ products.

No license, express or implied, to any intellectual property right is granted by ST herein.

Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.

ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks. All other product or servicenames are the property of their respective owners.

Information in this document supersedes and replaces information previously supplied in any prior versions of this document.

© 2019 STMicroelectronics – All rights reserved

UM2547

UM2547 - Rev 1 page 39/39