Open topic with navigation

Quickstart Guide

Introduction

This quickstart guide is designed to assist a new user in configuring PerfHUD ES to profile applications on a Tegra device.

PerfHUD ES enables experimentation and in-depth analysis of OpenGL ES applications. Through data provided by the OpenGL ES driver and the Tegra SoC, developers are provided live system status, including GPU performance and bottleneck information. This can help target optimizations where they are most needed.

The debugging capabilities of PerfHUD ES give full access to the state of the OpenGL ES pipeline, related textures and shaders, and all rendering states. By doing so, the developer is able to find the causes for improper setup, rendering anomalies, and performance issues.

Note that all downloads are available on the Tegra Developer's site:

http://developer.nvidia.com/tegra-resources

System Requirements

Host PC

• Minimum 2GHz CPU with 2GB RAM or more.
• An OpenGL 1.5 or better GPU (if you have an NVIDIA GeForce 6 series GPU or higher, that should suffice).
  The PerfHUD ES User Guide installed during this setup process covers specific GPU feature requirements in depth, as certain OpenGL extensions are necessary for the host PC to visualize the graphics rendered on the Tegra device.
• An available USB port for flashing your Tegra device and for connecting through Android ADB.
• OS Support:
  • Windows: Windows XP, Windows Vista, Windows 7, and Windows 8 (both 32-bit and 64-bit versions).
  • Mac: Recent OS X 10.6 has been tested. Prior OS X versions may work, but have not been verified. Note that flashing is not available on OSX.
  • Linux: Ubuntu 10.04 has been tested, but other Debian operating systems may also work.
• Ethernet connection to the Tegra device from the host PC, specifically with an IP address on the Tegra device that is reachable from the host. Options include:
  • A crossover network cable for direct host-to-device connections (for host with extra Ethernet port, and device with wired Ethernet port).
  • Wired Ethernet hub/router with both on the same LAN (for host and/or target with wired Ethernet port).
  • Wireless Ethernet AP/router (for target and/or host as available).

  Further detailed network setup instructions are outside the scope of this document.

Tegra Device OS

• Android: A recent Tegra Android OS image which has PerfHUD support.
• Linux: A recent Tegra LDK or Linux OS with PerfHUD ES support. We have tested both the 10.8.2 and 10.9.3 L4T releases (which include support in-pack), and an add-on support pack is available for LDK 10.9.3 (which may work with other releases).

PerfHUD ES Host Installation

Before you begin, make sure the following steps have been completed: 

• The Tegra Android Development Pack has been downloaded and installed for the host operating system that you are using. The installers are available from the Tegra Developer's site.
• The device has been flashed, booted, and is currently functioning.
  
• You have a program to be analyzed that is ready to run on the device.

Windows Host

The PerfHUD ES launcher shortcut should be added by the installer to the desktop. The PerfHUD ES Host may also be accessed through the start menu at the following location:

Programs\NVIDIA Corporation\NVIDIA PerfHUD ES Tegra

The default installed location will be C:\NVPACK\perfhud_es.

Linux Host

On Linux, the latest NVIDIA drivers for your graphics card should be installed. If this was not done automatically, you can use the following command to install the driver: 

sudo apt-get install nvidia-current 

The PerfHUD ES launcher shortcuts should be added by the installer to the system menu, in one of the following locations: 

• Applications > Programming > NVIDIA PerfHUD ES
• Applications > Graphics > NVIDIA PerfHUD ES

The default installation location is ~/NVPACK/perfhud_es.

PerfHUD ES Target Device Support Setup

Enabling PerfHUD Target Support

1. Kill the target application that you want to connect to PerfHUD ES.
2. Open a command prompt and run the following command: adb shell setprop debug.perfhudes 1
3. Note that you must re-enable PerfHUD ES every time you reboot your device.

Disabling PerfHUD Target Support

1. Kill the target application that you want to connect to PerfHUD ES.
2. Open a command prompt and run the following command: adb shell setprop debug.perfhudes 0
   
   

LDK Device Setup

Install PerfHUD ES Support Pack

At this time, LDK customers will need the tegra_linux_perfhud_10.8_10.9.tgz support pack for this next step – if you don’t already have it, please contact your support representative.

Copy the archive to the Tegra device (either copy to boot media from a host Linux PC, or use a remote file transfer like SCP). Then, simply unpack it on-device using a remote shell, using the following syntax:

tar -xzvf tegra_linux_perfhud_10.8_10.9.tgz

If you execute ls, you should see find now have perfhud.sh, as well as two PerfHUD libraries (.so files). The first time you run the perfhud.sh script, it will detect if the libraries are missing from the system, and attempt to install them properly (moving them to /usr/lib).

Note: If you are using the L4T 10.8.2 pack or later, you can skip this step and go directly to the “Enable or Disable PerfHUD Target Support” section below.

Enable or Disable PerfHUD Target Support

To enable PerfHUD support, open a command shell to the device. From the default user home directory, execute:

./perfhud.sh on

If you later want to turn off PerfHUD support for performance or compatibility reasons, simply execute:

./perfhud.sh off

Note that you must re-enable PerfHUD ES after the device has been rebooted.

Connect to the Target Device

Enable PerfHUD support on the target device (detailed above), then follow the steps outlined in this section.

Start the Target Application

Launch the application to be profiled on the Tegra device. The following should be displayed in the log output (remote shell on a Linux device, or adb logcat on an Android device):

NVPerfHUD ES is active.
Communication layer init succeed, listen on port 7876.

This indicates the PerfHUD support code is running and waiting for the host app to connect.

Start PerfHUD ES Host

Run the PerfHUD ES Host program on your host PC. You will then be prompted with a dialog requesting the Target device’s IP address.

Connect to Target over TCP/IP

If you are running just a single application, in a non-GLES-accelerated window manager:

1. Enter the IP address for your target into the PerfHUD ES Host dialog.
2. Click Connect.

If you are running multiple GLES applications simultaneously on the target, or a window manager that also leverages OpenGL ES in addition to applications, you’ll need to use the following steps:

1. Enter the IP address for your target into the PerfHUD ES Host dialog.
2. Click Refresh.
3. Select your application from the process list.
4. Click Connect.
   

Note that when there’s only a single GLES application running, if you quit the application and then start it (or another GLES app) without exiting the PerfHUD ES Host, the Host will automatically re-establish a connection to the new app instance on the same target and port without user intervention. This is useful for repeated test runs as you find and fix issues.

Connect to Android Target Using ADB

If ADB exists on your host system, then the PerfHUD ES Host will automatically attempt to connect to running applications on the target device using ADB. Note that if you have problems with ADB port forwarding, you may need to check that a local firewall is not blocking the port.

NVIDIA® GameWorks™ Documentation Rev. 1.0.211026 ©2014-2021. NVIDIA Corporation and affiliates. All Rights Reserved.