Skip to contentSkip to conversation

drm: kernel-doc stuff

PATCH Superseded Sam Ravnborg 6 participants 23 messages Mar 28, 2020 – Apr 5, 2020

Subsystems (4)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover drm: kernel-doc stuff

Lyude Paul wrote a nice intro to vblank in the following mail:
https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27

Reading this I managed to spot a glimmer of hope that I one day would understand some of the fuzz around vblank. To let others benefit from the description I went ahead and added the description to drm_vblank.c.

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.

When checking the output with "make htmldocs" I noticed several drm related warnings.
I went ahead a fixed most of them resulting in a few extre patches.

There are some warnings in amdgpu land - I have left
them for the AMD people to figure out:
amdgpu_vm.c:92: warning: Function parameter or member 'vm' not described in 'amdgpu_vm_eviction_lock' amdgpu_xgmi.c:1: warning: no structured comments found
amdgpu_ras.c:1: warning: no structured comments found
amdgpu_dm.h:305: warning: Function parameter or member 'hdcp_workqueue' not described in 'amdgpu_display_manager'

Sam

Sam Ravnborg (6):
drm/vblank: Add intro to documentation
drm/fb: fix kernel-doc in drm_framebuffer.h drm/sched: fix kernel-doc in gpu_scheduler.h
drm: writeback: document callbacks
drm/dp_mst: add kernel-doc for drm_dp_mst_port.fec_capable drm/bridge: fix kernel-doc warning in panel.c

 drivers/gpu/drm/bridge/panel.c           |  1 +
 drivers/gpu/drm/drm_vblank.c             | 15 +++++++++++++++
 include/drm/drm_dp_mst_helper.h          |  4 ++++
 include/drm/drm_framebuffer.h            |  4 ++--
 include/drm/drm_modeset_helper_vtables.h | 31 +++++++++++++++++++++++++++++++
 include/drm/gpu_scheduler.h              |  1 +
 6 files changed, 54 insertions(+), 2 deletions(-)

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#1 lore raw

PATCH 1/6 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.

