Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   Benjamin Gaignard <benjamin.gaignard@st.com>
To:     <maarten.lankhorst@linux.intel.com>, <mripard@kernel.org>,
        <airlied@linux.ie>, <daniel@ffwll.ch>
CC:     <dri-devel@lists.freedesktop.org>, <linux-kernel@vger.kernel.org>,
        Benjamin Gaignard <benjamin.gaignard@st.com>
Subject: [PATCH] gpu: drm: context: Clean up documentation
Date:   Fri, 31 Jan 2020 10:21:47 +0100
Message-ID: <20200131092147.32063-1-benjamin.gaignard@st.com>
MIME-Version: 1.0
Content-Type: text/plain
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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(-)

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