| Message ID | 20200131092147.32063-1-benjamin.gaignard@st.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | gpu: drm: context: Clean up documentation | expand |
Le lun. 3 févr. 2020 à 09:11, Benjamin Gaignard <benjamin.gaignard@st.com> a écrit : > > Fix kernel doc comments to avoid warnings when compiling with W=1. gentle ping. Benjamin > > Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com> > --- > 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 > dri-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel
On Mon, 3 Feb 2020 at 08:11, Benjamin Gaignard <benjamin.gaignard@st.com> wrote: > > Fix kernel doc comments to avoid warnings when compiling with W=1. > > Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com> > --- > 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 <benjamin.gaignard@st.com> wrote: >> Fix kernel doc comments to avoid warnings when compiling with W=1. >> >> Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com> >> --- >> 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 <benjamin.gaignard@st.com> wrote: > >> Fix kernel doc comments to avoid warnings when compiling with W=1. > >> > >> Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com> > >> --- > >> 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
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. */
Fix kernel doc comments to avoid warnings when compiling with W=1. Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com> --- drivers/gpu/drm/drm_context.c | 145 ++++++++++++++++++------------------------ 1 file changed, 61 insertions(+), 84 deletions(-)