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 performanec 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:

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

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

  • PVRScopeDeveloper.lib - This is the PVRScope library file (can also be PVRScopeComplete.lib).

In order to use PVRScope functionality, a project must include the relevant header file and link against PVRScopeDeveloper.lib.

Library Compatibility

Currently, PVRScope libraries installed on Windows machines only function with Visual Studio 2010 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 pplInitialie 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.