display-tool - Display Driver Testing & Verification Tool

Command-line testing utility for Fuchsia display drivers.

Overview & Architecture

The tool's design prioritizes minimizing the System Under Test (SUT) size.

Key decisions:

• Use the fuchsia.hardware.display/Coordinator FIDL interface directly.
• Use the testing client priority, so the tool takes over the display from any active product session.

Build configuration

display-tool is included in the tools bundle for the display drivers stack.

fx add-test //src/graphics/display:tools

If you‘re iterating on the tool, include the display drivers’ tests bundle.

fx add-test //src/graphics/display:tests

Use balanced or release builds for frame rate testing. The current scene rendering logic can bottleneck the CPU in debug.

Running

Recommended method:

ffx target ssh -- display-tool <command> [options]

To terminate continuous animation or vsync monitoring commands, send SIGINT (Ctrl+C).

Intended use for display testing

Step 1: Display detection and timings

Test that the display drivers detect connected panels and register the correct display modes and pixel formats.

ffx target ssh -- display-tool info

Verification

Add the --fidl flag to inspect the raw FIDL structure.

Checklist:

• At least one display is reported.
• Reported resolution matches the panel or emulator specifications.
• Supported pixel formats include expected types.
• Vertical refresh rates match specifications. Example: 60000 mHz (in millihertz) for 60 Hz.

Step 2: One solid color fill layer

Test the driver's ability to handle solid color fill layers. This test does not depend on Sysmem integration or IOMMU configuration.

ffx target ssh -- display-tool color --color ff0000

Verification

• The display is filled with the requested color. Example: ff0000 is pure red.
• The terminal outputs live refresh rate statistics: Display 1 config is applied, refresh rate 60.00 Hz (16.66667 ms)
• Vsync events arrive at a steady rate.

Step 3: One image layer

Test that the display driver integrates with Sysmem and manages its IOMMU correctly.

ffx target ssh -- display-tool vsync --color 00ff00 --pixel-format bgra32

Verification

• The display is filled with the chosen color. Example: 00ff00 is pure green.
• The terminal shows a stable VSync frequency. No dropped event warnings.
• System logs do not include any Sysmem buffer negotiation constraint errors.

Step 4: Swapchain with double-buffering

Test that the display driver submits a sequence of display configurations correctly to the hardware.

ffx target ssh -- display-tool squares

Expected visuals

Four colored squares animate and bounce off the display borders against a black background.

• Orange square (#ff6400): starts at top-left
• Fuchsia square (#ff00ff): starts at top-right
• Green square (#64ff00): starts at bottom-left
• Blue square (#0064ff): starts at bottom-right

Verification

• Smooth animation. No screen tearing, jitter, or display corruption.
• The terminal outputs continuous FPS updates matching the display refresh rate. Example: Display 60.00 fps (16.66667 ms).

Step 5: Display compositing (multiple layers)

Test the display engine driver's support for multi-layer hardware composition, layer z-ordering, and hardware alpha blending modes.

ffx target ssh -- display-tool multilayer-squares

Expected visuals

• Bottom layer: Bouncing fuchsia square (#ff00ff), four times as large as the smaller squares described below. Fully opaque (alpha blending disabled).
• Top layer: Three bouncing squares. Premultiplied alpha blending.
  • Orange square (#ff6400): opaque
  • Green square (#64ff00): semi-transparent (alpha set to 150)
  • Blue square (#0064ff): opaque

Verification

• The semi-transparent green square blends correctly with the bottom layer.
• Opaque areas in the top layer properly occlude the bottom layer.
• The terminal outputs a steady frame rate.

Step 6: Frame rate

Test that the display engine does not drop or skip committed frames.

ffx target ssh -- display-tool frame-rate-test

Expected visuals

10x6 rectangular grid. A single colored cell traverses every grid location sequentially following a continuous Hamiltonian cycle.

Cell color:

• First loop frame: Blue (#0000ff).
• Intermediate frames: White (#ffffff).
• Final frame of loop: Red (#ff0000).

Verification

• The terminal outputs the selected display mode rate. Example: Expected frame rate: 60.000 fps.
• The moving cell advances smoothly by exactly one position per frame. No skipped cells. No stuttering.