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