Skip to contentSkip to conversation

drm/doc: Remove atomic_state_helper.h from drm-kms-helpers.rst

PATCH In review Sean Paul 2 participants 4 messages May 2, 2019 – May 3, 2019

Subsystems (3)
lore
Share & tools
lore

Sean Paul

author
#0 lore raw

PATCH 1/2 drm/doc: Remove atomic_state_helper.h from drm-kms-helpers.rst

From: Sean Paul <[email protected]>

There are no structured comments in the file, so it generates this warning on compilation:

include/drm/drm_atomic_state_helper.h:1: warning: no structured comments found

Fixes 9ef8a9dc4b21 ("drm: Extract drm_atomic_state_helper.[hc]")
Cc Ville Syrjälä <[email protected]>
Cc Daniel Vetter <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
Cc Maarten Lankhorst <[email protected]>
Cc Maxime Ripard <[email protected]>
Cc Sean Paul <[email protected]>
---
 Documentation/gpu/drm-kms-helpers.rst | 3 ---
 1 file changed, 3 deletions(-)
Documentation/gpu/drm-kms-helpers.rst +0 -3
index 14102ae035dc..e7804a9eef9f 100644
@@ -77,9 +77,6 @@ Atomic State Reset and Initialization
 Atomic State Helper Reference
 -----------------------------
 
-.. kernel-doc:: include/drm/drm_atomic_state_helper.h
-   :internal:
-
 .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
    :export:
 
Signature · 6 lines
Sean Paul, Software Engineer, Google / Chromium OS

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

PATCH 2/2 drm/doc: Document the writeback prepare/cleanup jobs

From: Sean Paul <[email protected]>

These functions were missing documentation.

Fixes the warning:
../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'prepare_writeback_job' not described in 'drm_connector_helper_funcs' ../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'cleanup_writeback_job' not described in 'drm_connector_helper_funcs'

Fixes 9d2230dc1351 ("drm: writeback: Add job prepare and cleanup operations")
Cc Laurent Pinchart <[email protected]>
Cc Liviu Dudau <[email protected]>
Cc Maarten Lankhorst <[email protected]>
Cc Maxime Ripard <[email protected]>
Cc Sean Paul <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
---
 drivers/gpu/drm/drm_writeback.c          | 20 ++++++++++++++++++++
 include/drm/drm_modeset_helper_vtables.h | 20 ++++++++++++++++++++
 2 files changed, 40 insertions(+)
drivers/gpu/drm/drm_writeback.c +20 -0
index 79ac014701c8..ef6f85966546 100644
@@ -258,6 +258,15 @@ int drm_writeback_set_fb(struct drm_connector_state *conn_state,
 	return 0;
 }
 
