Skip to contentSkip to conversation

drm: kernel-doc stuff

PATCH In review Sam Ravnborg 6 participants 13 messages Apr 6, 2020 – Apr 7, 2020

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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

#1 lore raw

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

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 +53 -0
index bcf346b3e486..9633092c9ad5 100644
@@ -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
Reviewed-by on v2 1/3
#2 lore raw

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/#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

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
index bcf346b3e486..9633092c9ad5 100644

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
maintainer Acked-by on v2 1/3
#3 lore raw

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

In reply to Sam Ravnborg

Am 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/#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

Quoted 9 lines
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
index bcf346b3e486..9633092c9ad5 100644
@@ -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

#4 lore raw

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

In reply to Sam Ravnborg

Hi 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/#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

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
index bcf346b3e486..9633092c9ad5 100644
@@ -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-devel
Reviewed-by on v2 1/3
#5 lore raw

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

In reply to Sam Ravnborg
Quoted 39 lines · Sam Ravnborg

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

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
index bcf346b3e486..9633092c9ad5 100644
@@ -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

#6 lore raw

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/#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

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
index bcf346b3e486..9633092c9ad5 100644
@@ -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

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

#7 lore raw

PATCH v2 2/3 drm: writeback: document callbacks

In reply to Sam Ravnborg

Document 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)

Cc Laurent Pinchart <[email protected]>
Cc Liviu Dudau <[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]>
---
 include/drm/drm_modeset_helper_vtables.h | 27 ++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
include/drm/drm_modeset_helper_vtables.h +27 -0
index 7c20b1c8b6a7..421a30f08463 100644
@@ -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
Reviewed-by on v2 2/3
#8 lore raw

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_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)

Quoted 5 lines

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
index 7c20b1c8b6a7..421a30f08463 100644
@@ -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-devel
author Applied
#9 lore raw

Re: [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_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)

Quoted 7 lines
Quoted 5 lines

Thanks, applied to drm-misc-next and pushed out.

Sam

Quoted 48 lines

Thanks!
Liviu

Quoted 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
index 7c20b1c8b6a7..421a30f08463 100644
@@ -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.1
Signature · 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

#10 lore raw

PATCH v2 3/3 drm/writeback: wire drm_writeback.h to kernel-doc

In reply to Sam Ravnborg

drm_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.

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]>
---
 Documentation/gpu/drm-kms.rst | 3 +++
 include/drm/drm_writeback.h   | 9 +++++++++
 2 files changed, 12 insertions(+)
Documentation/gpu/drm-kms.rst +3 -0
index e1f685015807..397314d08f77 100644
@@ -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
index 777c14c847f0..9697d2714d2a 100644
@@ -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
Reviewed-by on v2 3/3
#11 lore raw

Re: [PATCH v2 3/3] drm/writeback: wire drm_writeback.h to kernel-doc

Quoted 7 lines · Sam Ravnborg

drm_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.

Quoted 8 lines
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
index e1f685015807..397314d08f77 100644
@@ -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
index 777c14c847f0..9697d2714d2a 100644
@@ -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
#12 lore raw

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.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.

Quoted 8 lines
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

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
index e1f685015807..397314d08f77 100644
@@ -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 +6 -0
index 777c14c847f0..9697d2714d2a 100644
@@ -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.1
Signature · 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