Etna utilities

As you may have noticed I recently pushed a new directory utils to the etna_viv source repository. This directory contains various utilities related to the GPU and driver.

Some of these utilities are mostly useful for debugging the driver itself, others are also useful for optimization of applications using the driver. An overview follows.


This utility provides a live view of the rate of change of the performance counters (profiling information). This is arguably the most useful of the bunch.

Here is an example while getting my ass kicked by the AIs in Quake 3 (update frequency: 1/s, action starts after some time due to loading delays):

The exact meanings of the various performance counters are not publicly documented AFAIK, although a lot can be guessed from the names alone.


viv_info shows the feature bits of all the cores of the GPU. These bits signify to the driver which rendering features are available. This is used to fill in the feature matrix.

Example output for GC860 (terminal can be scrolled with mouse wheel):


This utility shows a live view of all GPU debug registers.

Important: Needs kernel driver compiled with user space register access (gcdREGISTER_ACCESS_FROM_USER=1). This is the case by default with most kernel drivers I've encountered in the wild.

Here is an example while bunny-hopping through E1M1 of Quake 1 (update frequency: 1/s).

In general viv_gpu_top provides a more useful overview. However, the difference is that this tool shows all the debug registers, not just the performance counters returned from the kernel.


viv_registers shows the current state of the GPU mmio registers.

Important: Needs kernel driver compiled with user space register access (gcdREGISTER_ACCESS_FROM_USER=1).

Warning: this utility can result in crashes inside the kernel such as (on ARM),

Unhandled fault: external abort on non-linefetch (0x1028) at 0xfe641000
Internal error: : 1028 [#1] PREEMPT ARM

It appears that the actually accessible registers differ per SoC. When a non-accessible register is loaded, a fault happens. So expect crashes when using this utility.

Example (terminal can be scrolled using mouse wheel):


As you may have guessed from the name, this command resets the GPU. This should be useful if some erroneous input managed to hang it.

Note: this is known to be unreliable with many kernel drivers and can bring the GPU in a state that can only be recovered with a device reboot.

No screencast for this one as it has no output.

Written on September 11, 2013
Filed under