Introduction to PVRScope#

Document Overview#

This document is intended as a reference for PVRScope library and provides a number of examples of its use. The document covers key topics including how to access the performance counters in PowerVR hardware and send user defined information to PVRTune.

Note

For more information about PVRTune, consult the PVRTune User Manual

Library Overview#

PVRScope is a utility library with two components:

  • PVRScopeStats - PVRScopeStats is used to access the hardware performance counters in PowerVR hardware.

  • PVRScopeComms - PVRScopeComms allows an application to send user-defined information to PVRTune via PVRPerfServer in the form of counters, timing data, and marks, or as editable data that can be passed back to the application.

PVRScope is supplied in the following files:

Headers#

  • PVRScopeStats.h - This is the header file defining the PVRScopeStats functionality.

  • PVRScopeComms.h - This is the header file defining the PVRScopeComms functionality.

Static libraries#

If you link to these, then no additional PVRScope files will be needed at run time.

  • PVRScopeDeveloper.lib (or PVRScopeComplete.lib) on Windows.

  • libPVRScopeDeveloper.a (or libPVRScopeComplete.a) on other OS.

Dynamic libraries#

If you compile-time link to these, then the library will need to be available to your application at load time.

  • PVRScopeDeveloper.lib and PVRScopeDeveloper.dll (or PVRScopeComplete.lib and PVRScopeComplete.dll) on Windows.

  • libPVRScopeDeveloper.so (or libPVRScopeComplete.so) on other OS.

Run-time dynamic libraries#

  • PVRScopeComms.c - If you compile this source file into your application, rather than link to the .a, .lib or .so, then this should transparently handle loading libPVRScopeDeveloper.so or PVRScopeDeveloper.dll (or libPVRScopeComplete.so or PVRScopeComplete.dll) dynamically at run time, which gives the advantage that PVRScope will work if the library is present, or work but do nothing if the library is missing (rather than failing to load, if the app had been linked to the .so or .dll).

Library Compatibility#

PVRScope libraries installed on Windows machines are only tested to function with Visual Studio 2019 and later versions.

PVRScopeStats Limitations#

PVRScopeStats has a few limitations:

  • Only one instance of PVRScopeStats may communicate with PVRScopeServices (a driver library) at any given time. If a PVRScopeStats-enabled application attempts to communicate with PVRScopeServices at the same time as another such application, or at the same time as PVRPerfServer, conflicts can occur that may make performance data unreliable. In this case, PVRPerfServer can be run with the -disable-hwperf flag.

  • Performance counters can only be read on devices whose drivers have been built with hardware profiling enabled. This configuration is the default in most production drivers due to negligible overhead.

  • Performance counters contain the average value of that counter from the last time the counter was queried.

  • PVRScopeStats is not re-entrant. Ensure that only a single thread calls into PVRScope at any point in time in a multi-threaded application.

PVRScopeComms Limitations#

PVRScopeComms also has a small number of limitations:

  • PVRPerfServer must be running on the host device as an intermediary between a PVRScopeComms-enabled application and PVRTune.

  • The available data types for remotely editable library items are: bool, enum, float, int, and string.

  • Multithreading:

    • PVRScopeComms is re-entrant only if the SSPSCommsData pointer is unique per thread that is simultaneously executing inside a PVRScope function.

    • If a single pointer is used (perhaps protected via locks) then everything will work except if custom timing data is sent, as the activity of each thread would then be garbled together.

    • Depending on the requirements, a single pointer could be a good choice for custom counters and a remotely editable library.

    • For marks and custom timing data, a common solution is for each thread to call pplInitialise to create a connection, meaning that each can submit custom timing data, and have each show up as a parallel timeline in the PVRTune GUI. If a thread pool is in use, another solution could be to create a connection per “job”, leading to the PVRTune GUI showing a timeline per job rather than per thread.