From 56b165feaf9bf0e3111d814bad0e4a2e11231a9e Mon Sep 17 00:00:00 2001 From: Sam Ravnborg Date: Mon, 6 Apr 2020 21:47:44 +0200 Subject: [PATCH] drm/vblank: Add intro to documentation Lyude Paul wrote a very good intro to vblank here: https://lore.kernel.org/dri-devel/faf63d8a9ed23c16af69762f59d0dca6b2bf085f.camel@redhat.com/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27 Add this to the intro chapter in drm_vblank.c so others can benefit from it too. v2: - Reworded to improve readability (Thomas) v3: - Added nice ascii drawing from Lyude (Lyude) - Added referende to high-precision timestamp (Daniel) - Improved grammar (Thomas) - Combined it all and made kernel-doc happy - Dropped any a-b, r-b do to the amount of changes v4: - Add intro to vblank interrupt (Liviu) - Add historical reference for blanking (Alex) Signed-off-by: Sam Ravnborg Co-developed-by: Lyude Paul Reviewed-by: Lyude Paul Reviewed-by: Alex Deucher Cc: Alex Deucher Cc: Liviu Dudau Cc: Lyude Paul Cc: Thomas Zimmermann Cc: Daniel Vetter Cc: Maarten Lankhorst Cc: Maxime Ripard Cc: David Airlie Link: https://patchwork.freedesktop.org/patch/msgid/20200406194746.26433-2-sam@ravnborg.org --- drivers/gpu/drm/drm_vblank.c | 63 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/drivers/gpu/drm/drm_vblank.c b/drivers/gpu/drm/drm_vblank.c index bcf346b..758bf74 100644 --- a/drivers/gpu/drm/drm_vblank.c +++ b/drivers/gpu/drm/drm_vblank.c @@ -41,6 +41,69 @@ /** * DOC: vblank handling * + * From the computer's perspective, every time the monitor displays + * a new frame the scanout engine has "scanned out" the display image + * from top to bottom, one row of pixels at a time. The current row + * of pixels is referred to as the current scanline. + * + * In addition to the display's visible area, there's usually a couple of + * extra scanlines which aren't actually displayed on the screen. + * These extra scanlines don't contain image data and are occasionally used + * for features like audio and infoframes. The region made up of these + * scanlines is referred to as the vertical blanking region, or vblank for + * short. + * + * For historical reference, the vertical blanking period was designed to + * give the electron gun (on CRTs) enough time to move back to the top of + * the screen to start scanning out the next frame. Similar for horizontal + * blanking periods. They were designed to give the electron gun enough + * time to move back to the other side of the screen to start scanning the + * next scanline. + * + * :: + * + * + * physical → ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ + * top of | | + * display | | + * | New frame | + * | | + * |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| + * |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| ← Scanline, + * |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| updates the + * | | frame as it + * | | travels down + * | | ("sacn out") + * | Old frame | + * | | + * | | + * | | + * | | physical + * | | bottom of + * vertical |⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽| ← display + * blanking ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ + * region → ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ + * ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ + * start of → ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ + * new frame + * + * "Physical top of display" is the reference point for the high-precision/ + * corrected timestamp. + * + * On a lot of display hardware, programming needs to take effect during the + * vertical blanking period so that settings like gamma, the image buffer + * buffer to be scanned out, etc. can safely be changed without showing + * any visual artifacts on the screen. In some unforgiving hardware, some of + * this programming has to both start and end in the same vblank. To help + * with the timing of the hardware programming, an interrupt is usually + * available to notify the driver when it can start the updating of registers. + * The interrupt is in this context named the vblank interrupt. + * + * The vblank interrupt may be fired at different points depending on the + * hardware. Some hardware implementations will fire the interrupt when the + * new frame start, other implementations will fire the interrupt at different + * points in time. + * * Vertical blanking plays a major role in graphics rendering. To achieve * tear-free display, users must synchronize page flips and/or rendering to * vertical blanking. The DRM API offers ioctls to perform page flips -- 2.7.4