Skip to contentSkip to conversation

drm: Fix kerneldoc for "Returns" section

PATCH In review renjun wang 4 participants 6 messages Aug 24, 2024 – Aug 27, 2024

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 drm: Fix kerneldoc for "Returns" section

The blank line between title "Returns:" and detail description is not allowed, otherwise the title will goes under the description block in generated .html file after running make htmldocs.

There are a few examples for current kerneldoc:
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_crtc_commit_wait
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_atomic_get_crtc_state
https://www.kernel.org/doc/html/latest/gpu/i915.html#c.i915_vma_pin_fence

---
 drivers/gpu/drm/display/drm_dp_mst_topology.c | 4 ----
 drivers/gpu/drm/drm_atomic.c                  | 6 ------
 drivers/gpu/drm/drm_atomic_helper.c           | 2 --
 drivers/gpu/drm/drm_file.c                    | 7 -------
 drivers/gpu/drm/drm_gem.c                     | 7 ++-----
 drivers/gpu/drm/drm_modes.c                   | 1 -
 drivers/gpu/drm/drm_rect.c                    | 1 -
 drivers/gpu/drm/drm_vblank.c                  | 2 --
 drivers/gpu/drm/i915/gem/i915_gem_object.h    | 1 -
 drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c  | 1 -
 drivers/gpu/drm/i915/i915_vma.h               | 1 -
 11 files changed, 2 insertions(+), 31 deletions(-)
drivers/gpu/drm/display/drm_dp_mst_topology.c +0 -4
index fc2ceae61db2..e68d23997d53 100644
@@ -5569,7 +5569,6 @@ EXPORT_SYMBOL(drm_dp_mst_atomic_check_mgr);
  * drm_dp_atomic_release_time_slots()
  *
  * Returns:
- *
  * 0 if the new state is valid, negative error code otherwise.
  */
 int drm_dp_mst_atomic_check(struct drm_atomic_state *state)
@@ -5606,7 +5605,6 @@ EXPORT_SYMBOL(drm_dp_mst_topology_state_funcs);
  * topology object.
  *
  * RETURNS:
- *
  * The MST topology state or error pointer.
  */
 struct drm_dp_mst_topology_state *drm_atomic_get_mst_topology_state(struct drm_atomic_state *state,
@@ -5626,7 +5624,6 @@ EXPORT_SYMBOL(drm_atomic_get_mst_topology_state);
  * topology object.
  *
  * Returns:
- *
  * The old MST topology state, or NULL if there's no topology state for this MST mgr
  * in the global atomic state
  */
@@ -5651,7 +5648,6 @@ EXPORT_SYMBOL(drm_atomic_get_old_mst_topology_state);
  * topology object.
  *
  * Returns:
- *
  * The new MST topology state, or NULL if there's no topology state for this MST mgr
  * in the global atomic state
  */
drivers/gpu/drm/drm_atomic.c +0 -6
index 6e516c39a372..0fc99da93afe 100644
@@ -63,7 +63,6 @@ EXPORT_SYMBOL(__drm_crtc_commit_free);
  * hardware and flipped to.
  *
  * Returns:
- *
  * 0 on success, a negative error code otherwise.
  */
 int drm_crtc_commit_wait(struct drm_crtc_commit *commit)
@@ -337,7 +336,6 @@ EXPORT_SYMBOL(__drm_atomic_state_free);
  * not created by userspace through an IOCTL call.
  *
  * Returns:
- *
  * Either the allocated state or the error code encoded into the pointer. When
  * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
  * entire atomic sequence must be restarted. All other errors are fatal.
@@ -518,7 +516,6 @@ static int drm_atomic_connector_check(struct drm_connector *connector,
  * is consistent.
  *
  * Returns:
- *
  * Either the allocated state or the error code encoded into the pointer. When
  * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
  * entire atomic sequence must be restarted. All other errors are fatal.
@@ -828,7 +825,6 @@ EXPORT_SYMBOL(drm_atomic_private_obj_fini);
  * object lock to make sure that the state is consistent.
  *
  * RETURNS:
- *
  * Either the allocated state or the error code encoded into a pointer.
  */
 struct drm_private_state *
@@ -1061,7 +1057,6 @@ EXPORT_SYMBOL(drm_atomic_get_new_crtc_for_encoder);
  * make sure that the state is consistent.
  *
  * Returns:
- *
  * Either the allocated state or the error code encoded into the pointer. When
  * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
  * entire atomic sequence must be restarted. All other errors are fatal.
@@ -1169,7 +1164,6 @@ static void drm_atomic_connector_print_state(struct drm_printer *p,
  * state is consistent.
  *
  * Returns:
- *
  * Either the allocated state or the error code encoded into the pointer. When
  * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
  * entire atomic sequence must be restarted.
drivers/gpu/drm/drm_atomic_helper.c +0 -2
index fb97b51b38f1..43cdf39019a4 100644
@@ -2266,7 +2266,6 @@ crtc_or_fake_commit(struct drm_atomic_state *state, struct drm_crtc *crtc)
  * automatically.
  *
  * Returns:
- *
  * 0 on success. -EBUSY when userspace schedules nonblocking commits too fast,
  * -ENOMEM on allocation failures and -EINTR when a signal is pending.
  */
@@ -3009,7 +3008,6 @@ EXPORT_SYMBOL(drm_atomic_helper_cleanup_planes);
  * don't pass the right state structures to the callbacks.
  *
  * Returns:
- *
  * Returns 0 on success. Can return -ERESTARTSYS when @stall is true and the
  * waiting for the previous commits has been interrupted.
  */
drivers/gpu/drm/drm_file.c +0 -7
index 714e42b05108..7beed6902208 100644
@@ -355,7 +355,6 @@ int drm_open_helper(struct file *filp, struct drm_minor *minor)
  * resources for it. It also calls the &drm_driver.open driver callback.
  *
  * RETURNS:
- *
  * 0 on success or negative errno value on failure.
  */
 int drm_open(struct inode *inode, struct file *filp)
@@ -417,7 +416,6 @@ void drm_lastclose(struct drm_device * dev)
  * DRM device also proceeds to call the &drm_driver.lastclose driver callback.
  *
  * RETURNS:
- *
  * Always succeeds and returns 0.
  */
 int drm_release(struct inode *inode, struct file *filp)
@@ -489,7 +487,6 @@ void drm_file_update_pid(struct drm_file *filp)
  * call the &drm_driver.lastclose driver callback.
  *
  * RETURNS:
- *
  * Always succeeds and returns 0.
  */
 int drm_release_noglobal(struct inode *inode, struct file *filp)
@@ -532,7 +529,6 @@ EXPORT_SYMBOL(drm_release_noglobal);
  * safety.
  *
  * RETURNS:
- *
  * Number of bytes read (always aligned to full events, and can be 0) or a
  * negative error code on failure.
  */
@@ -618,7 +614,6 @@ EXPORT_SYMBOL(drm_read);
  * See also drm_read().
  *
  * RETURNS:
- *
  * Mask of POLL flags indicating the current status of the file.
  */
 __poll_t drm_poll(struct file *filp, struct poll_table_struct *wait)
@@ -656,7 +651,6 @@ EXPORT_SYMBOL(drm_poll);
  * already hold &drm_device.event_lock.
  *
  * RETURNS:
- *
  * 0 on success or a negative error code on failure.
  */
 int drm_event_reserve_init_locked(struct drm_device *dev,
@@ -698,7 +692,6 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked);
  * drm_event_reserve_init_locked() instead.
  *
  * RETURNS:
- *
  * 0 on success or a negative error code on failure.
  */
 int drm_event_reserve_init(struct drm_device *dev,
drivers/gpu/drm/drm_gem.c +2 -5
index d4bbc5d109c8..149b8e25da5b 100644
@@ -689,7 +689,6 @@ static int objects_lookup(struct drm_file *filp, u32 *handle, int count,
  * For a single handle lookup, use drm_gem_object_lookup().
  *
  * Returns:
- *
  * @objs filled in with GEM object pointers. Returned GEM objects need to be
  * released with drm_gem_object_put(). -ENOENT is returned on a lookup
  * failure. 0 is returned on success.
@@ -737,12 +736,11 @@ EXPORT_SYMBOL(drm_gem_objects_lookup);
  * @filp: DRM file private date
  * @handle: userspace handle
  *
- * Returns:
+ * If looking up an array of handles, use drm_gem_objects_lookup().
  *
+ * Returns:
  * A reference to the object named by the handle if such exists on @filp, NULL
  * otherwise.
- *
- * If looking up an array of handles, use drm_gem_objects_lookup().
  */
 struct drm_gem_object *
 drm_gem_object_lookup(struct drm_file *filp, u32 handle)
@@ -763,7 +761,6 @@ EXPORT_SYMBOL(drm_gem_object_lookup);
  * @timeout: timeout value in jiffies or zero to return immediately
  *
  * Returns:
- *
  * Returns -ERESTARTSYS if interrupted, 0 if the wait timed out, or
  * greater than 0 on success.
  */
drivers/gpu/drm/drm_modes.c +0 -1
index 1a0890083aee..6ba167a33461 100644
@@ -539,7 +539,6 @@ static int fill_analog_mode(struct drm_device *dev,
  * to reach those resolutions.
  *
  * Returns:
- *
  * A pointer to the mode, allocated with drm_mode_create(). Returns NULL
  * on error.
  */
drivers/gpu/drm/drm_rect.c +0 -1
index 85c79a38c13a..492acce0516f 100644
@@ -85,7 +85,6 @@ static u32 clip_scaled(int src, int dst, int *clip)
  * factors from @src to @dst.
  *
  * RETURNS:
- *
  * %true if rectangle @dst is still visible after being clipped,
  * %false otherwise.
  */
drivers/gpu/drm/drm_vblank.c +0 -2
index cc3571e25a9a..6428b7975dd6 100644
@@ -686,7 +686,6 @@ EXPORT_SYMBOL(drm_calc_timestamping_constants);
  * drm_atomic_helper_calc_timestamping_constants().
  *
  * Returns:
- *
  * Returns true on success, and false on failure, i.e. when no accurate
  * timestamp could be acquired.
  */
@@ -831,7 +830,6 @@ EXPORT_SYMBOL(drm_crtc_vblank_helper_get_vblank_timestamp_internal);
  * drm_atomic_helper_calc_timestamping_constants().
  *
  * Returns:
- *
  * Returns true on success, and false on failure, i.e. when no accurate
  * timestamp could be acquired.
  */
drivers/gpu/drm/i915/gem/i915_gem_object.h +0 -1
index 5d7446a48ae7..3dc61cbd2e11 100644
@@ -89,7 +89,6 @@ __i915_gem_object_unset_pages(struct drm_i915_gem_object *obj);
  * @handle: userspace handle
  *
  * Returns:
- *
  * A pointer to the object named by the handle if such exists on @filp, NULL
  * otherwise. This object is only valid whilst under the RCU read lock, and
  * note carefully the object may be in the process of being destroyed.
drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c +0 -1
index 93bc1cc1ee7e..0ffba50981e3 100644
@@ -418,7 +418,6 @@ int __i915_vma_pin_fence(struct i915_vma *vma)
  * For an untiled surface, this removes any existing fence.
  *
  * Returns:
- *
  * 0 on success, negative error code on failure.
  */
 int i915_vma_pin_fence(struct i915_vma *vma)
drivers/gpu/drm/i915/i915_vma.h +0 -1
index e356dfb883d3..6a6be8048aa8 100644
@@ -389,7 +389,6 @@ void i915_vma_unpin_iomap(struct i915_vma *vma);
  * i915_vma_unpin_fence().
  *
  * Returns:
- *
  * True if the vma has a fence, false otherwise.
  */
 int __must_check i915_vma_pin_fence(struct i915_vma *vma);
Signature · 1 line
2.39.2
maintainer Reviewed-by on v1 1/1
#1 lore raw

Am 24.08.24 um 10:36 schrieb renjun wang:

Quoted 10 lines

The blank line between title "Returns:" and detail description is not allowed, otherwise the title will goes under the description block in generated .html file after running make htmldocs.

There are a few examples for current kerneldoc:
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_crtc_commit_wait
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_atomic_get_crtc_state
https://www.kernel.org/doc/html/latest/gpu/i915.html#c.i915_vma_pin_fence

I'll add this patch and the other doc fix to the drm-misc tree. Thanks a lot for the fixes.

Best regards
Thomas

Quoted 297 lines
---
  drivers/gpu/drm/display/drm_dp_mst_topology.c | 4 ----
  drivers/gpu/drm/drm_atomic.c                  | 6 ------
  drivers/gpu/drm/drm_atomic_helper.c           | 2 --
  drivers/gpu/drm/drm_file.c                    | 7 -------
  drivers/gpu/drm/drm_gem.c                     | 7 ++-----
  drivers/gpu/drm/drm_modes.c                   | 1 -
  drivers/gpu/drm/drm_rect.c                    | 1 -
  drivers/gpu/drm/drm_vblank.c                  | 2 --
  drivers/gpu/drm/i915/gem/i915_gem_object.h    | 1 -
  drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c  | 1 -
  drivers/gpu/drm/i915/i915_vma.h               | 1 -
  11 files changed, 2 insertions(+), 31 deletions(-)
drivers/gpu/drm/display/drm_dp_mst_topology.c +0 -4
index fc2ceae61db2..e68d23997d53 100644
@@ -5569,7 +5569,6 @@ EXPORT_SYMBOL(drm_dp_mst_atomic_check_mgr);
   * drm_dp_atomic_release_time_slots()
   *
   * Returns:
- *
   * 0 if the new state is valid, negative error code otherwise.
   */
  int drm_dp_mst_atomic_check(struct drm_atomic_state *state)
@@ -5606,7 +5605,6 @@ EXPORT_SYMBOL(drm_dp_mst_topology_state_funcs);
   * topology object.
   *
   * RETURNS:
- *
   * The MST topology state or error pointer.
   */
  struct drm_dp_mst_topology_state *drm_atomic_get_mst_topology_state(struct drm_atomic_state *state,
@@ -5626,7 +5624,6 @@ EXPORT_SYMBOL(drm_atomic_get_mst_topology_state);
   * topology object.
   *
   * Returns:
- *
   * The old MST topology state, or NULL if there's no topology state for this MST mgr
   * in the global atomic state
   */
@@ -5651,7 +5648,6 @@ EXPORT_SYMBOL(drm_atomic_get_old_mst_topology_state);
   * topology object.
   *
   * Returns:
- *
   * The new MST topology state, or NULL if there's no topology state for this MST mgr
   * in the global atomic state
   */
drivers/gpu/drm/drm_atomic.c +0 -6
index 6e516c39a372..0fc99da93afe 100644
@@ -63,7 +63,6 @@ EXPORT_SYMBOL(__drm_crtc_commit_free);
   * hardware and flipped to.
   *
   * Returns:
- *
   * 0 on success, a negative error code otherwise.
   */
  int drm_crtc_commit_wait(struct drm_crtc_commit *commit)
@@ -337,7 +336,6 @@ EXPORT_SYMBOL(__drm_atomic_state_free);
   * not created by userspace through an IOCTL call.
   *
   * Returns:
- *
   * Either the allocated state or the error code encoded into the pointer. When
   * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
   * entire atomic sequence must be restarted. All other errors are fatal.
@@ -518,7 +516,6 @@ static int drm_atomic_connector_check(struct drm_connector *connector,
   * is consistent.
   *
   * Returns:
- *
   * Either the allocated state or the error code encoded into the pointer. When
   * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
   * entire atomic sequence must be restarted. All other errors are fatal.
@@ -828,7 +825,6 @@ EXPORT_SYMBOL(drm_atomic_private_obj_fini);
   * object lock to make sure that the state is consistent.
   *
   * RETURNS:
- *
   * Either the allocated state or the error code encoded into a pointer.
   */
  struct drm_private_state *
@@ -1061,7 +1057,6 @@ EXPORT_SYMBOL(drm_atomic_get_new_crtc_for_encoder);
   * make sure that the state is consistent.
   *
   * Returns:
- *
   * Either the allocated state or the error code encoded into the pointer. When
   * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
   * entire atomic sequence must be restarted. All other errors are fatal.
@@ -1169,7 +1164,6 @@ static void drm_atomic_connector_print_state(struct drm_printer *p,
   * state is consistent.
   *
   * Returns:
- *
   * Either the allocated state or the error code encoded into the pointer. When
   * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
   * entire atomic sequence must be restarted.
drivers/gpu/drm/drm_atomic_helper.c +0 -2
index fb97b51b38f1..43cdf39019a4 100644
@@ -2266,7 +2266,6 @@ crtc_or_fake_commit(struct drm_atomic_state *state, struct drm_crtc *crtc)
   * automatically.
   *
   * Returns:
- *
   * 0 on success. -EBUSY when userspace schedules nonblocking commits too fast,
   * -ENOMEM on allocation failures and -EINTR when a signal is pending.
   */
@@ -3009,7 +3008,6 @@ EXPORT_SYMBOL(drm_atomic_helper_cleanup_planes);
   * don't pass the right state structures to the callbacks.
   *
   * Returns:
- *
   * Returns 0 on success. Can return -ERESTARTSYS when @stall is true and the
   * waiting for the previous commits has been interrupted.
   */
drivers/gpu/drm/drm_file.c +0 -7
index 714e42b05108..7beed6902208 100644
@@ -355,7 +355,6 @@ int drm_open_helper(struct file *filp, struct drm_minor *minor)
   * resources for it. It also calls the &drm_driver.open driver callback.
   *
   * RETURNS:
- *
   * 0 on success or negative errno value on failure.
   */
  int drm_open(struct inode *inode, struct file *filp)
@@ -417,7 +416,6 @@ void drm_lastclose(struct drm_device * dev)
   * DRM device also proceeds to call the &drm_driver.lastclose driver callback.
   *
   * RETURNS:
- *
   * Always succeeds and returns 0.
   */
  int drm_release(struct inode *inode, struct file *filp)
@@ -489,7 +487,6 @@ void drm_file_update_pid(struct drm_file *filp)
   * call the &drm_driver.lastclose driver callback.
   *
   * RETURNS:
- *
   * Always succeeds and returns 0.
   */
  int drm_release_noglobal(struct inode *inode, struct file *filp)
@@ -532,7 +529,6 @@ EXPORT_SYMBOL(drm_release_noglobal);
   * safety.
   *
   * RETURNS:
- *
   * Number of bytes read (always aligned to full events, and can be 0) or a
   * negative error code on failure.
   */
@@ -618,7 +614,6 @@ EXPORT_SYMBOL(drm_read);
   * See also drm_read().
   *
   * RETURNS:
- *
   * Mask of POLL flags indicating the current status of the file.
   */
  __poll_t drm_poll(struct file *filp, struct poll_table_struct *wait)
@@ -656,7 +651,6 @@ EXPORT_SYMBOL(drm_poll);
   * already hold &drm_device.event_lock.
   *
   * RETURNS:
- *
   * 0 on success or a negative error code on failure.
   */
  int drm_event_reserve_init_locked(struct drm_device *dev,
@@ -698,7 +692,6 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked);
   * drm_event_reserve_init_locked() instead.
   *
   * RETURNS:
- *
   * 0 on success or a negative error code on failure.
   */
  int drm_event_reserve_init(struct drm_device *dev,
drivers/gpu/drm/drm_gem.c +2 -5
index d4bbc5d109c8..149b8e25da5b 100644
@@ -689,7 +689,6 @@ static int objects_lookup(struct drm_file *filp, u32 *handle, int count,
   * For a single handle lookup, use drm_gem_object_lookup().
   *
   * Returns:
- *
   * @objs filled in with GEM object pointers. Returned GEM objects need to be
   * released with drm_gem_object_put(). -ENOENT is returned on a lookup
   * failure. 0 is returned on success.
@@ -737,12 +736,11 @@ EXPORT_SYMBOL(drm_gem_objects_lookup);
   * @filp: DRM file private date
   * @handle: userspace handle
   *
- * Returns:
+ * If looking up an array of handles, use drm_gem_objects_lookup().
   *
+ * Returns:
   * A reference to the object named by the handle if such exists on @filp, NULL
   * otherwise.
- *
- * If looking up an array of handles, use drm_gem_objects_lookup().
   */
  struct drm_gem_object *
  drm_gem_object_lookup(struct drm_file *filp, u32 handle)
@@ -763,7 +761,6 @@ EXPORT_SYMBOL(drm_gem_object_lookup);
   * @timeout: timeout value in jiffies or zero to return immediately
   *
   * Returns:
- *
   * Returns -ERESTARTSYS if interrupted, 0 if the wait timed out, or
   * greater than 0 on success.
   */
drivers/gpu/drm/drm_modes.c +0 -1
index 1a0890083aee..6ba167a33461 100644
@@ -539,7 +539,6 @@ static int fill_analog_mode(struct drm_device *dev,
   * to reach those resolutions.
   *
   * Returns:
- *
   * A pointer to the mode, allocated with drm_mode_create(). Returns NULL
   * on error.
   */
drivers/gpu/drm/drm_rect.c +0 -1
index 85c79a38c13a..492acce0516f 100644
@@ -85,7 +85,6 @@ static u32 clip_scaled(int src, int dst, int *clip)
   * factors from @src to @dst.
   *
   * RETURNS:
- *
   * %true if rectangle @dst is still visible after being clipped,
   * %false otherwise.
   */
drivers/gpu/drm/drm_vblank.c +0 -2
index cc3571e25a9a..6428b7975dd6 100644
@@ -686,7 +686,6 @@ EXPORT_SYMBOL(drm_calc_timestamping_constants);
   * drm_atomic_helper_calc_timestamping_constants().
   *
   * Returns:
- *
   * Returns true on success, and false on failure, i.e. when no accurate
   * timestamp could be acquired.
   */
@@ -831,7 +830,6 @@ EXPORT_SYMBOL(drm_crtc_vblank_helper_get_vblank_timestamp_internal);
   * drm_atomic_helper_calc_timestamping_constants().
   *
   * Returns:
- *
   * Returns true on success, and false on failure, i.e. when no accurate
   * timestamp could be acquired.
   */
drivers/gpu/drm/i915/gem/i915_gem_object.h +0 -1
index 5d7446a48ae7..3dc61cbd2e11 100644
@@ -89,7 +89,6 @@ __i915_gem_object_unset_pages(struct drm_i915_gem_object *obj);
   * @handle: userspace handle
   *
   * Returns:
- *
   * A pointer to the object named by the handle if such exists on @filp, NULL
   * otherwise. This object is only valid whilst under the RCU read lock, and
   * note carefully the object may be in the process of being destroyed.
drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c +0 -1
index 93bc1cc1ee7e..0ffba50981e3 100644
@@ -418,7 +418,6 @@ int __i915_vma_pin_fence(struct i915_vma *vma)
   * For an untiled surface, this removes any existing fence.
   *
   * Returns:
- *
   * 0 on success, negative error code on failure.
   */
  int i915_vma_pin_fence(struct i915_vma *vma)
drivers/gpu/drm/i915/i915_vma.h +0 -1
index e356dfb883d3..6a6be8048aa8 100644
@@ -389,7 +389,6 @@ void i915_vma_unpin_iomap(struct i915_vma *vma);
   * i915_vma_unpin_fence().
   *
   * Returns:
- *
   * True if the vma has a fence, false otherwise.
   */
  int __must_check i915_vma_pin_fence(struct i915_vma *vma);
Signature · 7 lines
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstrasse 146, 90461 Nuernberg, Germany
GF: Ivo Totev, Andrew Myers, Andrew McDonald, Boudien Moerman
HRB 36809 (AG Nuernberg)
#2 lore raw

Hi Renjun

Am 26.08.24 um 16:26 schrieb Thomas Zimmermann:

Quoted 12 lines

Am 24.08.24 um 10:36 schrieb renjun wang:

Quoted 9 lines

The blank line between title "Returns:" and detail description is not allowed, otherwise the title will goes under the description block in generated .html file after running make htmldocs.

There are a few examples for current kerneldoc:
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_crtc_commit_wait

https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_atomic_get_crtc_state

Quoted 8 lines
Quoted 4 lines

https://www.kernel.org/doc/html/latest/gpu/i915.html#c.i915_vma_pin_fence

I'll add this patch and the other doc fix to the drm-misc tree. Thanks a lot for the fixes.

I took the liberty to slightly change the commit messages. The links are now given in Link tags and point to stable URLs.

Best regards
Thomas

Quoted 313 lines

Best regards
Thomas

Quoted 308 lines

---
  drivers/gpu/drm/display/drm_dp_mst_topology.c | 4 ---- drivers/gpu/drm/drm_atomic.c                  | 6 ------ drivers/gpu/drm/drm_atomic_helper.c           | 2 -- drivers/gpu/drm/drm_file.c                    | 7 ------- drivers/gpu/drm/drm_gem.c                     | 7 ++----- drivers/gpu/drm/drm_modes.c                   | 1 - drivers/gpu/drm/drm_rect.c                    | 1 - drivers/gpu/drm/drm_vblank.c                  | 2 -- drivers/gpu/drm/i915/gem/i915_gem_object.h    | 1 - drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c  | 1 - drivers/gpu/drm/i915/i915_vma.h               | 1 -

  11 files changed, 2 insertions(+), 31 deletions(-)
drivers/gpu/drm/display/drm_dp_mst_topology.c +0 -4
index fc2ceae61db2..e68d23997d53 100644
@@ -5569,7 +5569,6 @@ EXPORT_SYMBOL(drm_dp_mst_atomic_check_mgr);
    * drm_dp_atomic_release_time_slots()
    *
    * Returns:
- *
    * 0 if the new state is valid, negative error code otherwise.
    */
   int drm_dp_mst_atomic_check(struct drm_atomic_state *state)
@@ -5606,7 +5605,6 @@ EXPORT_SYMBOL(drm_dp_mst_topology_state_funcs);
    * topology object.
    *
    * RETURNS:
- *
    * The MST topology state or error pointer.
    */
   struct drm_dp_mst_topology_state *drm_atomic_get_mst_topology_state(struct drm_atomic_state *state,
@@ -5626,7 +5624,6 @@ EXPORT_SYMBOL(drm_atomic_get_mst_topology_state);
    * topology object.
    *
    * Returns:
- *
    * The old MST topology state, or NULL if there's no topology state for this MST mgr
    * in the global atomic state
    */
@@ -5651,7 +5648,6 @@ 
 EXPORT_SYMBOL(drm_atomic_get_old_mst_topology_state);
    * topology object.
    *
    * Returns:
- *
    * The new MST topology state, or NULL if there's no topology state for this MST mgr
    * in the global atomic state

   */

drivers/gpu/drm/drm_atomic.c +0 -3
index 6e516c39a372..0fc99da93afe 100644
@@ -63,7 +63,6 @@ EXPORT_SYMBOL(__drm_crtc_commit_free);
    * hardware and flipped to.
    *
    * Returns:
- *
    * 0 on success, a negative error code otherwise.
    */
   int drm_crtc_commit_wait(struct drm_crtc_commit *commit)
@@ -337,7 +336,6 @@ EXPORT_SYMBOL(__drm_atomic_state_free);
    * not created by userspace through an IOCTL call.
    *
    * Returns:
- *
    * Either the allocated state or the error code encoded into the pointer. When
    * the error is EDEADLK then the w/w mutex code has detected a deadlock and the
    * entire atomic sequence must be restarted. All other errors are fatal.
@@ -518,7 +516,6 @@ static int drm_atomic_connector_check(struct 
 drm_connector *connector,
    * is consistent.
    *
    * Returns:
- *
    * Either the allocated state or the error code encoded into the pointer. When
    * the error is EDEADLK then the w/w mutex code has detected a deadlock and the

   * entire atomic sequence must be restarted. All other errors are fatal.

drivers/gpu/drm/drm_atomic.c +0 -1
@@ -828,7 +825,6 @@ EXPORT_SYMBOL(drm_atomic_private_obj_fini);
    * object lock to make sure that the state is consistent.
    *
    * RETURNS:
- *
    * Either the allocated state or the error code encoded into a pointer.
    */

  struct drm_private_state *

drivers/gpu/drm/drm_atomic.c +0 -1
@@ -1061,7 +1057,6 @@ 
 EXPORT_SYMBOL(drm_atomic_get_new_crtc_for_encoder);
    * make sure that the state is consistent.
    *
    * Returns:
- *
    * Either the allocated state or the error code encoded into the pointer. When
    * the error is EDEADLK then the w/w mutex code has detected a deadlock and the

   * entire atomic sequence must be restarted. All other errors are fatal.

drivers/gpu/drm/drm_atomic.c +0 -1
@@ -1169,7 +1164,6 @@ static void 
 drm_atomic_connector_print_state(struct drm_printer *p,
    * state is consistent.
    *
    * Returns:
- *
    * Either the allocated state or the error code encoded into the pointer. When
    * the error is EDEADLK then the w/w mutex code has detected a deadlock and the

   * entire atomic sequence must be restarted.

drivers/gpu/drm/drm_atomic_helper.c +0 -1
index fb97b51b38f1..43cdf39019a4 100644
@@ -2266,7 +2266,6 @@ crtc_or_fake_commit(struct drm_atomic_state 
 *state, struct drm_crtc *crtc)
    * automatically.
    *
    * Returns:
- *
    * 0 on success. -EBUSY when userspace schedules nonblocking commits too fast,
    * -ENOMEM on allocation failures and -EINTR when a signal is pending.

   */

drivers/gpu/drm/drm_atomic_helper.c +0 -1
@@ -3009,7 +3008,6 @@ EXPORT_SYMBOL(drm_atomic_helper_cleanup_planes);
    * don't pass the right state structures to the callbacks.
    *
    * Returns:
- *
    * Returns 0 on success. Can return -ERESTARTSYS when @stall is true and the
    * waiting for the previous commits has been interrupted.
    */
drivers/gpu/drm/drm_file.c +0 -1
index 714e42b05108..7beed6902208 100644
@@ -355,7 +355,6 @@ int drm_open_helper(struct file *filp, struct 
 drm_minor *minor)
    * resources for it. It also calls the &drm_driver.open driver callback.
    *
    * RETURNS:
- *
    * 0 on success or negative errno value on failure.
    */

  int drm_open(struct inode *inode, struct file *filp)

drivers/gpu/drm/drm_file.c +0 -6
@@ -417,7 +416,6 @@ void drm_lastclose(struct drm_device * dev)
    * DRM device also proceeds to call the &drm_driver.lastclose driver callback.
    *
    * RETURNS:
- *
    * Always succeeds and returns 0.
    */
   int drm_release(struct inode *inode, struct file *filp)
@@ -489,7 +487,6 @@ void drm_file_update_pid(struct drm_file *filp)
    * call the &drm_driver.lastclose driver callback.
    *
    * RETURNS:
- *
    * Always succeeds and returns 0.
    */
   int drm_release_noglobal(struct inode *inode, struct file *filp)
@@ -532,7 +529,6 @@ EXPORT_SYMBOL(drm_release_noglobal);
    * safety.
    *
    * RETURNS:
- *
    * Number of bytes read (always aligned to full events, and can be 0) or a
    * negative error code on failure.
    */
@@ -618,7 +614,6 @@ EXPORT_SYMBOL(drm_read);
    * See also drm_read().
    *
    * RETURNS:
- *
    * Mask of POLL flags indicating the current status of the file.
    */
   __poll_t drm_poll(struct file *filp, struct poll_table_struct *wait)
@@ -656,7 +651,6 @@ EXPORT_SYMBOL(drm_poll);
    * already hold &drm_device.event_lock.
    *
    * RETURNS:
- *
    * 0 on success or a negative error code on failure.
    */
   int drm_event_reserve_init_locked(struct drm_device *dev,
@@ -698,7 +692,6 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked);
    * drm_event_reserve_init_locked() instead.
    *
    * RETURNS:
- *
    * 0 on success or a negative error code on failure.
    */
   int drm_event_reserve_init(struct drm_device *dev,
drivers/gpu/drm/drm_gem.c +0 -1
index d4bbc5d109c8..149b8e25da5b 100644
@@ -689,7 +689,6 @@ static int objects_lookup(struct drm_file *filp, 
 u32 *handle, int count,
    * For a single handle lookup, use drm_gem_object_lookup().
    *
    * Returns:
- *
    * @objs filled in with GEM object pointers. Returned GEM objects need to be
    * released with drm_gem_object_put(). -ENOENT is returned on a lookup

   * failure. 0 is returned on success.

drivers/gpu/drm/drm_gem.c +2 -1
@@ -737,12 +736,11 @@ EXPORT_SYMBOL(drm_gem_objects_lookup);
    * @filp: DRM file private date
    * @handle: userspace handle
    *
- * Returns:
+ * If looking up an array of handles, use drm_gem_objects_lookup().
    *
+ * Returns:
    * A reference to the object named by the handle if such exists on 

@filp, NULL
   * otherwise.
- *
- * If looking up an array of handles, use drm_gem_objects_lookup(). */
  struct drm_gem_object *
  drm_gem_object_lookup(struct drm_file *filp, u32 handle)

drivers/gpu/drm/drm_gem.c +0 -1
@@ -763,7 +761,6 @@ EXPORT_SYMBOL(drm_gem_object_lookup);
    * @timeout: timeout value in jiffies or zero to return immediately
    *
    * Returns:
- *
    * Returns -ERESTARTSYS if interrupted, 0 if the wait timed out, or
    * greater than 0 on success.
    */
drivers/gpu/drm/drm_modes.c +0 -1
index 1a0890083aee..6ba167a33461 100644
@@ -539,7 +539,6 @@ static int fill_analog_mode(struct drm_device *dev,
    * to reach those resolutions.
    *
    * Returns:
- *
    * A pointer to the mode, allocated with drm_mode_create(). Returns NULL
    * on error.
    */
drivers/gpu/drm/drm_rect.c +0 -1
index 85c79a38c13a..492acce0516f 100644
@@ -85,7 +85,6 @@ static u32 clip_scaled(int src, int dst, int *clip)
    * factors from @src to @dst.
    *
    * RETURNS:
- *
    * %true if rectangle @dst is still visible after being clipped,
    * %false otherwise.
    */
drivers/gpu/drm/drm_vblank.c +0 -2
index cc3571e25a9a..6428b7975dd6 100644
@@ -686,7 +686,6 @@ EXPORT_SYMBOL(drm_calc_timestamping_constants);
    * drm_atomic_helper_calc_timestamping_constants().
    *
    * Returns:
- *
    * Returns true on success, and false on failure, i.e. when no accurate
    * timestamp could be acquired.
    */
@@ -831,7 +830,6 @@ 
 EXPORT_SYMBOL(drm_crtc_vblank_helper_get_vblank_timestamp_internal);
    * drm_atomic_helper_calc_timestamping_constants().
    *
    * Returns:
- *
    * Returns true on success, and false on failure, i.e. when no accurate
    * timestamp could be acquired.

   */

drivers/gpu/drm/i915/gem/i915_gem_object.h +0 -1
index 5d7446a48ae7..3dc61cbd2e11 100644
@@ -89,7 +89,6 @@ __i915_gem_object_unset_pages(struct 
 drm_i915_gem_object *obj);
    * @handle: userspace handle
    *
    * Returns:
- *
    * A pointer to the object named by the handle if such exists on 

@filp, NULL
   * otherwise. This object is only valid whilst under the RCU read lock, and
   * note carefully the object may be in the process of being destroyed.

drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c +0 -1
index 93bc1cc1ee7e..0ffba50981e3 100644
@@ -418,7 +418,6 @@ int __i915_vma_pin_fence(struct i915_vma *vma)
    * For an untiled surface, this removes any existing fence.
    *
    * Returns:
- *
    * 0 on success, negative error code on failure.
    */
   int i915_vma_pin_fence(struct i915_vma *vma)
drivers/gpu/drm/i915/i915_vma.h +0 -1
index e356dfb883d3..6a6be8048aa8 100644
@@ -389,7 +389,6 @@ void i915_vma_unpin_iomap(struct i915_vma *vma);
    * i915_vma_unpin_fence().
    *
    * Returns:
- *
    * True if the vma has a fence, false otherwise.
    */
   int __must_check i915_vma_pin_fence(struct i915_vma *vma);
Signature · 7 lines
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstrasse 146, 90461 Nuernberg, Germany
GF: Ivo Totev, Andrew Myers, Andrew McDonald, Boudien Moerman
HRB 36809 (AG Nuernberg)
#3 lore raw
In reply to renjun wang

Hi Renjun,

Quoted 10 lines · renjun wang

The blank line between title "Returns:" and detail description is not allowed, otherwise the title will goes under the description block in generated .html file after running make htmldocs.

There are a few examples for current kerneldoc:
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_crtc_commit_wait
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_atomic_get_crtc_state
https://www.kernel.org/doc/html/latest/gpu/i915.html#c.i915_vma_pin_fence

Quoted 13 lines
---
 drivers/gpu/drm/display/drm_dp_mst_topology.c | 4 ----
 drivers/gpu/drm/drm_atomic.c                  | 6 ------
 drivers/gpu/drm/drm_atomic_helper.c           | 2 --
 drivers/gpu/drm/drm_file.c                    | 7 -------
 drivers/gpu/drm/drm_gem.c                     | 7 ++-----
 drivers/gpu/drm/drm_modes.c                   | 1 -
 drivers/gpu/drm/drm_rect.c                    | 1 -
 drivers/gpu/drm/drm_vblank.c                  | 2 --
 drivers/gpu/drm/i915/gem/i915_gem_object.h    | 1 -
 drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c  | 1 -
 drivers/gpu/drm/i915/i915_vma.h               | 1 -
 11 files changed, 2 insertions(+), 31 deletions(-)

next time, please, split the series so that each component goes to the right branch.

Andi

#4 lore raw

Hi

Am 27.08.24 um 00:11 schrieb Andi Shyti:

Quoted 26 lines

Hi Renjun,

Quoted 10 lines · renjun wang

The blank line between title "Returns:" and detail description is not allowed, otherwise the title will goes under the description block in generated .html file after running make htmldocs.

There are a few examples for current kerneldoc:
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_crtc_commit_wait
https://www.kernel.org/doc/html/latest/gpu/drm-kms.html#c.drm_atomic_get_crtc_state
https://www.kernel.org/doc/html/latest/gpu/i915.html#c.i915_vma_pin_fence

Quoted 13 lines
---
  drivers/gpu/drm/display/drm_dp_mst_topology.c | 4 ----
  drivers/gpu/drm/drm_atomic.c                  | 6 ------
  drivers/gpu/drm/drm_atomic_helper.c           | 2 --
  drivers/gpu/drm/drm_file.c                    | 7 -------
  drivers/gpu/drm/drm_gem.c                     | 7 ++-----
  drivers/gpu/drm/drm_modes.c                   | 1 -
  drivers/gpu/drm/drm_rect.c                    | 1 -
  drivers/gpu/drm/drm_vblank.c                  | 2 --
  drivers/gpu/drm/i915/gem/i915_gem_object.h    | 1 -
  drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c  | 1 -
  drivers/gpu/drm/i915/i915_vma.h               | 1 -
  11 files changed, 2 insertions(+), 31 deletions(-)
Quoted 2 lines

next time, please, split the series so that each component goes to the right branch.

My fault. Apologies if I crossed a line by just merging it into drm-misc. It's just doc syntax, so I didn't think it was a big deal.

Best regards
Thomas

Quoted 2 lines

Andi

Signature · 7 lines
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstrasse 146, 90461 Nuernberg, Germany
GF: Ivo Totev, Andrew Myers, Andrew McDonald, Boudien Moerman
HRB 36809 (AG Nuernberg)
maintainer
#5 lore raw
Quoted 2 lines · Thomas Zimmermann

My fault. Apologies if I crossed a line by just merging it into drm-misc. It's just doc syntax, so I didn't think it was a big deal.

No worries, retrospective ack.

BR,
Jani.

Signature · 1 line
Jani Nikula, Intel