[PATCH v1 1/6] drm/vblank: Add intro to documentation

From: Sam Ravnborg <sam@ravnborg.org>
To: dri-devel@lists.freedesktop.org, Lyude Paul <lyude@redhat.com>
Cc: Neil Armstrong <narmstrong@baylibre.com>,
	David Airlie <airlied@linux.ie>,
	Liviu Dudau <liviu.dudau@arm.com>,
	Andrzej Hajda <a.hajda@samsung.com>,
	Nirmoy Das <nirmoy.das@amd.com>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Mihail Atanassov <Mihail.Atanassov@arm.com>,
	Sam Ravnborg <sam@ravnborg.org>,
	Emil Velikov <emil.velikov@collabora.com>,
	David Francis <David.Francis@amd.com>,
	James Qian Wang <james.qian.wang@arm.com>,
	Jonas Karlman <jonas@kwiboo.se>,
	Mikita Lipski <mikita.lipski@amd.com>,
	Jernej Skrabec <jernej.skrabec@siol.net>,
	Andrzej Pietrasiewicz <andrzej.p@collabora.com>,
	Boris Brezillon <boris.brezillon@collabora.com>,
	Thomas Zimmermann <tzimmermann@suse.de>,
	Alex Deucher <alexander.deucher@amd.com>
Subject: [PATCH v1 1/6] drm/vblank: Add intro to documentation
Date: Sat, 28 Mar 2020 14:20:20 +0100	[thread overview]
Message-ID: <20200328132025.19910-2-sam@ravnborg.org> (raw)
In-Reply-To: <20200328132025.19910-1-sam@ravnborg.org>

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.

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Co-developed-by: Lyude Paul <lyude@redhat.com>
Cc: Lyude Paul <lyude@redhat.com>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: David Airlie <airlied@linux.ie>
---
 drivers/gpu/drm/drm_vblank.c | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/drivers/gpu/drm/drm_vblank.c b/drivers/gpu/drm/drm_vblank.c
index bcf346b3e486..95cac22d59d1 100644
--- a/drivers/gpu/drm/drm_vblank.c
+++ b/drivers/gpu/drm/drm_vblank.c
@@ -41,6 +41,21 @@
 /**
  * DOC: vblank handling
  *
+ * From the perspective of a computer, every time a computer monitor displays
+ * a new frame it's done by "scanning out" the display image from top to
+ * bottom, one row of pixels at a time. which row of pixels we're on is
+ * referred to as the scanline.
+ * Additionally, there's usually a couple of extra scanlines which we
+ * scan out, but aren't actually displayed on the screen (these sometimes
+ * get used by HDMI audio and friends, but that's another story).
+ * The period where we're on these scanlines is referred to as the vblank.
+ *
+ * On a lot of display hardware, programming needs to take effect during the
+ * vertical blanking period so that settings like gamma, what frame we're
+ * scanning out, etc. can be safely changed without showing visual tearing
+ * on the screen. In some unforgiving hardware, some of this programming has
+ * to both start and end in the same vblank - vertical blanking.
+ *
  * 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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