+/**
+ * drm_writeback_prepare_job - Gives driver a chance to prepare for writeback
+ * @job: The writeback job to be prepared
+ *
+ * This function is called from &drm_atomic_helper_prepare_planes(), and allows
+ * the driver to setup the upcoming writeback job. The job will be
+ * destroyed/cleaned up in &drm_writeback_cleanup_job when the connector state
+ * is destroyed.
+ */
 int drm_writeback_prepare_job(struct drm_writeback_job *job)
 {
 	struct drm_writeback_connector *connector = job->connector;
@@ -310,6 +319,17 @@ void drm_writeback_queue_job(struct drm_writeback_connector *wb_connector,
 }
 EXPORT_SYMBOL(drm_writeback_queue_job);
 
+/**
+ * drm_writeback_cleanup_job - Gives driver a chance to cleanup a writeback job
+ * @job: The writeback job to be cleaned up
+ *
+ * This function is called from &atomic_helper_connector_destroy_state() and
+ * allows the driver to clean up the now finished writeback job.
+ *
+ * Notice the asymmetry from prepare, this is called on destroy to
+ * ensure the job is not destroyed before than the writeback operation
+ * has completed.
+ */
 void drm_writeback_cleanup_job(struct drm_writeback_job *job)
 {
 	struct drm_writeback_connector *connector = job->connector;
include/drm/drm_modeset_helper_vtables.h +20 -0
index 8f3602811eb5..a0017f37ef55 100644
@@ -992,8 +992,28 @@ struct drm_connector_helper_funcs {
 	void (*atomic_commit)(struct drm_connector *connector,
 			      struct drm_connector_state *state);
 
+	/**
+	 * @prepare_writeback_job:
+	 *
+	 * Called from &drm_atomic_helper_prepare_planes(), provides the driver
+	 * a chance to setup things in preparation for a writeback job.
+	 *
+	 * This hook is optional.
+	 */
 	int (*prepare_writeback_job)(struct drm_writeback_connector *connector,
 				     struct drm_writeback_job *job);
+
+	/**
+	 * @cleanup_writeback_job:
+	 *
+	 * Called from &drm_atomic_helper_connector_destroy_state(), and
+	 * provides the driver an opportunity to cleanup the writeback job.
+	 * Notice the asymmetry from prepare, this is called on destroy to
+	 * ensure the job is not destroyed before than the writeback operation
+	 * has completed.
+	 *
+	 * This hook is optional.
+	 */
 	void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,
 				      struct drm_writeback_job *job);
 };
Signature · 6 lines
Sean Paul, Software Engineer, Google / Chromium OS

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

Re: [PATCH 2/2] drm/doc: Document the writeback prepare/cleanup jobs

Quoted 10 lines · Sean Paul

From: Sean Paul <[email protected]>

These functions were missing documentation.

Fixes the warning:
../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'prepare_writeback_job' not described in 'drm_connector_helper_funcs' ../include/drm/drm_modeset_helper_vtables.h:1000: warning: Function parameter or member 'cleanup_writeback_job' not described in 'drm_connector_helper_funcs'

Fixes 9d2230dc1351 ("drm: writeback: Add job prepare and cleanup operations")
Cc Laurent Pinchart <[email protected]>

Oh Laurent didn't type documentation, I'll remember that one :-)

Quoted 19 lines
Cc Liviu Dudau <[email protected]>
Cc Maarten Lankhorst <[email protected]>
Cc Maxime Ripard <[email protected]>
Cc Sean Paul <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
---
 drivers/gpu/drm/drm_writeback.c          | 20 ++++++++++++++++++++
 include/drm/drm_modeset_helper_vtables.h | 20 ++++++++++++++++++++
 2 files changed, 40 insertions(+)
drivers/gpu/drm/drm_writeback.c +0 -0
index 79ac014701c8..ef6f85966546 100644
@@ -258,6 +258,15 @@ int drm_writeback_set_fb(struct drm_connector_state *conn_state,
 	return 0;

drivers/gpu/drm/drm_writeback.c int drm_writeback_set_fb(struct drm_connector_state *conn_state, · line 268

Quoted 10 lines
drivers/gpu/drm/drm_writeback.c +8 -0
 }
 
+/**
+ * drm_writeback_prepare_job - Gives driver a chance to prepare for writeback
+ * @job: The writeback job to be prepared
+ *
+ * This function is called from &drm_atomic_helper_prepare_planes(), and allows
+ * the driver to setup the upcoming writeback job. The job will be
+ * destroyed/cleaned up in &drm_writeback_cleanup_job when the connector state
+ * is destroyed.

This is missing the standard "Returns 0 on success, negative error codes on failures."

Quoted 7 lines
drivers/gpu/drm/drm_writeback.c +1 -0
+ */
 int drm_writeback_prepare_job(struct drm_writeback_job *job)
 {
 	struct drm_writeback_connector *connector = job->connector;
@@ -310,6 +319,17 @@ void drm_writeback_queue_job(struct drm_writeback_connector *wb_connector,
 }
 EXPORT_SYMBOL(drm_writeback_queue_job);

drivers/gpu/drm/drm_writeback.c void drm_writeback_queue_job(struct drm_writeback_connector *wb_connector, · line 330

Quoted 10 lines
drivers/gpu/drm/drm_writeback.c +9 -0
 
+/**
+ * drm_writeback_cleanup_job - Gives driver a chance to cleanup a writeback job
+ * @job: The writeback job to be cleaned up
+ *
+ * This function is called from &atomic_helper_connector_destroy_state() and
+ * allows the driver to clean up the now finished writeback job.
+ *
+ * Notice the asymmetry from prepare, this is called on destroy to
+ * ensure the job is not destroyed before than the writeback operation

s/than// I think.

But I'm not really clear on what exactly the asymmetry is.

Plus it's not only called from destry_state, but also through a worker that's launched by drm_writeback_signal_completion.

I think you're docs here don't reflect reality. But yeah I think there's some asymmetry, as in cleanup_job is always called, even if prepare_job wasn't. Not the greatest interface I think, probably should rename cleanup to release/free. Since that's what it's supposed to do I think.

Quoted 10 lines
drivers/gpu/drm/drm_writeback.c +2 -0
+ * has completed.
+ */
 void drm_writeback_cleanup_job(struct drm_writeback_job *job)
 {
 	struct drm_writeback_connector *connector = job->connector;
include/drm/drm_modeset_helper_vtables.h +0 -0
index 8f3602811eb5..a0017f37ef55 100644

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

Quoted 9 lines
include/drm/drm_modeset_helper_vtables.h +6 -0
@@ -992,8 +992,28 @@ struct drm_connector_helper_funcs {
 	void (*atomic_commit)(struct drm_connector *connector,
 			      struct drm_connector_state *state);
 
+	/**
+	 * @prepare_writeback_job:
+	 *
+	 * Called from &drm_atomic_helper_prepare_planes(), provides the driver
+	 * a chance to setup things in preparation for a writeback job.
+	 *

Missing standard boilerplate about return values.

Quoted 9 lines
include/drm/drm_modeset_helper_vtables.h +7 -0
+	 * This hook is optional.
+	 */
 	int (*prepare_writeback_job)(struct drm_writeback_connector *connector,
 				     struct drm_writeback_job *job);
+
+	/**
+	 * @cleanup_writeback_job:
+	 *
+	 * Called from &drm_atomic_helper_connector_destroy_state(), and

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

Quoted 10 lines
include/drm/drm_modeset_helper_vtables.h +7 -0
+	 * provides the driver an opportunity to cleanup the writeback job.
+	 * Notice the asymmetry from prepare, this is called on destroy to
+	 * ensure the job is not destroyed before than the writeback operation
+	 * has completed.
+	 *
+	 * This hook is optional.
+	 */
 	void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,
 				      struct drm_writeback_job *job);
 };

So I looked through the writeback code some more, and realized that this here is probably more helper code (it's mostly called from helpers, the vfuncs are in helpers), but it's in core code.

I think before we document the details of this we also need to rethink the layering here, atm it looks like someone smashed a penne vertically into our very nice kms core/helper lasagna ... Would be really nice to clean this up too and either make it all core (which feels wrong) or move into helpers (probably needs a writeback_helper.c for this, or we stuff it into drm_atomic_helper.c).

Cheers, Daniel

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
Reviewed-by on v1 1/2
#3 lore raw
In reply to Sean Paul
Quoted 7 lines · Sean Paul

From: Sean Paul <[email protected]>

There are no structured comments in the file, so it generates this warning on compilation:

include/drm/drm_atomic_state_helper.h:1: warning: no structured comments found

Quoted 10 lines
Fixes 9ef8a9dc4b21 ("drm: Extract drm_atomic_state_helper.[hc]")
Cc Ville Syrjälä <[email protected]>
Cc Daniel Vetter <[email protected]>
Cc David Airlie <[email protected]>
Cc Daniel Vetter <[email protected]>
Cc Maarten Lankhorst <[email protected]>
Cc Maxime Ripard <[email protected]>
Cc Sean Paul <[email protected]>
Quoted 21 lines
---
 Documentation/gpu/drm-kms-helpers.rst | 3 ---
 1 file changed, 3 deletions(-)
Documentation/gpu/drm-kms-helpers.rst +0 -3
index 14102ae035dc..e7804a9eef9f 100644
@@ -77,9 +77,6 @@ Atomic State Reset and Initialization
 Atomic State Helper Reference
 -----------------------------
 
-.. kernel-doc:: include/drm/drm_atomic_state_helper.h
-   :internal:
-
 .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
    :export:
 
Signature · 1 line
Sean Paul, Software Engineer, Google / Chromium OS
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