1Flatland is a benchmark for measuring GPU performance in various 2D UI 2rendering and window compositing scenarios. It is designed to be used early 3in the device development process to evaluate GPU hardware (e.g. for SoC 4selection). It uses OpenGL ES 2.0, gralloc, and the Android explicit 5synchronization framework, so it can only be run on devices with drivers 6supporting those HALs. 7 8 9Preparing a Device 10 11Because it's measuring hardware performance, flatland should be run in as 12consistent and static an environment as possible. The display should be 13turned off and background services should be stopped before running the 14benchmark. Running 'adb shell stop' after turning off the display is probably 15sufficient for this, but if there are device- specific background services 16that consume much CPU cycles, memory bandwidth, or might otherwise interfere 17with GPU rendering, those should be stopped as well (and ideally they'd be 18fixed or eliminated for production devices). 19 20Additionally, all relevant hardware clocks should be locked at a particular 21frequency when running flatland. At a minimum this includes the CPU, GPU, and 22memory bus clocks. Running flatland with dynamic clocking essentially 23measures the behavior of the dynamic clocking algorithm under a fairly 24unrealistic workload, and will likely result in unstable and useless results. 25 26If running the benchmark with the clocks locked causes thermal issues, the -s 27command line option can be used to insert a sleep (specified in milliseconds) 28in between each benchmark sample run. Regardless of the scenario being 29measured, each sample measurement runs for between 50 and 200 ms, so a sleep 30time between 10 and 50 ms should address most thermal problems. 31 32 33Interpreting the Output 34 35The output of flatland should look something like this: 36 37 cmdline: flatland 38 Scenario | Resolution | Time (ms) 39 16:10 Single Static Window | 1280 x 800 | fast 40 16:10 Single Static Window | 2560 x 1600 | 5.368 41 16:10 Single Static Window | 3840 x 2400 | 11.979 42 16:10 App -> Home Transition | 1280 x 800 | 4.069 43 16:10 App -> Home Transition | 2560 x 1600 | 15.911 44 16:10 App -> Home Transition | 3840 x 2400 | 38.795 45 16:10 SurfaceView -> Home Transition | 1280 x 800 | 5.387 46 16:10 SurfaceView -> Home Transition | 2560 x 1600 | 21.147 47 16:10 SurfaceView -> Home Transition | 3840 x 2400 | slow 48 49The first column is simply a description of the scenario that's being 50simulated. The second column indicates the resolution at which the scenario 51was measured. The third column is the measured benchmark result. It 52indicates the expected time in milliseconds that a single frame of the 53scenario takes to complete. 54 55The third column may also contain one of three other values: 56 57 fast - This indicates that frames of the scenario completed too fast to be 58 reliably benchmarked. This corresponds to a frame time less than 3 ms. 59 Rather than spending time trying (and likely failing) to get a stable 60 result, the scenario was skipped. 61 62 slow - This indicates that frames of the scenario took too long to 63 complete. This corresponds to a frame time over 50 ms. Rather than 64 simulating a scenario that is obviously impractical on this device, the 65 scenario was skipped. 66 67 varies - This indicates that the scenario was measured, but it did not 68 yield a stable result. Occasionally this happens with an otherwise stable 69 scenario. In this case, simply rerunning flatland should yield a valid 70 result. If a scenario repeatedly results in a 'varies' output, that 71 probably indicates that something is wrong with the environment in which 72 flatland is being run. Check that the hardware clock frequencies are 73 locked and that no heavy-weight services / daemons are running in the 74 background. 75