Cc Lyude Paul <[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 | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
drivers/gpu/drm/drm_vblank.c +15 -0
index bcf346b3e486..95cac22d59d1 100644
@@ -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
Signature · 6 lines
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
maintainer Acked-by on v1 1/6
#2 lore raw

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

Hi Sam and Lyude,

thanks for improving the documentation. Below are a few points that I'd found more understandable. I'm no native speaker, though.

Am 28.03.20 um 14:20 schrieb Sam Ravnborg:

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

Cc Lyude Paul <[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 | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
drivers/gpu/drm/drm_vblank.c +0 -0
index bcf346b3e486..95cac22d59d1 100644

drivers/gpu/drm/drm_vblank.c line 44

Quoted 4 lines
drivers/gpu/drm/drm_vblank.c +1 -0
@@ -41,6 +41,21 @@
 /**
  * DOC: vblank handling
  *
+ * From the perspective of a computer, every time a computer monitor displays

Possibly change from dative case to genitive:

"From the computer's perspective," ...

drivers/gpu/drm/drm_vblank.c line 46

Quoted 2 lines
drivers/gpu/drm/drm_vblank.c +2 -0
+ * 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

s/which/Which

The text changes from third person (the computer) to first person (we're). Makes it harder to read. I'd remove both, "we" and "computer", and speak of display hardware or scanout engine.

drivers/gpu/drm/drm_vblank.c line 47

Quoted 1 line
drivers/gpu/drm/drm_vblank.c +1 -0
+ * referred to as the scanline.

I'd say a scanline is any of them. Maybe say "current scanline"?

drivers/gpu/drm/drm_vblank.c line 48

Quoted 1 line
drivers/gpu/drm/drm_vblank.c +1 -0
+ * Additionally, there's usually a couple of extra scanlines which we

"In addition to the display's visible area, there's usually a couple of extra scanlines that" ...

drivers/gpu/drm/drm_vblank.c line 51

Quoted 3 lines
drivers/gpu/drm/drm_vblank.c +3 -0
+ * 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.

I'd replace vblank with "vertical blanking period." That term is required in the next paragraph.

The time when the hardware operates on these invisible scanlines is referred to as vertical blanking period, or simply vblank.

drivers/gpu/drm/drm_vblank.c line 54

Quoted 3 lines
drivers/gpu/drm/drm_vblank.c +3 -0
+ *
+ * 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

"we" again

drivers/gpu/drm/drm_vblank.c line 61

Quoted 8 lines
drivers/gpu/drm/drm_vblank.c +4 -0
+ * 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

In any case

Best regards
Thomas

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

#3 lore raw

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

Hi Thomas.

Quoted 81 lines · Thomas Zimmermann

Hi Sam and Lyude,

thanks for improving the documentation. Below are a few points that I'd found more understandable. I'm no native speaker, though.

Am 28.03.20 um 14:20 schrieb Sam Ravnborg:

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

Cc Lyude Paul <[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 | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
drivers/gpu/drm/drm_vblank.c +0 -0
index bcf346b3e486..95cac22d59d1 100644

drivers/gpu/drm/drm_vblank.c line 44

Quoted 4 lines
drivers/gpu/drm/drm_vblank.c +1 -0
@@ -41,6 +41,21 @@
 /**
  * DOC: vblank handling
  *
+ * From the perspective of a computer, every time a computer monitor displays

Possibly change from dative case to genitive:

"From the computer's perspective," ...

drivers/gpu/drm/drm_vblank.c line 46

Quoted 2 lines
drivers/gpu/drm/drm_vblank.c +2 -0
+ * 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

s/which/Which

The text changes from third person (the computer) to first person (we're). Makes it harder to read. I'd remove both, "we" and "computer", and speak of display hardware or scanout engine.

drivers/gpu/drm/drm_vblank.c line 47

Quoted 1 line
drivers/gpu/drm/drm_vblank.c +1 -0
+ * referred to as the scanline.

I'd say a scanline is any of them. Maybe say "current scanline"?

drivers/gpu/drm/drm_vblank.c line 48

Quoted 1 line
drivers/gpu/drm/drm_vblank.c +1 -0
+ * Additionally, there's usually a couple of extra scanlines which we

"In addition to the display's visible area, there's usually a couple of extra scanlines that" ...

drivers/gpu/drm/drm_vblank.c line 51

Quoted 3 lines
drivers/gpu/drm/drm_vblank.c +3 -0
+ * 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.

I'd replace vblank with "vertical blanking period." That term is required in the next paragraph.

The time when the hardware operates on these invisible scanlines is referred to as vertical blanking period, or simply vblank.

drivers/gpu/drm/drm_vblank.c line 54

Quoted 3 lines
drivers/gpu/drm/drm_vblank.c +3 -0
+ *
+ * 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

"we" again

drivers/gpu/drm/drm_vblank.c line 61

Quoted 8 lines
drivers/gpu/drm/drm_vblank.c +4 -0
+ * 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
Quoted 3 lines

In any case

Thanks for the detailed feedabck - I have tried to reword it so it better fits the context and have taking into account your suggetions. See other mail for the updated patch.

Sam
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#4 lore raw

PATCH v2 1/6 drm/vblank: Add intro to documentation

In reply to 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)

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 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
drivers/gpu/drm/drm_vblank.c +17 -0
index bcf346b3e486..ec2c2083b186 100644
@@ -41,6 +41,23 @@
 /**
  * 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
+ * (the extra scanlines are sometimes used by HDMI audio and friends).
+ * The period where the extra scanlines are "scanned out" is referred
+ * to as the vertical blanking period (vblank for short).
+ *
+ * On a lot of display hardware, programming needs to take effect during the
+ * vertical blanking period so that settings like gamma, what frame being
+ * scanned 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 period.
+ *
  * 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
#5 lore raw

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

I am glad that my explanation of vblanks made sense! Some comments below on things I think we could improve here

Quoted 2 lines · Sam Ravnborg

Lyude Paul wrote a very good intro to vblank here:

https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27

Quoted 29 lines

Add this to the intro chapter in drm_vblank.c so others can benefit from it too.

v2:
- Reworded to improve readability (Thomas)

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 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
drivers/gpu/drm/drm_vblank.c +0 -0
index bcf346b3e486..ec2c2083b186 100644
@@ -41,6 +41,23 @@
 /**
  * DOC: vblank handling
  *

drivers/gpu/drm/drm_vblank.c line 53

Quoted 10 lines
drivers/gpu/drm/drm_vblank.c +10 -0
+ * 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
+ * (the extra scanlines are sometimes used by HDMI audio and friends).
+ * The period where the extra scanlines are "scanned out" is referred
+ * to as the vertical blanking period (vblank for short).

I'd reword this, starting from "(the extra scanlines…" (I'd also remove the paranthesis):

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.

I'd also add a simple ascii-art diagram here, since this might make a lot more sense to some people if there's a visual reference. Probably something like this (feel free to get a little creative)

⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽
| |
| |
| New frame |
| |
|↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| ← Scanline, updates the
|↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| frame as it travels
| | down (AKA "scans out")
| |
| |
| Old frame |
| |
| |
| |
| |
| | physical bottom of
|⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽| ← display ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ ← vertical blanking
┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ region
------------------------------------------------

Quoted 4 lines
drivers/gpu/drm/drm_vblank.c +2 -0
+ *
+ * On a lot of display hardware, programming needs to take effect during

the
+ * vertical blanking period so that settings like gamma, what frame being

s/what frame being/which frame is being/

Quoted 4 lines

+ * scanned 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 period.

You can just say vblank here, since we already explained what the vertical blanking period is up above.

Alex Deucher pointed out to me that it's probably also worth mentioning that not all hardware actually fires off the vblank interrupt at the start of the vertical blank, depending on the hardware the interrupt could also happen a few scanlines after the start of vblank, a few scanlines before the start, somewhere in the middle, at the end of the vblank, etc.

Other then that, this looks great so far! Feel free to cc me in the respin for this patch and I'll be happy to give my r-b.

Quoted 4 lines

+ *
* 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
#6 lore raw

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

Hi,

just a few more nits below.

Am 30.03.20 um 23:51 schrieb Lyude Paul:

Quoted 81 lines

I am glad that my explanation of vblanks made sense! Some comments below on things I think we could improve here

Quoted 2 lines · Sam Ravnborg

Lyude Paul wrote a very good intro to vblank here:

https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27

Quoted 29 lines

Add this to the intro chapter in drm_vblank.c so others can benefit from it too.

v2:
- Reworded to improve readability (Thomas)

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 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
drivers/gpu/drm/drm_vblank.c +0 -0
index bcf346b3e486..ec2c2083b186 100644
@@ -41,6 +41,23 @@
 /**
  * DOC: vblank handling
  *

drivers/gpu/drm/drm_vblank.c line 53

Quoted 10 lines
drivers/gpu/drm/drm_vblank.c +10 -0
+ * 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
+ * (the extra scanlines are sometimes used by HDMI audio and friends).
+ * The period where the extra scanlines are "scanned out" is referred
+ * to as the vertical blanking period (vblank for short).

I'd reword this, starting from "(the extra scanlines…" (I'd also remove the paranthesis):

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.

I'd also add a simple ascii-art diagram here, since this might make a lot more sense to some people if there's a visual reference. Probably something like this (feel free to get a little creative)

⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽
| |
| |
| New frame |
| |
|↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| ← Scanline, updates the
|↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| frame as it travels
| | down (AKA "scans out")
| |
| |
| Old frame |
| |
| |
| |
| |
| | physical bottom of
|⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽| ← display ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ ← vertical blanking
┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ region
------------------------------------------------

Quoted 6 lines
Quoted 4 lines
drivers/gpu/drm/drm_vblank.c +2 -0
+ *
+ * On a lot of display hardware, programming needs to take effect during

the
+ * vertical blanking period so that settings like gamma, what frame being

s/what frame being/which frame is being/

I still had read it twice in either variant. Maybe:

s/what frame being scanned out/the displayed image buffer

Quoted 2 lines
Quoted 2 lines

+ * scanned out, etc. can be safely changed without showing visual tearing

I think tearing refers specifically to mid-frame buffer flips. Maybe

s/tearing/artifacts

or

s/tearing/distortion

Best regards
Thomas

Quoted 20 lines
Quoted 3 lines

+ * on the screen. In some unforgiving hardware, some of this programming has
+ * to both start and end in the same vblank - vertical blanking period.

You can just say vblank here, since we already explained what the vertical blanking period is up above.

Alex Deucher pointed out to me that it's probably also worth mentioning that not all hardware actually fires off the vblank interrupt at the start of the vertical blank, depending on the hardware the interrupt could also happen a few scanlines after the start of vblank, a few scanlines before the start, somewhere in the middle, at the end of the vblank, etc.

Other then that, this looks great so far! Feel free to cc me in the respin for this patch and I'll be happy to give my r-b.

Quoted 4 lines

+ *
* 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

#7 lore raw

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

In reply to Lyude Paul
Quoted 73 lines · Lyude Paul

I am glad that my explanation of vblanks made sense! Some comments below on things I think we could improve here

Quoted 2 lines · Sam Ravnborg

Lyude Paul wrote a very good intro to vblank here:

https://lore.kernel.org/dri-devel/[email protected]/T/#mce6480be738160e9d07c5d023e88fd78d7a06d27

Quoted 29 lines

Add this to the intro chapter in drm_vblank.c so others can benefit from it too.

v2:
- Reworded to improve readability (Thomas)

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 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
drivers/gpu/drm/drm_vblank.c +0 -0
index bcf346b3e486..ec2c2083b186 100644
@@ -41,6 +41,23 @@
 /**
  * DOC: vblank handling
  *

drivers/gpu/drm/drm_vblank.c line 53

Quoted 10 lines
drivers/gpu/drm/drm_vblank.c +10 -0
+ * 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
+ * (the extra scanlines are sometimes used by HDMI audio and friends).
+ * The period where the extra scanlines are "scanned out" is referred
+ * to as the vertical blanking period (vblank for short).

I'd reword this, starting from "(the extra scanlines…" (I'd also remove the paranthesis):

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.

I'd also add a simple ascii-art diagram here, since this might make a lot more sense to some people if there's a visual reference. Probably something like this (feel free to get a little creative)

⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽
| |
| |
| New frame |
| |
|↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| ← Scanline, updates the
|↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| frame as it travels
| | down (AKA "scans out")
| |
| |
| Old frame |
| |
| |

Quoted 8 lines

| |
| |
| | physical bottom of
|⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽| ← display ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ ← vertical blanking
┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆ region
------------------------------------------------

Oh if we go with a nice asci-art picture, can we please also make a note that top of the frame is where the corrected/high-precision timestamp should match?
-Daniel

Quoted 33 lines
Quoted 4 lines
drivers/gpu/drm/drm_vblank.c +2 -0
+ *
+ * On a lot of display hardware, programming needs to take effect during

the
+ * vertical blanking period so that settings like gamma, what frame being

s/what frame being/which frame is being/

Quoted 4 lines

+ * scanned 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 period.

You can just say vblank here, since we already explained what the vertical blanking period is up above.

Alex Deucher pointed out to me that it's probably also worth mentioning that not all hardware actually fires off the vblank interrupt at the start of the vertical blank, depending on the hardware the interrupt could also happen a few scanlines after the start of vblank, a few scanlines before the start, somewhere in the middle, at the end of the vblank, etc.

Other then that, this looks great so far! Feel free to cc me in the respin for this patch and I'll be happy to give my r-b.

Quoted 4 lines

+ *
* 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 · 3 lines
Cheers,
	Lyude Paul (she/her)
	Associate Software Engineer at Red Hat
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
#8 lore raw

PATCH 2/6 drm/fb: fix kernel-doc in drm_framebuffer.h

In reply to Sam Ravnborg

Fix following warnings:
drm_framebuffer.h:342: warning: Function parameter or member 'block_width' not described in 'drm_afbc_framebuffer' drm_framebuffer.h:342: warning: Function parameter or member 'block_height' not described in 'drm_afbc_framebuffer'

Trivial spelling mistakes.

Fixes 55f7f72753ab ("drm/core: Add drm_afbc_framebuffer and a corresponding helper")
Cc Andrzej Pietrasiewicz <[email protected]>
Cc Emil Velikov <[email protected]>
Cc James Qian Wang <[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]>
Cc Daniel Vetter <[email protected]>
---
 include/drm/drm_framebuffer.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/drm/drm_framebuffer.h +2 -2
index e9f1b0e2968d..b53c0332f040 100644
@@ -308,11 +308,11 @@ struct drm_afbc_framebuffer {
 	 */
 	struct drm_framebuffer base;
 	/**
-	 * @block_widht: width of a single afbc block
+	 * @block_width: width of a single afbc block
 	 */
 	u32 block_width;
 	/**
-	 * @block_widht: height of a single afbc block
+	 * @block_height: height of a single afbc block
 	 */
 	u32 block_height;
 	/**
Signature · 6 lines
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Acked-by on v1 2/6
#9 lore raw

Re: [PATCH v1 2/6] drm/fb: fix kernel-doc in drm_framebuffer.h

W dniu 28.03.2020 o 14:20, Sam Ravnborg pisze:

Quoted 30 lines

Fix following warnings:
drm_framebuffer.h:342: warning: Function parameter or member 'block_width' not described in 'drm_afbc_framebuffer' drm_framebuffer.h:342: warning: Function parameter or member 'block_height' not described in 'drm_afbc_framebuffer'

Trivial spelling mistakes.

Fixes 55f7f72753ab ("drm/core: Add drm_afbc_framebuffer and a corresponding helper")
Cc Andrzej Pietrasiewicz <[email protected]>
Cc Emil Velikov <[email protected]>
Cc James Qian Wang <[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]>
Cc Daniel Vetter <[email protected]>
---
  include/drm/drm_framebuffer.h | 4 ++--
  1 file changed, 2 insertions(+), 2 deletions(-)
include/drm/drm_framebuffer.h +0 -0
index e9f1b0e2968d..b53c0332f040 100644
@@ -308,11 +308,11 @@ struct drm_afbc_framebuffer {
  	 */
  	struct drm_framebuffer base;
  	/**

include/drm/drm_framebuffer.h struct drm_afbc_framebuffer { · line 318

Quoted 10 lines
include/drm/drm_framebuffer.h +2 -2
-	 * @block_widht: width of a single afbc block
+	 * @block_width: width of a single afbc block
  	 */
  	u32 block_width;
  	/**
-	 * @block_widht: height of a single afbc block
+	 * @block_height: height of a single afbc block
  	 */
  	u32 block_height;
  	/**

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#10 lore raw

Re: [PATCH v1 2/6] drm/fb: fix kernel-doc in drm_framebuffer.h

Hi Andrzej

Quoted 10 lines · Andrzej Pietrasiewicz

W dniu 28.03.2020 o 14:20, Sam Ravnborg pisze:

Quoted 9 lines

Fix following warnings:
drm_framebuffer.h:342: warning: Function parameter or member 'block_width' not described in 'drm_afbc_framebuffer' drm_framebuffer.h:342: warning: Function parameter or member 'block_height' not described in 'drm_afbc_framebuffer'

Trivial spelling mistakes.

Fixes 55f7f72753ab ("drm/core: Add drm_afbc_framebuffer and a corresponding helper")
Cc Andrzej Pietrasiewicz <[email protected]>

...

Quoted 2 lines

Thanks. Added a-b and applied to drm-misc-next.

Sam

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#11 lore raw

PATCH 3/6 drm/sched: fix kernel-doc in gpu_scheduler.h

In reply to Sam Ravnborg

Fix following warning:
gpu_scheduler.h:103: warning: Function parameter or member 'priority' not described in 'drm_sched_entity'

Cc Nirmoy Das <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
---
 include/drm/gpu_scheduler.h | 1 +
 1 file changed, 1 insertion(+)
include/drm/gpu_scheduler.h +1 -0
index 26b04ff62676..a21b3b92135a 100644
@@ -56,6 +56,7 @@ enum drm_sched_priority {
  *              Jobs from this entity can be scheduled on any scheduler
  *              on this list.
  * @num_sched_list: number of drm_gpu_schedulers in the sched_list.
+ * @priority: priority of the entity
  * @rq_lock: lock to modify the runqueue to which this entity belongs.
  * @job_queue: the list of jobs of this entity.
  * @fence_seq: a linearly increasing seqno incremented with each
Signature · 6 lines
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Acked-by on v1 3/6
#12 lore raw

Re: [PATCH v1 3/6] drm/sched: fix kernel-doc in gpu_scheduler.h

Quoted 7 lines · Sam Ravnborg

Fix following warning:
gpu_scheduler.h:103: warning: Function parameter or member 'priority' not described in 'drm_sched_entity'

Cc Nirmoy Das <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>

Inline struct comments would be really nice here. Otherwise

Quoted 19 lines
---
 include/drm/gpu_scheduler.h | 1 +
 1 file changed, 1 insertion(+)
include/drm/gpu_scheduler.h +1 -0
index 26b04ff62676..a21b3b92135a 100644
@@ -56,6 +56,7 @@ enum drm_sched_priority {
  *              Jobs from this entity can be scheduled on any scheduler
  *              on this list.
  * @num_sched_list: number of drm_gpu_schedulers in the sched_list.
+ * @priority: priority of the entity
  * @rq_lock: lock to modify the runqueue to which this entity belongs.
  * @job_queue: the list of jobs of this entity.
  * @fence_seq: a linearly increasing seqno incremented with each
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
#13 lore raw

Re: [PATCH v1 3/6] drm/sched: fix kernel-doc in gpu_scheduler.h

In reply to Sam Ravnborg
Quoted 10 lines · Sam Ravnborg

Fix following warning:
gpu_scheduler.h:103: warning: Function parameter or member 'priority' not described in 'drm_sched_entity'

Cc Nirmoy Das <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
---
 include/drm/gpu_scheduler.h | 1 +
 1 file changed, 1 insertion(+)

Committed to drm-misc-next

Quoted 15 lines
include/drm/gpu_scheduler.h +1 -0
index 26b04ff62676..a21b3b92135a 100644
@@ -56,6 +56,7 @@ enum drm_sched_priority {
  *              Jobs from this entity can be scheduled on any scheduler
  *              on this list.
  * @num_sched_list: number of drm_gpu_schedulers in the sched_list.
+ * @priority: priority of the entity
  * @rq_lock: lock to modify the runqueue to which this entity belongs.
  * @job_queue: the list of jobs of this entity.
  * @fence_seq: a linearly increasing seqno incremented with each
Signature · 1 line
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#14 lore raw

PATCH 4/6 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.

Addign 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'

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 | 31 ++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
include/drm/drm_modeset_helper_vtables.h +31 -0
index 7c20b1c8b6a7..c51bca1ffec7 100644
@@ -1075,8 +1075,39 @@ 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 cleanup them the same way they can prepare and
+	 * cleanup 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() to avoid a new atomic commit
+	 * helper that would need to be called by all drivers not using
+	 * drm_atomic_helper_commit().
+	 *
+	 * This hook 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 a aborted commit, or when
+	 * the job completes.
+	 *
+	 * This hook 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 v1 4/6
#15 lore raw

Re: [PATCH v1 4/6] drm: writeback: document callbacks

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

Addign 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'

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 | 31 ++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
include/drm/drm_modeset_helper_vtables.h +0 -0
index 7c20b1c8b6a7..c51bca1ffec7 100644

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1079

Quoted 5 lines
include/drm/drm_modeset_helper_vtables.h +2 -0
@@ -1075,8 +1075,39 @@ struct drm_connector_helper_funcs {
 	void (*atomic_commit)(struct drm_connector *connector,
 			      struct drm_connector_state *state);
 
+	/**
+	 * @prepare_writeback_job:

Formatting looks funny, your linebreaks here won't go into the generated html and are a bit unusual. I'd remove them and just flow this as a full paragraph.

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1089

Quoted 10 lines
include/drm/drm_modeset_helper_vtables.h +10 -0
+	 *
+	 * As writeback jobs contain a framebuffer, drivers may need to
+	 * prepare and cleanup them the same way they can prepare and
+	 * cleanup 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() to avoid a new atomic commit
+	 * helper that would need to be called by all drivers not using
+	 * drm_atomic_helper_commit().

I'd delete "to avoid a new ..." until the end of the sentence. That feels more like stuff in the commit message/review than kernel docs for driver writers.

Instead maybe add "... for struct &drm_writeback_connector connectors only." This gives us a nice link to the writeback docs, and makes it clear that this isn't some general prep/cleanup thing. Similar addition below.

Quoted 13 lines
include/drm/drm_modeset_helper_vtables.h +11 -0
+	 *
+	 * This hook 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

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1112

Quoted 10 lines
include/drm/drm_modeset_helper_vtables.h +8 -0
+	 * drm_writeback_cleanup_job() function, invoked both when
+	 * destroying the job as part of a aborted commit, or when
+	 * the job completes.
+	 *
+	 * This hook 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);

With the bikesheds addressed as you see fit:

Also Laurent owes you one, I've been pestering to fill this gap in his docs since forever ...

Cheers, Daniel

Quoted 4 lines
include/drm/drm_modeset_helper_vtables.h +0 -0
 };
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
reviewer Reviewed-by
#16 lore raw

Re: [PATCH v1 4/6] drm: writeback: document callbacks

Hi Sam,

Thank you for the patch.

Quoted 39 lines · Daniel Vetter
Quoted 28 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.

Addign 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'

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 | 31 ++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
include/drm/drm_modeset_helper_vtables.h +0 -0
index 7c20b1c8b6a7..c51bca1ffec7 100644

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1079

Quoted 5 lines
include/drm/drm_modeset_helper_vtables.h +2 -0
@@ -1075,8 +1075,39 @@ struct drm_connector_helper_funcs {
 	void (*atomic_commit)(struct drm_connector *connector,
 			      struct drm_connector_state *state);
 
+	/**
+	 * @prepare_writeback_job:

Formatting looks funny, your linebreaks here won't go into the generated html and are a bit unusual. I'd remove them and just flow this as a full paragraph.

Quoted 3 lines

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1082

Quoted 3 lines
include/drm/drm_modeset_helper_vtables.h +3 -0
+	 *
+	 * As writeback jobs contain a framebuffer, drivers may need to
+	 * prepare and cleanup them the same way they can prepare and

"cleanup them" or "clean them up" ?

Quoted 1 line

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1083

Quoted 1 line
include/drm/drm_modeset_helper_vtables.h +1 -0
+	 * cleanup framebuffers for planes.

This would be "clean up" too.

Quoted 11 lines

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1089

Quoted 6 lines
include/drm/drm_modeset_helper_vtables.h +6 -0
+	 * 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() to avoid a new atomic commit
+	 * helper that would need to be called by all drivers not using
+	 * drm_atomic_helper_commit().

I'd delete "to avoid a new ..." until the end of the sentence. That feels more like stuff in the commit message/review than kernel docs for driver writers.

Quoted 8 lines

Instead maybe add "... for struct &drm_writeback_connector connectors only." This gives us a nice link to the writeback docs, and makes it clear that this isn't some general prep/cleanup thing. Similar addition below.

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1093

Quoted 4 lines
include/drm/drm_modeset_helper_vtables.h +4 -0
+	 *
+	 * This hook is optional.
+	 *
+	 * This callback is used by the atomic modeset helpers.

"hook" or "callback", you decide, but let's be consistent :-) I'd go for "operation" personally as that's what is used above. Same for the cleanup_writeback_job operation below.

Quoted 11 lines

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1104

Quoted 11 lines
include/drm/drm_modeset_helper_vtables.h +9 -0
+	 */
 	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 a aborted commit, or when

s/a aborted/an aborted/

Quoted 11 lines

include/drm/drm_modeset_helper_vtables.h struct drm_connector_helper_funcs { · line 1112

Quoted 8 lines
include/drm/drm_modeset_helper_vtables.h +6 -0
+	 * the job completes.
+	 *
+	 * This hook 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);

With the bikesheds addressed as you see fit:

Quoted 1 line
Quoted 2 lines

Also Laurent owes you one, I've been pestering to fill this gap in his docs since forever ...

I do. Sorry for letting you fix it.

Quoted 1 line
Quoted 1 line
include/drm/drm_modeset_helper_vtables.h +0 -0
 };
Signature · 7 lines
Regards,

Laurent Pinchart
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#17 lore raw

PATCH 5/6 drm/dp_mst: add kernel-doc for drm_dp_mst_port.fec_capable

In reply to Sam Ravnborg

Fix kernel-doc warnings for drm_dp_mst_port.fec_capable.
This fixed the following warning:
drm_dp_mst_helper.h:162: warning: Function parameter or member 'fec_capable' not described in 'drm_dp_mst_port'

Cc David Francis <[email protected]>
Cc Lyude Paul <[email protected]>
Cc Harry Wentland <[email protected]>
Cc Mikita Lipski <[email protected]>
Cc Alex Deucher <[email protected]>
Cc Maarten Lankhorst <[email protected]>
Cc Maxime Ripard <[email protected]>
Cc Thomas Zimmermann <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
---
 include/drm/drm_dp_mst_helper.h | 4 ++++
 1 file changed, 4 insertions(+)
include/drm/drm_dp_mst_helper.h +4 -0
index bf5e65d2303e..d93e628ebc84 100644
@@ -157,6 +157,10 @@ struct drm_dp_mst_port {
 	 */
 	bool has_audio;
 
+	/**
+	 * @fec_capable: bool indicating if FEC can be supported
+	 * up to that point in the MST network.
+	 */
 	bool fec_capable;
 };
 
Signature · 6 lines
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Reviewed-by on v1 5/6
#18 lore raw

Re: [PATCH v1 5/6] drm/dp_mst: add kernel-doc for drm_dp_mst_port.fec_capable

Quoted 26 lines · Sam Ravnborg

Fix kernel-doc warnings for drm_dp_mst_port.fec_capable.
This fixed the following warning:
drm_dp_mst_helper.h:162: warning: Function parameter or member 'fec_capable' not described in 'drm_dp_mst_port'

Cc David Francis <[email protected]>
Cc Lyude Paul <[email protected]>
Cc Harry Wentland <[email protected]>
Cc Mikita Lipski <[email protected]>
Cc Alex Deucher <[email protected]>
Cc Maarten Lankhorst <[email protected]>
Cc Maxime Ripard <[email protected]>
Cc Thomas Zimmermann <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
---
 include/drm/drm_dp_mst_helper.h | 4 ++++
 1 file changed, 4 insertions(+)
include/drm/drm_dp_mst_helper.h +0 -0
index bf5e65d2303e..d93e628ebc84 100644

include/drm/drm_dp_mst_helper.h struct drm_dp_mst_port { · line 162

Quoted 6 lines
include/drm/drm_dp_mst_helper.h +3 -0
@@ -157,6 +157,10 @@ struct drm_dp_mst_port {
 	 */
 	bool has_audio;
 
+	/**
+	 * @fec_capable: bool indicating if FEC can be supported
+	 * up to that point in the MST network.

s/network/topology, but I can just fix that locally and push this in just a moment. Thanks!

Quoted 4 lines
include/drm/drm_dp_mst_helper.h +1 -0
+	 */
 	bool fec_capable;
 };
 
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
#19 lore raw

Re: [PATCH v1 5/6] drm/dp_mst: add kernel-doc for drm_dp_mst_port.fec_capable

Hi Lyude.

Quoted 30 lines · Lyude Paul
Quoted 29 lines · Sam Ravnborg

Fix kernel-doc warnings for drm_dp_mst_port.fec_capable.
This fixed the following warning:
drm_dp_mst_helper.h:162: warning: Function parameter or member 'fec_capable' not described in 'drm_dp_mst_port'

Cc David Francis <[email protected]>
Cc Lyude Paul <[email protected]>
Cc Harry Wentland <[email protected]>
Cc Mikita Lipski <[email protected]>
Cc Alex Deucher <[email protected]>
Cc Maarten Lankhorst <[email protected]>
Cc Maxime Ripard <[email protected]>
Cc Thomas Zimmermann <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
---
 include/drm/drm_dp_mst_helper.h | 4 ++++
 1 file changed, 4 insertions(+)
include/drm/drm_dp_mst_helper.h +0 -0
index bf5e65d2303e..d93e628ebc84 100644
@@ -157,6 +157,10 @@ struct drm_dp_mst_port {
 	 */
 	bool has_audio;
 
Quoted 8 lines

include/drm/drm_dp_mst_helper.h struct drm_dp_mst_port { · line 162

Quoted 3 lines
include/drm/drm_dp_mst_helper.h +3 -0
+	/**
+	 * @fec_capable: bool indicating if FEC can be supported
+	 * up to that point in the MST network.

s/network/topology, but I can just fix that locally and push this in just a moment. Thanks!

Thanks for fixing and applying!

Can you also take a look at PATCH 1/6 and if OK provide your s-o-b that should follow the Co-developed-by: ...
I know the text has seen a few changes but the original source came from you.

Sam
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#20 lore raw

PATCH 6/6 drm/bridge: fix kernel-doc warning in panel.c

In reply to Sam Ravnborg

Add missing documentation to fix following warning:
panel.c:303: warning: Function parameter or member 'bridge' not described in 'drm_panel_bridge_connector'

Cc Laurent Pinchart <[email protected]>
Cc Boris Brezillon <[email protected]>
Cc Mihail Atanassov <[email protected]>
Cc Andrzej Hajda <[email protected]>
Cc Neil Armstrong <[email protected]>
Cc Jonas Karlman <[email protected]>
Cc Jernej Skrabec <[email protected]>
---
 drivers/gpu/drm/bridge/panel.c | 1 +
 1 file changed, 1 insertion(+)
drivers/gpu/drm/bridge/panel.c +1 -0
index 8461ee8304ba..e933f1c47f5d 100644
@@ -311,6 +311,7 @@ EXPORT_SYMBOL(devm_drm_panel_bridge_add_typed);
 
 /**
  * drm_panel_bridge_connector - return the connector for the panel bridge
+ * @bridge: The drm_bridge.
  *
  * drm_panel_bridge creates the connector.
  * This function gives external access to the connector.
Signature · 6 lines
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Reviewed-by on v1 6/6
#21 lore raw

Re: [PATCH v1 6/6] drm/bridge: fix kernel-doc warning in panel.c

Quoted 11 lines · Sam Ravnborg

Add missing documentation to fix following warning:
panel.c:303: warning: Function parameter or member 'bridge' not described in 'drm_panel_bridge_connector'

Cc Laurent Pinchart <[email protected]>
Cc Boris Brezillon <[email protected]>
Cc Mihail Atanassov <[email protected]>
Cc Andrzej Hajda <[email protected]>
Cc Neil Armstrong <[email protected]>
Cc Jonas Karlman <[email protected]>
Cc Jernej Skrabec <[email protected]>
Quoted 19 lines
---
 drivers/gpu/drm/bridge/panel.c | 1 +
 1 file changed, 1 insertion(+)
drivers/gpu/drm/bridge/panel.c +1 -0
index 8461ee8304ba..e933f1c47f5d 100644
@@ -311,6 +311,7 @@ EXPORT_SYMBOL(devm_drm_panel_bridge_add_typed);
 
 /**
  * drm_panel_bridge_connector - return the connector for the panel bridge
+ * @bridge: The drm_bridge.
  *
  * drm_panel_bridge creates the connector.
  * This function gives external access to the 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
#22 lore raw

Re: [PATCH v1 6/6] drm/bridge: fix kernel-doc warning in panel.c

In reply to Sam Ravnborg
Quoted 11 lines · Sam Ravnborg

Add missing documentation to fix following warning:
panel.c:303: warning: Function parameter or member 'bridge' not described in 'drm_panel_bridge_connector'

Cc Laurent Pinchart <[email protected]>
Cc Boris Brezillon <[email protected]>
Cc Mihail Atanassov <[email protected]>
Cc Andrzej Hajda <[email protected]>
Cc Neil Armstrong <[email protected]>
Cc Jonas Karlman <[email protected]>
Cc Jernej Skrabec <[email protected]>
Quoted 3 lines
---
 drivers/gpu/drm/bridge/panel.c | 1 +
 1 file changed, 1 insertion(+)

Committed to drm-misc-next

Quoted 15 lines
drivers/gpu/drm/bridge/panel.c +1 -0
index 8461ee8304ba..e933f1c47f5d 100644
@@ -311,6 +311,7 @@ EXPORT_SYMBOL(devm_drm_panel_bridge_add_typed);
 
 /**
  * drm_panel_bridge_connector - return the connector for the panel bridge
+ * @bridge: The drm_bridge.
  *
  * drm_panel_bridge creates the connector.
  * This function gives external access to the connector.
Signature · 1 line
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel