Fix kernel doc comments to avoid warnings when compiling with W=1.
Signed-off-by: Benjamin Gaignard <[email protected]>
---
drivers/gpu/drm/drm_context.c | 145 ++++++++++++++++++------------------------
1 file changed, 61 insertions(+), 84 deletions(-)
diff --git a/drivers/gpu/drm/drm_context.c b/drivers/gpu/drm/drm_context.c
index 1f802d8e5681..54e64d612a2b 100644
--- a/drivers/gpu/drm/drm_context.c
+++ b/drivers/gpu/drm/drm_context.c
@@ -43,15 +43,11 @@ struct drm_ctx_list {
struct drm_file *tag;
};
-/******************************************************************/
-/** \name Context bitmap support */
-/*@{*/
-
/**
- * Free a handle from the context bitmap.
+ * drm_legacy_ctxbitmap_free() - Free a handle from the context bitmap.
*
- * \param dev DRM device.
- * \param ctx_handle context handle.
+ * @dev: DRM device.
+ * @ctx_handle: context handle.
*
* Clears the bit specified by \p ctx_handle in drm_device::ctx_bitmap and the entry
* in drm_device::ctx_idr, while holding the drm_device::struct_mutex
@@ -69,10 +65,10 @@ void drm_legacy_ctxbitmap_free(struct drm_device * dev, int ctx_handle)
}
/**
- * Context bitmap allocation.
+ * drm_legacy_ctxbitmap_next() - Context bitmap allocation.
*
- * \param dev DRM device.
- * \return (non-negative) context handle on success or a negative number on failure.
+ * @dev: DRM device.
+ * Return: (non-negative) context handle on success or a negative number on failure.
*
* Allocate a new idr from drm_device::ctx_idr while holding the
* drm_device::struct_mutex lock.
@@ -89,9 +85,9 @@ static int drm_legacy_ctxbitmap_next(struct drm_device * dev)
}
/**
- * Context bitmap initialization.
+ * drm_legacy_ctxbitmap_init() - Context bitmap initialization.
*
- * \param dev DRM device.
+ * @dev: DRM device.
*
* Initialise the drm_device::ctx_idr
*/
@@ -105,9 +101,9 @@ void drm_legacy_ctxbitmap_init(struct drm_device * dev)
}
/**
- * Context bitmap cleanup.
+ * drm_legacy_ctxbitmap_cleanup() - bitmap cleanup.
*
- * \param dev DRM device.
+ * @dev: DRM device.
*
* Free all idr members using drm_ctx_sarea_free helper function
* while holding the drm_device::struct_mutex lock.
@@ -157,20 +153,13 @@ void drm_legacy_ctxbitmap_flush(struct drm_device *dev, struct drm_file *file)
mutex_unlock(&dev->ctxlist_mutex);
}
-/*@}*/
-
-/******************************************************************/
-/** \name Per Context SAREA Support */
-/*@{*/
-
/**
- * Get per-context SAREA.
+ * drm_legacy_getsareactx() - Get per-context SAREA.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx_priv_map structure.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
+ * Return: zero on success or a negative number on failure.
*
* Gets the map from drm_device::ctx_idr with the handle specified and
* returns its handle.
@@ -212,13 +201,12 @@ int drm_legacy_getsareactx(struct drm_device *dev, void *data,
}
/**
- * Set per-context SAREA.
+ * drm_legacy_setsareactx() - Set per-context SAREA.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx_priv_map structure.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
+ * Return: zero on success or a negative number on failure.
*
* Searches the mapping specified in \p arg and update the entry in
* drm_device::ctx_idr with it.
@@ -257,19 +245,13 @@ int drm_legacy_setsareactx(struct drm_device *dev, void *data,
return 0;
}
-/*@}*/
-
-/******************************************************************/
-/** \name The actual DRM context handling routines */
-/*@{*/
-
/**
- * Switch context.
+ * drm_context_switch() - Switch context.
*
- * \param dev DRM device.
- * \param old old context handle.
- * \param new new context handle.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device.
+ * @old: old context handle.
+ * @new: new context handle.
+ * Return: zero on success or a negative number on failure.
*
* Attempt to set drm_device::context_flag.
*/
@@ -291,11 +273,12 @@ static int drm_context_switch(struct drm_device * dev, int old, int new)
}
/**
- * Complete context switch.
+ * drm_context_switch_complete() - Complete context switch.
*
- * \param dev DRM device.
- * \param new new context handle.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device.
+ * @file_priv: DRM file private.
+ * @new: new context handle.
+ * Return: zero on success or a negative number on failure.
*
* Updates drm_device::last_context and drm_device::last_switch. Verifies the
* hardware lock is held, clears the drm_device::context_flag and wakes up
@@ -319,13 +302,13 @@ static int drm_context_switch_complete(struct drm_device *dev,
}
/**
- * Reserve contexts.
+ * drm_legacy_resctx() - Reserve contexts.
+ *
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx_res structure.
- * \return zero on success or a negative number on failure.
+ * Return: zero on success or a negative number on failure.
*/
int drm_legacy_resctx(struct drm_device *dev, void *data,
struct drm_file *file_priv)
@@ -352,15 +335,13 @@ int drm_legacy_resctx(struct drm_device *dev, void *data,
}
/**
- * Add context.
+ * drm_legacy_addctx() - Add context.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx structure.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
*
- * Get a new handle for the context and copy to userspace.
+ * Return: zero on success or a negative number on failure.
*/
int drm_legacy_addctx(struct drm_device *dev, void *data,
struct drm_file *file_priv)
@@ -405,13 +386,12 @@ int drm_legacy_addctx(struct drm_device *dev, void *data,
}
/**
- * Get context.
+ * drm_legacy_getctx() - Get context.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx structure.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
+ * Return: zero on success or a negative number on failure.
*/
int drm_legacy_getctx(struct drm_device *dev, void *data,
struct drm_file *file_priv)
@@ -429,13 +409,12 @@ int drm_legacy_getctx(struct drm_device *dev, void *data,
}
/**
- * Switch context.
+ * drm_legacy_switchctx() - Switch context.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx structure.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
+ * Return: zero on success or a negative number on failure.
*
* Calls context_switch().
*/
@@ -453,13 +432,12 @@ int drm_legacy_switchctx(struct drm_device *dev, void *data,
}
/**
- * New context.
+ * drm_legacy_newctx() - New context.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx structure.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
+ * Return: zero on success or a negative number on failure.
*
* Calls context_switch_complete().
*/
@@ -479,13 +457,12 @@ int drm_legacy_newctx(struct drm_device *dev, void *data,
}
/**
- * Remove context.
+ * drm_legacy_rmctx() - Remove context.
*
- * \param inode device inode.
- * \param file_priv DRM file private.
- * \param cmd command.
- * \param arg user argument pointing to a drm_ctx structure.
- * \return zero on success or a negative number on failure.
+ * @dev: DRM device to operate on
+ * @data: request data
+ * @file_priv: DRM file private.
+ * Return: zero on success or a negative number on failure.
*
* If not the special kernel context, calls ctxbitmap_free() to free the specified context.
*/
--
2.15.0
Le lun. 3 févr. 2020 à 09:11, Benjamin Gaignard
<[email protected]> a écrit :
>
> Fix kernel doc comments to avoid warnings when compiling with W=1.
gentle ping.
Benjamin
>
> Signed-off-by: Benjamin Gaignard <[email protected]>
> ---
> drivers/gpu/drm/drm_context.c | 145 ++++++++++++++++++------------------------
> 1 file changed, 61 insertions(+), 84 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_context.c b/drivers/gpu/drm/drm_context.c
> index 1f802d8e5681..54e64d612a2b 100644
> --- a/drivers/gpu/drm/drm_context.c
> +++ b/drivers/gpu/drm/drm_context.c
> @@ -43,15 +43,11 @@ struct drm_ctx_list {
> struct drm_file *tag;
> };
>
> -/******************************************************************/
> -/** \name Context bitmap support */
> -/*@{*/
> -
> /**
> - * Free a handle from the context bitmap.
> + * drm_legacy_ctxbitmap_free() - Free a handle from the context bitmap.
> *
> - * \param dev DRM device.
> - * \param ctx_handle context handle.
> + * @dev: DRM device.
> + * @ctx_handle: context handle.
> *
> * Clears the bit specified by \p ctx_handle in drm_device::ctx_bitmap and the entry
> * in drm_device::ctx_idr, while holding the drm_device::struct_mutex
> @@ -69,10 +65,10 @@ void drm_legacy_ctxbitmap_free(struct drm_device * dev, int ctx_handle)
> }
>
> /**
> - * Context bitmap allocation.
> + * drm_legacy_ctxbitmap_next() - Context bitmap allocation.
> *
> - * \param dev DRM device.
> - * \return (non-negative) context handle on success or a negative number on failure.
> + * @dev: DRM device.
> + * Return: (non-negative) context handle on success or a negative number on failure.
> *
> * Allocate a new idr from drm_device::ctx_idr while holding the
> * drm_device::struct_mutex lock.
> @@ -89,9 +85,9 @@ static int drm_legacy_ctxbitmap_next(struct drm_device * dev)
> }
>
> /**
> - * Context bitmap initialization.
> + * drm_legacy_ctxbitmap_init() - Context bitmap initialization.
> *
> - * \param dev DRM device.
> + * @dev: DRM device.
> *
> * Initialise the drm_device::ctx_idr
> */
> @@ -105,9 +101,9 @@ void drm_legacy_ctxbitmap_init(struct drm_device * dev)
> }
>
> /**
> - * Context bitmap cleanup.
> + * drm_legacy_ctxbitmap_cleanup() - bitmap cleanup.
> *
> - * \param dev DRM device.
> + * @dev: DRM device.
> *
> * Free all idr members using drm_ctx_sarea_free helper function
> * while holding the drm_device::struct_mutex lock.
> @@ -157,20 +153,13 @@ void drm_legacy_ctxbitmap_flush(struct drm_device *dev, struct drm_file *file)
> mutex_unlock(&dev->ctxlist_mutex);
> }
>
> -/*@}*/
> -
> -/******************************************************************/
> -/** \name Per Context SAREA Support */
> -/*@{*/
> -
> /**
> - * Get per-context SAREA.
> + * drm_legacy_getsareactx() - Get per-context SAREA.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx_priv_map structure.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> + * Return: zero on success or a negative number on failure.
> *
> * Gets the map from drm_device::ctx_idr with the handle specified and
> * returns its handle.
> @@ -212,13 +201,12 @@ int drm_legacy_getsareactx(struct drm_device *dev, void *data,
> }
>
> /**
> - * Set per-context SAREA.
> + * drm_legacy_setsareactx() - Set per-context SAREA.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx_priv_map structure.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> + * Return: zero on success or a negative number on failure.
> *
> * Searches the mapping specified in \p arg and update the entry in
> * drm_device::ctx_idr with it.
> @@ -257,19 +245,13 @@ int drm_legacy_setsareactx(struct drm_device *dev, void *data,
> return 0;
> }
>
> -/*@}*/
> -
> -/******************************************************************/
> -/** \name The actual DRM context handling routines */
> -/*@{*/
> -
> /**
> - * Switch context.
> + * drm_context_switch() - Switch context.
> *
> - * \param dev DRM device.
> - * \param old old context handle.
> - * \param new new context handle.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device.
> + * @old: old context handle.
> + * @new: new context handle.
> + * Return: zero on success or a negative number on failure.
> *
> * Attempt to set drm_device::context_flag.
> */
> @@ -291,11 +273,12 @@ static int drm_context_switch(struct drm_device * dev, int old, int new)
> }
>
> /**
> - * Complete context switch.
> + * drm_context_switch_complete() - Complete context switch.
> *
> - * \param dev DRM device.
> - * \param new new context handle.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device.
> + * @file_priv: DRM file private.
> + * @new: new context handle.
> + * Return: zero on success or a negative number on failure.
> *
> * Updates drm_device::last_context and drm_device::last_switch. Verifies the
> * hardware lock is held, clears the drm_device::context_flag and wakes up
> @@ -319,13 +302,13 @@ static int drm_context_switch_complete(struct drm_device *dev,
> }
>
> /**
> - * Reserve contexts.
> + * drm_legacy_resctx() - Reserve contexts.
> + *
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx_res structure.
> - * \return zero on success or a negative number on failure.
> + * Return: zero on success or a negative number on failure.
> */
> int drm_legacy_resctx(struct drm_device *dev, void *data,
> struct drm_file *file_priv)
> @@ -352,15 +335,13 @@ int drm_legacy_resctx(struct drm_device *dev, void *data,
> }
>
> /**
> - * Add context.
> + * drm_legacy_addctx() - Add context.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx structure.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> *
> - * Get a new handle for the context and copy to userspace.
> + * Return: zero on success or a negative number on failure.
> */
> int drm_legacy_addctx(struct drm_device *dev, void *data,
> struct drm_file *file_priv)
> @@ -405,13 +386,12 @@ int drm_legacy_addctx(struct drm_device *dev, void *data,
> }
>
> /**
> - * Get context.
> + * drm_legacy_getctx() - Get context.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx structure.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> + * Return: zero on success or a negative number on failure.
> */
> int drm_legacy_getctx(struct drm_device *dev, void *data,
> struct drm_file *file_priv)
> @@ -429,13 +409,12 @@ int drm_legacy_getctx(struct drm_device *dev, void *data,
> }
>
> /**
> - * Switch context.
> + * drm_legacy_switchctx() - Switch context.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx structure.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> + * Return: zero on success or a negative number on failure.
> *
> * Calls context_switch().
> */
> @@ -453,13 +432,12 @@ int drm_legacy_switchctx(struct drm_device *dev, void *data,
> }
>
> /**
> - * New context.
> + * drm_legacy_newctx() - New context.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx structure.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> + * Return: zero on success or a negative number on failure.
> *
> * Calls context_switch_complete().
> */
> @@ -479,13 +457,12 @@ int drm_legacy_newctx(struct drm_device *dev, void *data,
> }
>
> /**
> - * Remove context.
> + * drm_legacy_rmctx() - Remove context.
> *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument pointing to a drm_ctx structure.
> - * \return zero on success or a negative number on failure.
> + * @dev: DRM device to operate on
> + * @data: request data
> + * @file_priv: DRM file private.
> + * Return: zero on success or a negative number on failure.
> *
> * If not the special kernel context, calls ctxbitmap_free() to free the specified context.
> */
> --
> 2.15.0
>
> _______________________________________________
> dri-devel mailing list
> [email protected]
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
On Mon, 3 Feb 2020 at 08:11, Benjamin Gaignard <[email protected]> wrote:
>
> Fix kernel doc comments to avoid warnings when compiling with W=1.
>
> Signed-off-by: Benjamin Gaignard <[email protected]>
> ---
> drivers/gpu/drm/drm_context.c | 145 ++++++++++++++++++------------------------
> 1 file changed, 61 insertions(+), 84 deletions(-)
>
Since we're talking about legacy, aka user mode-setting code, I think
a wiser solution is to simply remove the documentation. It is _not_
something we should encourage people to read, let alone use.
Nit: prefix should be "drm:"
-Emil
On 3/4/20 5:07 PM, Emil Velikov wrote:
> On Mon, 3 Feb 2020 at 08:11, Benjamin Gaignard <[email protected]> wrote:
>> Fix kernel doc comments to avoid warnings when compiling with W=1.
>>
>> Signed-off-by: Benjamin Gaignard <[email protected]>
>> ---
>> drivers/gpu/drm/drm_context.c | 145 ++++++++++++++++++------------------------
>> 1 file changed, 61 insertions(+), 84 deletions(-)
>>
> Since we're talking about legacy, aka user mode-setting code, I think
> a wiser solution is to simply remove the documentation. It is _not_
> something we should encourage people to read, let alone use.
>
> Nit: prefix should be "drm:"
Should I assume it is the same for drm_vm.c and drm_bufs.c ?
Benjamin
> -Emil
On Wed, Mar 04, 2020 at 04:42:09PM +0000, Benjamin GAIGNARD wrote:
>
>
> On 3/4/20 5:07 PM, Emil Velikov wrote:
> > On Mon, 3 Feb 2020 at 08:11, Benjamin Gaignard <[email protected]> wrote:
> >> Fix kernel doc comments to avoid warnings when compiling with W=1.
> >>
> >> Signed-off-by: Benjamin Gaignard <[email protected]>
> >> ---
> >> drivers/gpu/drm/drm_context.c | 145 ++++++++++++++++++------------------------
> >> 1 file changed, 61 insertions(+), 84 deletions(-)
> >>
> > Since we're talking about legacy, aka user mode-setting code, I think
> > a wiser solution is to simply remove the documentation. It is _not_
> > something we should encourage people to read, let alone use.
> >
> > Nit: prefix should be "drm:"
> Should I assume it is the same for drm_vm.c and drm_bufs.c ?
Yeah. In other legacy files all I've done is replace the /** with /* and
that's it. That shuts up kerneldoc validation for good with minimal
effort. Just not worth it to spend any time and polish on these :-)
-Daniel
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch