[PATCH 0/4] drm: Fix some warnings when building docs

[PATCH 0/4] drm: Fix some warnings when building docs

[Sean Paul]

I noticed these warnings as part of my compile testing and decided to fix them.

There are still a few warnings with the import/export prime helpers. They're
partially documented in drm_prime.c, so suggestions welcome on how to resolve
them without duplication (or perhaps duplication is best in this case).

Sean



Sean Paul (4):
  drm/modes: Fix drm_mode_is_420_only() comment
  drm: Fix warning when building docs for scdc_helper
  gpu/host1x: Remove excess parameter in host1x_subdev_add docs
  drm: Add a few missing descriptions in drm_driver docs

 drivers/gpu/drm/drm_modes.c       |  2 +-
 drivers/gpu/drm/drm_scdc_helper.c |  4 +--
 drivers/gpu/host1x/bus.c          |  1 -
 include/drm/drm_drv.h             | 52 ++++++++++++++++++++++++++++++++++-----
 4 files changed, 49 insertions(+), 10 deletions(-)

-- 
2.14.0.rc0.284.gd933b75aa4-goog

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 1/4] drm/modes: Fix drm_mode_is_420_only() comment

[Sean Paul]

Fixes the following warnings when building docs:
../drivers/gpu/drm/drm_modes.c:1623: warning: No description found for parameter 'display'
../drivers/gpu/drm/drm_modes.c:1623: warning: Excess function parameter 'connector' description in 'drm_mode_is_420_only'

Signed-off-by: Sean Paul <seanpaul@chromium.org>
---
 drivers/gpu/drm/drm_modes.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index d52f0a17a66b..4a3f68a33844 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -1610,7 +1610,7 @@ int drm_mode_convert_umode(struct drm_display_mode *out,
  * drm_mode_is_420_only - if a given videomode can be only supported in YCBCR420
  * output format
  *
- * @connector: drm connector under action.
+ * @display: display under action
  * @mode: video mode to be tested.
  *
  * Returns:
-- 
2.14.0.rc0.284.gd933b75aa4-goog

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 1/4] drm/modes: Fix drm_mode_is_420_only() comment

[Daniel Vetter]

On Thu, Jul 20, 2017 at 01:47:40PM -0400, Sean Paul wrote:
> Fixes the following warnings when building docs:
> ../drivers/gpu/drm/drm_modes.c:1623: warning: No description found for parameter 'display'
> ../drivers/gpu/drm/drm_modes.c:1623: warning: Excess function parameter 'connector' description in 'drm_mode_is_420_only'
> 
> Signed-off-by: Sean Paul <seanpaul@chromium.org>

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> ---
>  drivers/gpu/drm/drm_modes.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
> index d52f0a17a66b..4a3f68a33844 100644
> --- a/drivers/gpu/drm/drm_modes.c
> +++ b/drivers/gpu/drm/drm_modes.c
> @@ -1610,7 +1610,7 @@ int drm_mode_convert_umode(struct drm_display_mode *out,
>   * drm_mode_is_420_only - if a given videomode can be only supported in YCBCR420
>   * output format
>   *
> - * @connector: drm connector under action.
> + * @display: display under action
>   * @mode: video mode to be tested.
>   *
>   * Returns:
> -- 
> 2.14.0.rc0.284.gd933b75aa4-goog
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

RE: [PATCH 1/4] drm/modes: Fix drm_mode_is_420_only() comment

[Sharma, Shashank]

Reviewed-by: Shashank Sharma <shashank.shama@intel.com>

Regards
Shashank

-----Original Message-----
From: dri-devel [mailto:dri-devel-bounces@lists.freedesktop.org] On Behalf Of Sean Paul
Sent: Thursday, July 20, 2017 11:18 PM
To: dri-devel@lists.freedesktop.org
Cc: Vetter, Daniel <daniel.vetter@intel.com>
Subject: [PATCH 1/4] drm/modes: Fix drm_mode_is_420_only() comment

Fixes the following warnings when building docs:
../drivers/gpu/drm/drm_modes.c:1623: warning: No description found for parameter 'display'
../drivers/gpu/drm/drm_modes.c:1623: warning: Excess function parameter 'connector' description in 'drm_mode_is_420_only'

Signed-off-by: Sean Paul <seanpaul@chromium.org>
---
 drivers/gpu/drm/drm_modes.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c index d52f0a17a66b..4a3f68a33844 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -1610,7 +1610,7 @@ int drm_mode_convert_umode(struct drm_display_mode *out,
  * drm_mode_is_420_only - if a given videomode can be only supported in YCBCR420
  * output format
  *
- * @connector: drm connector under action.
+ * @display: display under action
  * @mode: video mode to be tested.
  *
  * Returns:
--
2.14.0.rc0.284.gd933b75aa4-goog

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 2/4] drm: Fix warning when building docs for scdc_helper

[Sean Paul]

Fixes:
../drivers/gpu/drm/drm_scdc_helper.c:203: ERROR: Unexpected indentation.
../drivers/gpu/drm/drm_scdc_helper.c:204: WARNING: Block quote ends without a blank line; unexpected unindent.

Signed-off-by: Sean Paul <seanpaul@chromium.org>
---
 drivers/gpu/drm/drm_scdc_helper.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
index 3cd96a95736d..53a743811298 100644
--- a/drivers/gpu/drm/drm_scdc_helper.c
+++ b/drivers/gpu/drm/drm_scdc_helper.c
@@ -199,9 +199,9 @@ EXPORT_SYMBOL(drm_scdc_set_scrambling);
  * TMDS character rate = The rate at which TMDS characters are transmitted(Mcsc)
  * TMDS bit rate = 10x TMDS character rate
  * As per the spec:
- * TMDS clock rate for pixel clock < 340 MHz = 1x the character rate
+ * TMDS clock rate for pixel clock < 340 MHz = 1x the character rate \
  *	= 1/10 pixel clock rate
- * TMDS clock rate for pixel clock > 340 MHz = 0.25x the character rate
+ * TMDS clock rate for pixel clock > 340 MHz = 0.25x the character rate \
  *	= 1/40 pixel clock rate
  *
  * Writes to the TMDS config register over SCDC channel, and:
-- 
2.14.0.rc0.284.gd933b75aa4-goog

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 2/4] drm: Fix warning when building docs for scdc_helper

[Daniel Vetter]

On Thu, Jul 20, 2017 at 01:47:41PM -0400, Sean Paul wrote:
> Fixes:
> ../drivers/gpu/drm/drm_scdc_helper.c:203: ERROR: Unexpected indentation.
> ../drivers/gpu/drm/drm_scdc_helper.c:204: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> Signed-off-by: Sean Paul <seanpaul@chromium.org>
> ---
>  drivers/gpu/drm/drm_scdc_helper.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
> index 3cd96a95736d..53a743811298 100644
> --- a/drivers/gpu/drm/drm_scdc_helper.c
> +++ b/drivers/gpu/drm/drm_scdc_helper.c
> @@ -199,9 +199,9 @@ EXPORT_SYMBOL(drm_scdc_set_scrambling);
>   * TMDS character rate = The rate at which TMDS characters are transmitted(Mcsc)
>   * TMDS bit rate = 10x TMDS character rate
>   * As per the spec:
> - * TMDS clock rate for pixel clock < 340 MHz = 1x the character rate
> + * TMDS clock rate for pixel clock < 340 MHz = 1x the character rate \
>   *	= 1/10 pixel clock rate
> - * TMDS clock rate for pixel clock > 340 MHz = 0.25x the character rate
> + * TMDS clock rate for pixel clock > 340 MHz = 0.25x the character rate \
>   *	= 1/40 pixel clock rate

Shouldn't we make the entire thing a blockquote? I.e. indent plus on its
own line?
-Daniel

>   *
>   * Writes to the TMDS config register over SCDC channel, and:
> -- 
> 2.14.0.rc0.284.gd933b75aa4-goog
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH v2 2/4] drm: Fix warning when building docs for scdc_helper

[Sean Paul]

Fixes:
../drivers/gpu/drm/drm_scdc_helper.c:203: ERROR: Unexpected indentation.
../drivers/gpu/drm/drm_scdc_helper.c:204: WARNING: Block quote ends without a blank line; unexpected unindent.

Changes in v2:
 - Property blockquote TMDS calculations so they look pretty (Daniel)
 - Remove duplicate documentation from the header file

Signed-off-by: Sean Paul <seanpaul@chromium.org>
---
 drivers/gpu/drm/drm_scdc_helper.c | 33 ++++++++++++++++++++-------------
 include/drm/drm_scdc_helper.h     | 25 -------------------------
 2 files changed, 20 insertions(+), 38 deletions(-)

diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
index 3cd96a95736d..7d1b0f011d33 100644
--- a/drivers/gpu/drm/drm_scdc_helper.c
+++ b/drivers/gpu/drm/drm_scdc_helper.c
@@ -194,19 +194,26 @@ EXPORT_SYMBOL(drm_scdc_set_scrambling);
  * @adapter: I2C adapter for DDC channel
  * @set: ret or reset the high clock ratio
  *
- * TMDS clock ratio calculations go like this:
- * TMDS character = 10 bit TMDS encoded value
- * TMDS character rate = The rate at which TMDS characters are transmitted(Mcsc)
- * TMDS bit rate = 10x TMDS character rate
- * As per the spec:
- * TMDS clock rate for pixel clock < 340 MHz = 1x the character rate
- *	= 1/10 pixel clock rate
- * TMDS clock rate for pixel clock > 340 MHz = 0.25x the character rate
- *	= 1/40 pixel clock rate
- *
- * Writes to the TMDS config register over SCDC channel, and:
- * sets TMDS clock ratio to 1/40 when set = 1
- * sets TMDS clock ratio to 1/10 when set = 0
+ *
+ *	TMDS clock ratio calculations go like this:
+ *		TMDS character = 10 bit TMDS encoded value
+ *
+ *		TMDS character rate = The rate at which TMDS characters are
+ *		transmitted (Mcsc)
+ *
+ *		TMDS bit rate = 10x TMDS character rate
+ *
+ *	As per the spec:
+ *		TMDS clock rate for pixel clock < 340 MHz = 1x the character
+ *		rate = 1/10 pixel clock rate
+ *
+ *		TMDS clock rate for pixel clock > 340 MHz = 0.25x the character
+ *		rate = 1/40 pixel clock rate
+ *
+ *	Writes to the TMDS config register over SCDC channel, and:
+ *		sets TMDS clock ratio to 1/40 when set = 1
+ *
+ *		sets TMDS clock ratio to 1/10 when set = 0
  *
  * Returns:
  * True if write is successful, false otherwise.
diff --git a/include/drm/drm_scdc_helper.h b/include/drm/drm_scdc_helper.h
index c25122bb490a..f92eb2094d6b 100644
--- a/include/drm/drm_scdc_helper.h
+++ b/include/drm/drm_scdc_helper.h
@@ -131,31 +131,6 @@ static inline int drm_scdc_writeb(struct i2c_adapter *adapter, u8 offset,
 
 bool drm_scdc_get_scrambling_status(struct i2c_adapter *adapter);
 
-/**
- * drm_scdc_set_scrambling - enable scrambling
- * @adapter: I2C adapter for DDC channel
- * @enable: bool to indicate if scrambling is to be enabled/disabled
- *
- * Writes the TMDS config register over SCDC channel, and:
- * enables scrambling when enable = 1
- * disables scrambling when enable = 0
- *
- * Returns:
- * True if scrambling is set/reset successfully, false otherwise.
- */
 bool drm_scdc_set_scrambling(struct i2c_adapter *adapter, bool enable);
-
-/**
- * drm_scdc_set_high_tmds_clock_ratio - set TMDS clock ratio
- * @adapter: I2C adapter for DDC channel
- * @set: ret or reset the high clock ratio
- *
- * Writes to the TMDS config register over SCDC channel, and:
- * sets TMDS clock ratio to 1/40 when set = 1
- * sets TMDS clock ratio to 1/10 when set = 0
- *
- * Returns:
- * True if write is successful, false otherwise.
- */
 bool drm_scdc_set_high_tmds_clock_ratio(struct i2c_adapter *adapter, bool set);
 #endif
-- 
2.14.0.rc0.284.gd933b75aa4-goog

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: FW: [PATCH v2 2/4] drm: Fix warning when building docs for scdc_helper

[Sharma, Shashank]

Thanks for adding this fix , Sean, and sorry about missing this 
alignment in doc.

Regards
Shashank
On 7/24/2017 9:01 PM, Sharma, Shashank wrote:
>
> -----Original Message-----
> From: dri-devel [mailto:dri-devel-bounces@lists.freedesktop.org] On Behalf Of Sean Paul
> Sent: Friday, July 21, 2017 1:39 AM
> To: dri-devel@lists.freedesktop.org; daniel@ffwll.ch
> Cc: Vetter, Daniel <daniel.vetter@intel.com>
> Subject: [PATCH v2 2/4] drm: Fix warning when building docs for scdc_helper
>
> Fixes:
> ../drivers/gpu/drm/drm_scdc_helper.c:203: ERROR: Unexpected indentation.
> ../drivers/gpu/drm/drm_scdc_helper.c:204: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> Changes in v2:
>   - Property blockquote TMDS calculations so they look pretty (Daniel)
>   - Remove duplicate documentation from the header file
>
> Signed-off-by: Sean Paul <seanpaul@chromium.org>
> ---
>   drivers/gpu/drm/drm_scdc_helper.c | 33 ++++++++++++++++++++-------------
>   include/drm/drm_scdc_helper.h     | 25 -------------------------
>   2 files changed, 20 insertions(+), 38 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
> index 3cd96a95736d..7d1b0f011d33 100644
> --- a/drivers/gpu/drm/drm_scdc_helper.c
> +++ b/drivers/gpu/drm/drm_scdc_helper.c
> @@ -194,19 +194,26 @@ EXPORT_SYMBOL(drm_scdc_set_scrambling);
>    * @adapter: I2C adapter for DDC channel
>    * @set: ret or reset the high clock ratio
>    *
> - * TMDS clock ratio calculations go like this:
> - * TMDS character = 10 bit TMDS encoded value
> - * TMDS character rate = The rate at which TMDS characters are transmitted(Mcsc)
> - * TMDS bit rate = 10x TMDS character rate
> - * As per the spec:
> - * TMDS clock rate for pixel clock < 340 MHz = 1x the character rate
> - *	= 1/10 pixel clock rate
> - * TMDS clock rate for pixel clock > 340 MHz = 0.25x the character rate
> - *	= 1/40 pixel clock rate
> - *
> - * Writes to the TMDS config register over SCDC channel, and:
> - * sets TMDS clock ratio to 1/40 when set = 1
> - * sets TMDS clock ratio to 1/10 when set = 0
> + *
> + *	TMDS clock ratio calculations go like this:
> + *		TMDS character = 10 bit TMDS encoded value
> + *
> + *		TMDS character rate = The rate at which TMDS characters are
> + *		transmitted (Mcsc)
> + *
> + *		TMDS bit rate = 10x TMDS character rate
> + *
> + *	As per the spec:
> + *		TMDS clock rate for pixel clock < 340 MHz = 1x the character
> + *		rate = 1/10 pixel clock rate
> + *
> + *		TMDS clock rate for pixel clock > 340 MHz = 0.25x the character
> + *		rate = 1/40 pixel clock rate
> + *
> + *	Writes to the TMDS config register over SCDC channel, and:
> + *		sets TMDS clock ratio to 1/40 when set = 1
> + *
> + *		sets TMDS clock ratio to 1/10 when set = 0
>    *
>    * Returns:
>    * True if write is successful, false otherwise.
> diff --git a/include/drm/drm_scdc_helper.h b/include/drm/drm_scdc_helper.h index c25122bb490a..f92eb2094d6b 100644
> --- a/include/drm/drm_scdc_helper.h
> +++ b/include/drm/drm_scdc_helper.h
> @@ -131,31 +131,6 @@ static inline int drm_scdc_writeb(struct i2c_adapter *adapter, u8 offset,
>   
>   bool drm_scdc_get_scrambling_status(struct i2c_adapter *adapter);
>   
> -/**
> - * drm_scdc_set_scrambling - enable scrambling
> - * @adapter: I2C adapter for DDC channel
> - * @enable: bool to indicate if scrambling is to be enabled/disabled
> - *
> - * Writes the TMDS config register over SCDC channel, and:
> - * enables scrambling when enable = 1
> - * disables scrambling when enable = 0
> - *
> - * Returns:
> - * True if scrambling is set/reset successfully, false otherwise.
> - */
>   bool drm_scdc_set_scrambling(struct i2c_adapter *adapter, bool enable);
> -
> -/**
> - * drm_scdc_set_high_tmds_clock_ratio - set TMDS clock ratio
> - * @adapter: I2C adapter for DDC channel
> - * @set: ret or reset the high clock ratio
> - *
> - * Writes to the TMDS config register over SCDC channel, and:
> - * sets TMDS clock ratio to 1/40 when set = 1
> - * sets TMDS clock ratio to 1/10 when set = 0
> - *
> - * Returns:
> - * True if write is successful, false otherwise.
> - */
>   bool drm_scdc_set_high_tmds_clock_ratio(struct i2c_adapter *adapter, bool set);  #endif
> --
> 2.14.0.rc0.284.gd933b75aa4-goog

Reviewed-by: Shashank Sharma <shashank.sharma@intel.com>

> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 3/4] gpu/host1x: Remove excess parameter in host1x_subdev_add docs

[Sean Paul]

Fixes the following warning when building docs:
../drivers/gpu/host1x/bus.c:50: warning: Excess function parameter 'driver' description in 'host1x_subdev_add'

Signed-off-by: Sean Paul <seanpaul-F7+t8E8rja9g9hUCZPvPmw@public.gmane.org>
---
 drivers/gpu/host1x/bus.c | 1 -
 1 file changed, 1 deletion(-)

diff --git a/drivers/gpu/host1x/bus.c b/drivers/gpu/host1x/bus.c
index a048e3ac523d..7ece0e9058c6 100644
--- a/drivers/gpu/host1x/bus.c
+++ b/drivers/gpu/host1x/bus.c
@@ -41,7 +41,6 @@ struct host1x_subdev {
 /**
  * host1x_subdev_add() - add a new subdevice with an associated device node
  * @device: host1x device to add the subdevice to
- * @driver: host1x driver
  * @np: device node
  */
 static int host1x_subdev_add(struct host1x_device *device,
-- 
2.14.0.rc0.284.gd933b75aa4-goog

[PATCH 4/4] drm: Add a few missing descriptions in drm_driver docs

[Sean Paul]

Fixes the following warnings when building docs:
../include/drm/drm_drv.h:553: warning: No description found for parameter 'debugfs_init'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_open_object'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_close_object'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'prime_handle_to_fd'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'prime_fd_to_handle'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_prime_export'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_prime_import'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_vm_ops'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'major'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'minor'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'patchlevel'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'name'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'desc'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'date'
../include/drm/drm_drv.h:553: warning: No description found for parameter 'driver_features'

There are still a couple more warnings for prime helpers that are documented elsewhere.

Signed-off-by: Sean Paul <seanpaul@chromium.org>
---
 include/drm/drm_drv.h | 52 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 6 deletions(-)

diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
index 81971dc0b573..505c91354802 100644
--- a/include/drm/drm_drv.h
+++ b/include/drm/drm_drv.h
@@ -390,6 +390,11 @@ struct drm_driver {
 	 */
 	void (*master_drop)(struct drm_device *dev, struct drm_file *file_priv);
 
+	/**
+	 * @debugfs_init:
+	 *
+	 * Allows drivers to create driver-specific debugfs files.
+	 */
 	int (*debugfs_init)(struct drm_minor *minor);
 
 	/**
@@ -408,7 +413,18 @@ struct drm_driver {
 	 */
 	void (*gem_free_object_unlocked) (struct drm_gem_object *obj);
 
+	/**
+	 * @gem_open_object:
+	 *
+	 * Driver hook called upon gem handle creation
+	 */
 	int (*gem_open_object) (struct drm_gem_object *, struct drm_file *);
+
+	/**
+	 * @gem_close_object:
+	 *
+	 * Driver hook called upon gem handle release
+	 */
 	void (*gem_close_object) (struct drm_gem_object *, struct drm_file *);
 
 	/**
@@ -421,19 +437,34 @@ struct drm_driver {
 						    size_t size);
 
 	/* prime: */
-	/* export handle -> fd (see drm_gem_prime_handle_to_fd() helper) */
+	/**
+	 * @prime_handle_to_fd:
+	 *
+	 * export handle -> fd (see drm_gem_prime_handle_to_fd() helper)
+	 */
 	int (*prime_handle_to_fd)(struct drm_device *dev, struct drm_file *file_priv,
 				uint32_t handle, uint32_t flags, int *prime_fd);
-	/* import fd -> handle (see drm_gem_prime_fd_to_handle() helper) */
+	/**
+	 * @prime_fd_to_handle:
+	 *
+	 * import fd -> handle (see drm_gem_prime_fd_to_handle() helper)
+	 */
 	int (*prime_fd_to_handle)(struct drm_device *dev, struct drm_file *file_priv,
 				int prime_fd, uint32_t *handle);
-	/* export GEM -> dmabuf */
+	/**
+	 * @gem_prime_export:
+	 *
+	 * export GEM -> dmabuf
+	 */
 	struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
 				struct drm_gem_object *obj, int flags);
-	/* import dmabuf -> GEM */
+	/**
+	 * @gem_prime_import:
+	 *
+	 * import dmabuf -> GEM
+	 */
 	struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
 				struct dma_buf *dma_buf);
-	/* low-level interface used by drm_gem_prime_{import,export} */
 	int (*gem_prime_pin)(struct drm_gem_object *obj);
 	void (*gem_prime_unpin)(struct drm_gem_object *obj);
 	struct reservation_object * (*gem_prime_res_obj)(
@@ -505,16 +536,25 @@ struct drm_driver {
 			    struct drm_device *dev,
 			    uint32_t handle);
 
-	/* Driver private ops for this object */
+	/**
+	 * @gem_vm_ops: Driver private ops for this object
+	 */
 	const struct vm_operations_struct *gem_vm_ops;
 
+	/** @major: driver major number */
 	int major;
+	/** @minor: driver minor number */
 	int minor;
+	/** @patchlevel: driver patch level */
 	int patchlevel;
+	/** @name: driver name */
 	char *name;
+	/** @desc: driver description */
 	char *desc;
+	/** @date: driver date */
 	char *date;
 
+	/** @driver_features: driver features */
 	u32 driver_features;
 
 	/**
-- 
2.14.0.rc0.284.gd933b75aa4-goog

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 4/4] drm: Add a few missing descriptions in drm_driver docs

[Daniel Vetter]

On Thu, Jul 20, 2017 at 01:47:43PM -0400, Sean Paul wrote:
> Fixes the following warnings when building docs:
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'debugfs_init'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_open_object'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_close_object'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'prime_handle_to_fd'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'prime_fd_to_handle'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_prime_export'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_prime_import'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_vm_ops'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'major'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'minor'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'patchlevel'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'name'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'desc'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'date'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'driver_features'
> 
> There are still a couple more warnings for prime helpers that are documented elsewhere.
> 
> Signed-off-by: Sean Paul <seanpaul@chromium.org>

Yeah reviewing gem/prime docs is still on my todo, which is why these
aren't complete yet. Yours are a bit terse and we probably want an
overhaul of all the gem/prime docs, but at least a start.

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>


> ---
>  include/drm/drm_drv.h | 52 +++++++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 46 insertions(+), 6 deletions(-)
> 
> diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
> index 81971dc0b573..505c91354802 100644
> --- a/include/drm/drm_drv.h
> +++ b/include/drm/drm_drv.h
> @@ -390,6 +390,11 @@ struct drm_driver {
>  	 */
>  	void (*master_drop)(struct drm_device *dev, struct drm_file *file_priv);
>  
> +	/**
> +	 * @debugfs_init:
> +	 *
> +	 * Allows drivers to create driver-specific debugfs files.
> +	 */
>  	int (*debugfs_init)(struct drm_minor *minor);
>  
>  	/**
> @@ -408,7 +413,18 @@ struct drm_driver {
>  	 */
>  	void (*gem_free_object_unlocked) (struct drm_gem_object *obj);
>  
> +	/**
> +	 * @gem_open_object:
> +	 *
> +	 * Driver hook called upon gem handle creation
> +	 */
>  	int (*gem_open_object) (struct drm_gem_object *, struct drm_file *);
> +
> +	/**
> +	 * @gem_close_object:
> +	 *
> +	 * Driver hook called upon gem handle release
> +	 */
>  	void (*gem_close_object) (struct drm_gem_object *, struct drm_file *);
>  
>  	/**
> @@ -421,19 +437,34 @@ struct drm_driver {
>  						    size_t size);
>  
>  	/* prime: */
> -	/* export handle -> fd (see drm_gem_prime_handle_to_fd() helper) */
> +	/**
> +	 * @prime_handle_to_fd:
> +	 *
> +	 * export handle -> fd (see drm_gem_prime_handle_to_fd() helper)
> +	 */
>  	int (*prime_handle_to_fd)(struct drm_device *dev, struct drm_file *file_priv,
>  				uint32_t handle, uint32_t flags, int *prime_fd);
> -	/* import fd -> handle (see drm_gem_prime_fd_to_handle() helper) */
> +	/**
> +	 * @prime_fd_to_handle:
> +	 *
> +	 * import fd -> handle (see drm_gem_prime_fd_to_handle() helper)
> +	 */
>  	int (*prime_fd_to_handle)(struct drm_device *dev, struct drm_file *file_priv,
>  				int prime_fd, uint32_t *handle);
> -	/* export GEM -> dmabuf */
> +	/**
> +	 * @gem_prime_export:
> +	 *
> +	 * export GEM -> dmabuf
> +	 */
>  	struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
>  				struct drm_gem_object *obj, int flags);
> -	/* import dmabuf -> GEM */
> +	/**
> +	 * @gem_prime_import:
> +	 *
> +	 * import dmabuf -> GEM
> +	 */
>  	struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
>  				struct dma_buf *dma_buf);
> -	/* low-level interface used by drm_gem_prime_{import,export} */
>  	int (*gem_prime_pin)(struct drm_gem_object *obj);
>  	void (*gem_prime_unpin)(struct drm_gem_object *obj);
>  	struct reservation_object * (*gem_prime_res_obj)(
> @@ -505,16 +536,25 @@ struct drm_driver {
>  			    struct drm_device *dev,
>  			    uint32_t handle);
>  
> -	/* Driver private ops for this object */
> +	/**
> +	 * @gem_vm_ops: Driver private ops for this object
> +	 */
>  	const struct vm_operations_struct *gem_vm_ops;
>  
> +	/** @major: driver major number */
>  	int major;
> +	/** @minor: driver minor number */
>  	int minor;
> +	/** @patchlevel: driver patch level */
>  	int patchlevel;
> +	/** @name: driver name */
>  	char *name;
> +	/** @desc: driver description */
>  	char *desc;
> +	/** @date: driver date */
>  	char *date;
>  
> +	/** @driver_features: driver features */
>  	u32 driver_features;
>  
>  	/**
> -- 
> 2.14.0.rc0.284.gd933b75aa4-goog
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 0/4] drm: Fix some warnings when building docs

[Thierry Reding]

[-- Attachment #1.1: Type: text/plain, Size: 1005 bytes --]

On Thu, Jul 20, 2017 at 01:47:39PM -0400, Sean Paul wrote:
> I noticed these warnings as part of my compile testing and decided to fix them.
> 
> There are still a few warnings with the import/export prime helpers. They're
> partially documented in drm_prime.c, so suggestions welcome on how to resolve
> them without duplication (or perhaps duplication is best in this case).
> 
> Sean
> 
> 
> 
> Sean Paul (4):
>   drm/modes: Fix drm_mode_is_420_only() comment
>   drm: Fix warning when building docs for scdc_helper
>   gpu/host1x: Remove excess parameter in host1x_subdev_add docs
>   drm: Add a few missing descriptions in drm_driver docs
> 
>  drivers/gpu/drm/drm_modes.c       |  2 +-
>  drivers/gpu/drm/drm_scdc_helper.c |  4 +--
>  drivers/gpu/host1x/bus.c          |  1 -
>  include/drm/drm_drv.h             | 52 ++++++++++++++++++++++++++++++++++-----
>  4 files changed, 49 insertions(+), 10 deletions(-)

Applied all four patches to drm-misc-next, thanks.

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel