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;
MIME-Version: 1.0
References: <20200131092147.32063-1-benjamin.gaignard@st.com>
In-Reply-To: <20200131092147.32063-1-benjamin.gaignard@st.com>
From:   Benjamin Gaignard <benjamin.gaignard@linaro.org>
Date:   Wed, 4 Mar 2020 12:41:04 +0100
Message-ID: <CA+M3ks5y457YP4x_W8_Bv4OooicJSHtFyZ4CAfbEPvkhiQ5wSw@mail.gmail.com>
Subject: Re: [PATCH] gpu: drm: context: Clean up documentation
To:     Benjamin Gaignard <benjamin.gaignard@st.com>
Cc:     Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
        Maxime Ripard <mripard@kernel.org>,
        David Airlie <airlied@linux.ie>,
        Daniel Vetter <daniel@ffwll.ch>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        ML dri-devel <dri-devel@lists.freedesktop.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Le lun. 3 f=C3=A9vr. 2020 =C3=A0 09:11, Benjamin Gaignard
<benjamin.gaignard@st.com> a =C3=A9crit :
>
> Fix kernel doc comments to avoid warnings when compiling with W=3D1.

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 a=
nd 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 * de=
v, 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 * de=
v)
>  }
>
>  /**
> - * 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 * d=
ev, 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. Verifie=
s 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_d=
evice *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, vo=
id *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