BoardConfig: Add and document vsync phase offset setting

Bug: 10624956
Change-Id: I82def5730f9d09396809d4b8cd2ea44829b21f22

target/board/generic/BoardConfig.mk

@@ -45,6 +45,28 @@ BUILD_EMULATOR_OPENGL := true
 # the GLES renderer disables itself if host GL acceleration isn't available.
 USE_OPENGL_RENDERER := true
 
+# Set the phase offset of the system's vsync event relative to the hardware
+# vsync. The system's vsync event drives Choreographer and SurfaceFlinger's
+# rendering. This value is the number of nanoseconds after the hardware vsync
+# that the system vsync event will occur.
+#
+# This phase offset allows adjustment of the minimum latency from application
+# wake-up (by Choregographer) time to the time at which the resulting window
+# image is displayed.  This value may be either positive (after the HW vsync)
+# or negative (before the HW vsync).  Setting it to 0 will result in a
+# minimum latency of two vsync periods because the app and SurfaceFlinger
+# will run just after the HW vsync.  Setting it to a positive number will
+# result in the minimum latency being:
+#
+#     (2 * VSYNC_PERIOD - (vsyncPhaseOffsetNs % VSYNC_PERIOD))
+#
+# Note that reducing this latency makes it more likely for the applications
+# to not have their window content image ready in time.  When this happens
+# the latency will end up being an additional vsync period, and animations
+# will hiccup.  Therefore, this latency should be tuned somewhat
+# conservatively (or at least with awareness of the trade-off being made).
+VSYNC_EVENT_PHASE_OFFSET_NS := 0
+
 TARGET_USERIMAGES_USE_EXT4 := true
 BOARD_SYSTEMIMAGE_PARTITION_SIZE := 576716800
 BOARD_USERDATAIMAGE_PARTITION_SIZE := 209715200