drm: kernel-doc stuff
Subsystems (3)
v2 cover drm: kernel-doc stuff
Lyude - I added a "Co-developed-by: ..." Can I get your s-o-b on the patch, to document that you are OK with this to go in.
Needed on top of an r-b.
v2:
- committed acked/reviewed patches
- significantly updated the vbalnk patch based on a lot of good inputs
- updated the writeback patch
- wired drm_writeback.h to kernel-doc
Sam
Sam Ravnborg (3):
drm/vblank: Add intro to documentation
drm: writeback: document callbacks drm/writeback: wire drm_writeback.h to kernel-doc
Documentation/gpu/drm-kms.rst | 3 ++ drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++ include/drm/drm_modeset_helper_vtables.h | 27 ++++++++++++++++ include/drm/drm_writeback.h | 9 ++++++ 4 files changed, 92 insertions(+)
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH v2 1/3 drm/vblank: Add intro to documentation
Lyude Paul wrote a very good intro to vblank here:
https://lore.kernel.org/dri-devel/[email protected]/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
--- drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)
drivers/gpu/drm/drm_vblank.c +53 -0
@@ -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. +* +* :: +* +* +* 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
Signature · 6 lines
2.20.1 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 1/3] drm/vblank: Add intro to documentation
Quoted 34 lines · Sam Ravnborg
Lyude Paul wrote a very good intro to vblank here:
https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27Add this to the intro chapter in
drm_vblank.cso 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 changesSigned-off-by Sam Ravnborg <[email protected]>Co-developed-by Lyude Paul <[email protected]>Cc Lyude Paul <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>--- drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)drivers/gpu/drm/drm_vblank.c +0
-0
drivers/gpu/drm/drm_vblank.c line 46
Quoted 6 lines
drivers/gpu/drm/drm_vblank.c +3
-0@@ -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.
s/have/has/
Other then that:
Quoted 58 lines
drivers/gpu/drm/drm_vblank.c +19
-0+* 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. +* +* :: +* +* +* 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
Signature · 8 lines
Cheers, Lyude Paul (she/her) Associate Software Engineer at Red Hat _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 1/3] drm/vblank: Add intro to documentation
In reply to Sam RavnborgAm 06.04.20 um 21:47 schrieb Sam Ravnborg:
Quoted 16 lines
Lyude Paul wrote a very good intro to vblank here:
https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27Add this to the intro chapter in
drm_vblank.cso 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
Quoted 9 lines
Signed-off-by Sam Ravnborg <[email protected]>Co-developed-by Lyude Paul <[email protected]>Cc Lyude Paul <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>
Quoted 69 lines
--- drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)drivers/gpu/drm/drm_vblank.c +53
-0@@ -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. +* +* :: +* +* +* 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
Signature · 6 lines
Thomas Zimmermann Graphics Driver Developer SUSE Software Solutions Germany GmbH Maxfeldstr. 5, 90409 Nürnberg, Germany (HRB 36809, AG Nürnberg) Geschäftsführer: Felix Imendörffer
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 1/3] drm/vblank: Add intro to documentation
In reply to Sam RavnborgHi Sam,
Sorry for jumping in late on this, I have just a small suggestion:
Quoted 74 lines · Sam Ravnborg
Lyude Paul wrote a very good intro to vblank here:
https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27Add this to the intro chapter in
drm_vblank.cso 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 changesSigned-off-by Sam Ravnborg <[email protected]>Co-developed-by Lyude Paul <[email protected]>Cc Lyude Paul <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>--- drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)drivers/gpu/drm/drm_vblank.c +37
-0@@ -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. +* +* :: +* +* +* 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 → ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽
drivers/gpu/drm/drm_vblank.c line 90
Quoted 10 lines
drivers/gpu/drm/drm_vblank.c +10
-0+* 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 mention of vblank interrupt in the next paragraph seems a bit sudden to me. Maybe you can add at the end of the paragraph above something like:
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.
Quoted 12 lines
drivers/gpu/drm/drm_vblank.c +6
-0+* +* 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 Signature · 1 line
2.20.1
Best regards,
Liviu
Signature · 12 lines
====================
| I would like to |
| fix the world, |
| but they're not |
| giving me the |
\ source code! /
---------------
¯\_(ツ)_/¯
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-develRe: [PATCH v2 1/3] drm/vblank: Add intro to documentation
In reply to Sam RavnborgQuoted 39 lines · Sam Ravnborg
Lyude Paul wrote a very good intro to vblank here:
https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27Add this to the intro chapter in
drm_vblank.cso 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 changesSigned-off-by Sam Ravnborg <[email protected]>Co-developed-by Lyude Paul <[email protected]>Cc Lyude Paul <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>--- drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)drivers/gpu/drm/drm_vblank.c +1
-0@@ -41,6 +41,59 @@/** * DOC: vblank handling * +* From the computer's perspective, every time the monitor displays
drivers/gpu/drm/drm_vblank.c line 54
Quoted 10 lines
drivers/gpu/drm/drm_vblank.c +10
-0+* 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:
Quoted 48 lines
drivers/gpu/drm/drm_vblank.c +42
-1+* +* :: +* +* +* 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
Quoted 4 lines
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 1/3] drm/vblank: Add intro to documentation
Hi Alex.
Quoted 58 lines · Alex Deucher
Quoted 39 lines · Sam Ravnborg
Lyude Paul wrote a very good intro to vblank here:
https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27Add this to the intro chapter in
drm_vblank.cso 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 changesSigned-off-by Sam Ravnborg <[email protected]>Co-developed-by Lyude Paul <[email protected]>Cc Lyude Paul <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>--- drivers/gpu/drm/drm_vblank.c | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)drivers/gpu/drm/drm_vblank.c +1
-0@@ -41,6 +41,59 @@/** * DOC: vblank handling * +* From the computer's perspective, every time the monitor displays drivers/gpu/drm/drm_vblank.c line 54
Quoted 10 lines
drivers/gpu/drm/drm_vblank.c +10
-0+* 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:
Quoted 1 line
Reviewed-by Alex Deucher <[email protected]>
Thanks. Added this nice historical lesson and committed and pushed out.
And to all, thanks for the inputs. We managed to improve this piece of the documetation.
Sam
Quoted 49 lines
Quoted 49 lines
drivers/gpu/drm/drm_vblank.c +42
-1+* +* :: +* +* +* 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
Quoted 4 lines
Quoted 4 lines
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH v2 2/3 drm: writeback: document callbacks
In reply to Sam RavnborgDocument the callbacks:
drm_connector_helper_funcs.prepare_writeback_job drm_connector_helper_funcs.cleanup_writeback_job
The documentation was pulled from the changelong introducing the callbacks, originally written by Laurent.
Adding the missing documentation fixes the following warnings:
drm_modeset_helper_vtables.h:1052: warning: Function parameter or member 'prepare_writeback_job' not described in 'drm_connector_helper_funcs' drm_modeset_helper_vtables.h:1052: warning: Function parameter or member 'cleanup_writeback_job' not described in 'drm_connector_helper_funcs'
v2:
- Fix formatting (Daniel)
- Drop changelog text and add reference (Daniel)
- Improve grammar. and use "operation" (Laurent)
--- include/drm/drm_modeset_helper_vtables.h | 27 ++++++++++++++++++++++++ 1 file changed, 27 insertions(+)
include/drm/drm_modeset_helper_vtables.h +27 -0
@@ -1075,8 +1075,35 @@ struct drm_connector_helper_funcs {void (*atomic_commit)(struct drm_connector *connector,struct drm_connector_state *state); +/** +* @prepare_writeback_job: +* +* As writeback jobs contain a framebuffer, drivers may need to +* prepare and clean them up the same way they can prepare and +* clean up framebuffers for planes. This optional connector operation +* is used to support the preparation of writeback jobs. The job +* prepare operation is called from drm_atomic_helper_prepare_planes() +* for struct &drm_writeback_connector connectors only. +* +* This operation is optional. +* +* This callback is used by the atomic modeset helpers. +*/ int (*prepare_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); +/** +* @cleanup_writeback_job: +* +* This optional connector operation is used to support the +* cleanup of writeback jobs. The job cleanup operation is called +* from the existing drm_writeback_cleanup_job() function, invoked +* both when destroying the job as part of an aborted commit, or when +* the job completes. +* +* This operation is optional. +* +* This callback is used by the atomic modeset helpers. +*/ void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); };
Signature · 6 lines
2.20.1 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 2/3] drm: writeback: document callbacks
Quoted 16 lines · Sam Ravnborg
Document the callbacks:
drm_connector_helper_funcs.prepare_writeback_job drm_connector_helper_funcs.cleanup_writeback_jobThe documentation was pulled from the changelong introducing the callbacks, originally written by Laurent.
Adding the missing documentation fixes the following warnings:
drm_modeset_helper_vtables.h:1052: warning: Function parameter or member 'prepare_writeback_job' not described in 'drm_connector_helper_funcs' drm_modeset_helper_vtables.h:1052: warning: Function parameter or member 'cleanup_writeback_job' not described in 'drm_connector_helper_funcs'v2:
- Fix formatting (Daniel)
- Drop changelog text and add reference (Daniel)
- Improve grammar. and use "operation" (Laurent)
Quoted 5 lines
Signed-off-by Sam Ravnborg <[email protected]>Reviewed-by Daniel Vetter <[email protected]>Reviewed-by Laurent Pinchart <[email protected]>Cc Laurent Pinchart <[email protected]>Cc Liviu Dudau <[email protected]>
Thanks!
Liviu
Quoted 52 lines
Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>--- include/drm/drm_modeset_helper_vtables.h | 27 ++++++++++++++++++++++++ 1 file changed, 27 insertions(+)include/drm/drm_modeset_helper_vtables.h +27
-0@@ -1075,8 +1075,35 @@ struct drm_connector_helper_funcs {void (*atomic_commit)(struct drm_connector *connector,struct drm_connector_state *state); +/** +* @prepare_writeback_job: +* +* As writeback jobs contain a framebuffer, drivers may need to +* prepare and clean them up the same way they can prepare and +* clean up framebuffers for planes. This optional connector operation +* is used to support the preparation of writeback jobs. The job +* prepare operation is called from drm_atomic_helper_prepare_planes() +* for struct &drm_writeback_connector connectors only. +* +* This operation is optional. +* +* This callback is used by the atomic modeset helpers. +*/ int (*prepare_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); +/** +* @cleanup_writeback_job: +* +* This optional connector operation is used to support the +* cleanup of writeback jobs. The job cleanup operation is called +* from the existing drm_writeback_cleanup_job() function, invoked +* both when destroying the job as part of an aborted commit, or when +* the job completes. +* +* This operation is optional. +* +* This callback is used by the atomic modeset helpers. +*/ void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); };Signature · 1 line
2.20.1
Signature · 12 lines
====================
| I would like to |
| fix the world, |
| but they're not |
| giving me the |
\ source code! /
---------------
¯\_(ツ)_/¯
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-develSam Ravnborg
AppliedRe: [PATCH v2 2/3] drm: writeback: document callbacks
Quoted 17 lines · Liviu Dudau
Quoted 16 lines · Sam Ravnborg
Document the callbacks:
drm_connector_helper_funcs.prepare_writeback_job drm_connector_helper_funcs.cleanup_writeback_jobThe documentation was pulled from the changelong introducing the callbacks, originally written by Laurent.
Adding the missing documentation fixes the following warnings:
drm_modeset_helper_vtables.h:1052: warning: Function parameter or member 'prepare_writeback_job' not described in 'drm_connector_helper_funcs' drm_modeset_helper_vtables.h:1052: warning: Function parameter or member 'cleanup_writeback_job' not described in 'drm_connector_helper_funcs'v2:
- Fix formatting (Daniel)
- Drop changelog text and add reference (Daniel)
- Improve grammar. and use "operation" (Laurent)
Quoted 7 lines
Quoted 5 lines
Signed-off-by Sam Ravnborg <[email protected]>Reviewed-by Daniel Vetter <[email protected]>Reviewed-by Laurent Pinchart <[email protected]>Cc Laurent Pinchart <[email protected]>Cc Liviu Dudau <[email protected]>Reviewed-by Liviu Dudau <[email protected]>
Thanks, applied to drm-misc-next and pushed out.
Sam
Quoted 48 lines
Thanks!
LiviuQuoted 44 lines
Cc Daniel Vetter <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>--- include/drm/drm_modeset_helper_vtables.h | 27 ++++++++++++++++++++++++ 1 file changed, 27 insertions(+)include/drm/drm_modeset_helper_vtables.h +25
-0@@ -1075,8 +1075,35 @@ struct drm_connector_helper_funcs {void (*atomic_commit)(struct drm_connector *connector,struct drm_connector_state *state); +/** +* @prepare_writeback_job: +* +* As writeback jobs contain a framebuffer, drivers may need to +* prepare and clean them up the same way they can prepare and +* clean up framebuffers for planes. This optional connector operation +* is used to support the preparation of writeback jobs. The job +* prepare operation is called from drm_atomic_helper_prepare_planes() +* for struct &drm_writeback_connector connectors only. +* +* This operation is optional. +* +* This callback is used by the atomic modeset helpers. +*/ int (*prepare_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); +/** +* @cleanup_writeback_job: +* +* This optional connector operation is used to support the +* cleanup of writeback jobs. The job cleanup operation is called +* from the existing drm_writeback_cleanup_job() function, invoked +* both when destroying the job as part of an aborted commit, or when +* the job completes. +* +* This operation is optional. +*
Quoted 18 lines
Quoted 8 lines
include/drm/drm_modeset_helper_vtables.h +2
-0+* This callback is used by the atomic modeset helpers. +*/ void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,struct drm_writeback_job *job); };Signature · 1 line
2.20.1Signature · 8 lines
==================== | I would like to | | fix the world, | | but they're not | | giving me the | \ source code! / --------------- ¯\_(ツ)_/¯
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH v2 3/3 drm/writeback: wire drm_writeback.h to kernel-doc
In reply to Sam Ravnborgdrm_writeback.h included a lot of nice kernel-doc comments. Wire it up so the header file is included in the kernel-doc generated documentation.
Added a few simple comments to the two structs so they get picked up by kernel-doc.
--- Documentation/gpu/drm-kms.rst | 3 +++ include/drm/drm_writeback.h | 9 +++++++++ 2 files changed, 12 insertions(+)
Documentation/gpu/drm-kms.rst +3 -0
@@ -397,6 +397,9 @@ Connector Functions Reference Writeback Connectors -------------------- +.. kernel-doc:: include/drm/drm_writeback.h + :internal: + .. kernel-doc:: drivers/gpu/drm/drm_writeback.c :doc: overview
include/drm/drm_writeback.h +9 -0
@@ -15,7 +15,13 @@#include <drm/drm_encoder.h> #include <linux/workqueue.h> +/** +* struct drm_writeback_connector - DRM writeback connector +*/ struct drm_writeback_connector { +/** +* @base: base drm_connector object +*/ struct drm_connector base;/**
@@ -78,6 +84,9 @@ struct drm_writeback_connector {char timeline_name[32 ]; }; +/** +* struct drm_writeback_job - DRM writeback job +*/ struct drm_writeback_job {/** * @connector:
Signature · 6 lines
2.20.1 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 3/3] drm/writeback: wire drm_writeback.h to kernel-doc
Quoted 7 lines · Sam Ravnborg
drm_writeback.hincluded a lot of nice kernel-doc comments. Wire it up so the header file is included in the kernel-doc generated documentation.Added a few simple comments to the two structs so they get picked up by kernel-doc.
Quoted 8 lines
Signed-off-by Sam Ravnborg <[email protected]>Cc Laurent Pinchart <[email protected]>Cc Brian Starkey <[email protected]>Cc Liviu Dudau <[email protected]>Cc Daniel Vetter <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc Maxime Ripard <[email protected]>Cc Maxime Ripard <[email protected]>
Quoted 50 lines
--- Documentation/gpu/drm-kms.rst | 3 +++ include/drm/drm_writeback.h | 9 +++++++++ 2 files changed, 12 insertions(+)Documentation/gpu/drm-kms.rst +3
-0@@ -397,6 +397,9 @@ Connector Functions Reference Writeback Connectors -------------------- +.. kernel-doc:: include/drm/drm_writeback.h + :internal: + .. kernel-doc:: drivers/gpu/drm/drm_writeback.c :doc: overviewinclude/drm/drm_writeback.h +9
-0@@ -15,7 +15,13 @@#include <drm/drm_encoder.h> #include <linux/workqueue.h> +/** +* struct drm_writeback_connector - DRM writeback connector +*/ struct drm_writeback_connector { +/** +* @base: base drm_connector object +*/ struct drm_connector base;/** @@ -78,6 +84,9 @@ struct drm_writeback_connector {char timeline_name[32 ]; }; +/** +* struct drm_writeback_job - DRM writeback job +*/ struct drm_writeback_job {/** * @connector: Signature · 1 line
2.20.1
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 3/3] drm/writeback: wire drm_writeback.h to kernel-doc
Quoted 17 lines · Daniel Vetter
Quoted 7 lines · Sam Ravnborg
drm_writeback.hincluded a lot of nice kernel-doc comments. Wire it up so the header file is included in the kernel-doc generated documentation.Added a few simple comments to the two structs so they get picked up by kernel-doc.
Quoted 8 lines
Signed-off-by Sam Ravnborg <[email protected]>Cc Laurent Pinchart <[email protected]>Cc Brian Starkey <[email protected]>Cc Liviu Dudau <[email protected]>Cc Daniel Vetter <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc Maxime Ripard <[email protected]>Cc Maxime Ripard <[email protected]>
Quoted 1 line
Reviewed-by Daniel Vetter <[email protected]>
Thanks. Applied to drm-misc-next and pushed out.
Sam
Quoted 41 lines
Quoted 41 lines
--- Documentation/gpu/drm-kms.rst | 3 +++ include/drm/drm_writeback.h | 9 +++++++++ 2 files changed, 12 insertions(+)Documentation/gpu/drm-kms.rst +3
-0@@ -397,6 +397,9 @@ Connector Functions Reference Writeback Connectors -------------------- +.. kernel-doc:: include/drm/drm_writeback.h + :internal: + .. kernel-doc:: drivers/gpu/drm/drm_writeback.c :doc: overviewinclude/drm/drm_writeback.h +6
-0@@ -15,7 +15,13 @@#include <drm/drm_encoder.h> #include <linux/workqueue.h> +/** +* struct drm_writeback_connector - DRM writeback connector +*/ struct drm_writeback_connector { +/** +* @base: base drm_connector object +*/ struct drm_connector base;/** @@ -78,6 +84,9 @@ struct drm_writeback_connector {char timeline_name[32 ]; };
Quoted 14 lines
Quoted 9 lines
include/drm/drm_writeback.h +3
-0+/** +* struct drm_writeback_job - DRM writeback job +*/ struct drm_writeback_job {/** * @connector: Signature · 1 line
2.20.1Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel