[PATCH v2 1/3] drm/vblank: Add intro to documentation

[Alex Deucher]

On Mon, Apr 6, 2020 at 3:48 PM Sam Ravnborg <sam at ravnborg.org> wrote:
>
> 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
>
> Signed-off-by: Sam Ravnborg <sam at ravnborg.org>
> Co-developed-by: Lyude Paul <lyude at redhat.com>
> Cc: Lyude Paul <lyude at redhat.com>
> Cc: Thomas Zimmermann <tzimmermann at suse.de>
> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> Cc: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
> Cc: Maxime Ripard <mripard at kernel.org>
> Cc: Thomas Zimmermann <tzimmermann at suse.de>
> Cc: David Airlie <airlied at linux.ie>
> ---
>  drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 53 insertions(+)
>
> diff --git a/drivers/gpu/drm/drm_vblank.c b/drivers/gpu/drm/drm_vblank.c
> index bcf346b3e486..9633092c9ad5 100644
> --- a/drivers/gpu/drm/drm_vblank.c
> +++ b/drivers/gpu/drm/drm_vblank.c
> @@ -41,6 +41,59 @@
>  /**
>   * DOC: vblank handling
>   *
> + * From the computer's perspective, every time the monitor displays
> + * a new frame the scanout engine have "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.  Might be worth adding something like
that.  Either way:
Reviewed-by: Alex Deucher <alexander.deucher at amd.com>

> + *
> + * ::
> + *
> + *
> + *    physical →   ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽
> + *    top of      |                                        |
> + *    display     |                                        |
> + *                |               New frame                |
> + *                |                                        |
> + *                |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓|
> + *                |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| ← Scanline, updates
> + *                |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓|   the frame as it
> + *                |                                        |   travels down
> + *                |                                        |   ("scan 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.
> + *
> + * 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.20.1
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel