drm: Fix kerneldoc for "Returns" section
Subsystems (3)
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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
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_fenceSigned-off-by renjun wang <[email protected]>
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@@ -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@@ -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@@ -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@@ -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@@ -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@@ -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@@ -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@@ -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@@ -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@@ -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@@ -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)
Thomas Zimmermann
maintainerHi 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_waithttps://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
Signed-off-by renjun wang <[email protected]>Reviewed-by Thomas Zimmermann <[email protected]>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
ThomasQuoted 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@@ -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@@ -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(structdrm_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@@ -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@@ -355,7 +355,6 @@ int drm_open_helper(struct file *filp, structdrm_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@@ -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, usedrm_gem_objects_lookup(). */
structdrm_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@@ -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@@ -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@@ -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@@ -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@@ -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@@ -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)
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_fenceSigned-off-by renjun wang <[email protected]>
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
Thomas Zimmermann
maintainerHi
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_fenceSigned-off-by renjun wang <[email protected]>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)
Jani Nikula
maintainerQuoted 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