MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Using swaplogger

The swaplogger tool measures application frame update/drawing rate. For GL applications FPS (frames per second) is measured by timing GL SwapBuffers calls that are made after each frame is completed, for non-GL applications FPS is deduced from image copy operations. SwapBuffers based FPS values are usually reliable, whereas the reliability of image copy based FPS values depend on the actions of the application.

As swaplogger uses LD_PRELOAD to track the functions signifying frame completion, you need to restart the application with it.

Packages

source: swaplogger

binary: swaplogger

Installing swaplogger on the Harmattan device

Install swaplogger through the developer mode applet.

Prerequisite: Developer mode must be enabled.

  1. Select Settings > Security > Developer mode.
  2. Install the Performance bundle package by clicking Install.
  3. You get a notification screen that lists all the applications to be installed in the bundle package. To install, click OK.
  4. A dependency notice appears. Click Accept.

For more information on developer mode and installable tools, see Activating developer mode.

Using the swaplogger tool with the Instrumentation Dashboard

Instrumentation Dashboard is an extension to Qt Creator that provides data gathering and visualisation features.

Precondition:

Instrumentation Dashboard has been installed and connected to the Harmattan device. For instructions, see Using Instrumentation Dashboard.

The swaplogger user interface contains the following views:

  • Dump View: The Dump view displays the terminal output.
  • Frame Duration View: Frame Duration view provides a visual representation of average frame per second.
  • AFPS_N View: Provides a visual representation of Average FPS in previous N frames.

Tool settings

To invoke the settings window, click the Settings button file:Instr_dashb_strace.settings.png in the tool bar. The options for running swaplogger are as follows:

  • -q -- Quiet operation; don't print info for every frame
  • -i -- Enable interactive mode (press 'h' for help)
  • -p N -- Set number of frames for calculating moving average FPS
  • -w -- Show results without rounding
  • -g -- Show swap geometry
  • --only-x -- Count only XSHMPutImage call as a frame
  • --only-egl -- Count only eglSwapBuffers call as a frame
  • --only-dmg -- Count only XDamage events as a frame
  • -v -- verbose mode: print unabbreviated argv, stat, termio[s], etc. args
  • -x -- print non-ascii strings in hex, -xx -- print all strings in hex
  • -a column -- alignment COLUMN for printing syscall results (default 40)
  • -e expr -- a qualifying expression: option=[!]all or option=[!]val1[,val2]...
  • -o file -- send trace output to FILE instead of stderr
  • -O overhead -- set overhead for tracing syscalls to OVERHEAD usecs
  • -s strsize -- limit length of print strings to STRSIZE chars (default 32)
  • -S sortby -- sort syscall counts by: time, calls, name, nothing (default time)


The following table presents the fields in the output generated by the tool:

Output fields of swaplogger
Field Description
source Component that triggered the swap (EGL, XSHM, XDMG)
frame Frame number since program start or reset
dur Duration of current frame in milliseconds
ifps Instantaneous FPS (frames per second) for current frame
min Minimum FPS since start or reset
max Maximum FPS since start or reset
afps_N Average FPS in previous N frames
afps Average FPS since start or reset

Using the swaplogger visualisation

To get the swaplogger data in a visual format, follow these steps:

  1. Click Tools in the Instrumentation Dashboard top menu bar and select strace.
  2. Select Select Target App in tool bar. The Target Application Selector window opens.
  3. Enter the Executable path, for example /opt/apnews/bin/apnews and click OK.
  4. Click Start on the tool bar. This launches the AP Mobile application on the device and starts updating the Dump View, Frame duration View and AFPS_N View in the Intrumentation Dashboard window.
    swaplogger visualisation
  5. After the required data is collected, click Stop.
  6. Use the different views to analyse the aquired data. You can select the required view using the Views menu at any time.

The following table presents the button elements in the example figure.

Element in the example figure Description
Opens the Target Application Selector window. The button is disabled if an application is running.
Start button launches the application on Harmattan device and shows the collected XDMG, EGL or XShmPutImage information in dump, frame duration and AFPS_N view. The button is disabled if no application has been specified, or when an application is already running.
Stop button stops the collecting of application profiling data and stops updating the visualisations. The button is disabled if the application is not running.
Settings button launches the swaplogger settings window.
Slider controls the number of lines the dump view stores. The minimum value is 500 and the maximum value is 9000.
The Clear button clears the content of the dump view.
The Save button saves the dump view data to a persistent file system.
Help button launches the tool help.

Using the tool on the Harmattan device

For more detailed instructions for using the tool, enter the following command:

swaplogger -h 

Note: To use this tool with the developer account, run the swaplogger tool with the aegis-exec command. For example:

 aegis-exec -u user swaplogger -i <process> <options for the process>

Starting swaplogger

To start swaplogger, use the following option:

 $ swaplogger -i <process> <options for the process>

See Tool settings for the swaplogger output fields.

Measuring FPS of applications with a status bar

If an application shows a status bar, its charging animation can cause application FPS fluctuations. To prevent sysuid from updating the application status bar contents, stop it temporarily. Enter the following command:

 killall -STOP sysuid

After the tool has taken the measurements, enter the following command:

 killall -CONT sysuid