[igt-dev] [PATCH i-g-t 2/2] lib/igt_kms: Update documentation for __igt_vblank_wait()

[Daniel Vetter]

On Thu, Feb 04, 2021 at 06:15:33PM +0530, Sumera Priyadarsini wrote:
> Add documentation for the __igt_vblank_wait() helper function.
> Update documentation for igt_wait_for_vblank_count() and
> igt_wait_for_vblank() to reflect the refactor accordingly.
> 
> Signed-off-by: Sumera Priyadarsini <sylphrenadin at gmail.com>
> ---
>  lib/igt_kms.c | 34 +++++++++++++++++++++++-----------
>  1 file changed, 23 insertions(+), 11 deletions(-)
> 
> diff --git a/lib/igt_kms.c b/lib/igt_kms.c
> index 08d429a8..e6854472 100644
> --- a/lib/igt_kms.c
> +++ b/lib/igt_kms.c
> @@ -4190,6 +4190,23 @@ void igt_output_set_writeback_fb(igt_output_t *output, struct igt_fb *fb)
>  					  (ptrdiff_t)&output->writeback_out_fence_fd);
>  }
>  
> +/**
> + * __igt_vblank_wait:
> + * @drm_fd: A drm file descriptor
> + * @crtc_offset: offset of the crtc in drmModeRes.crtcs
> + * @count: Number of vblanks to wait on
> + *
> + * Waits for a given number of vertical blank intervals
> + *
> + * In DRM, 'Pipe', as understood by DRM_IOCTL_WAIT_VBLANK,
> + * is actually an offset of crtc in drmModeRes.crtcs
> + * and it has nothing to do with a hardware concept of a pipe.
> + * They can match but don't have to in case of DRM lease or
> + * non-contiguous pipes.
> + *
> + * To make thing clear we are calling DRM_IOCTL_WAIT_VBLANK's 'pipe'
> + * a crtc_offset.

We keep docs on the public functions, not the static (i.e. internal) ones.
So this doesn't make much sense, hence I'll skip this one.
-Daniel

> + */
>  static int __igt_vblank_wait(int drm_fd, int crtc_offset, int count)
>  {
>  	drmVBlank wait_vbl;
> @@ -4210,16 +4227,10 @@ static int __igt_vblank_wait(int drm_fd, int crtc_offset, int count)
>   * @crtc_offset: offset of the crtc in drmModeRes.crtcs
>   * @count: Number of vblanks to wait on
>   *
> - * Waits for a given number of vertical blank intervals
> - *
> - * In DRM, 'Pipe', as understood by DRM_IOCTL_WAIT_VBLANK,
> - * is actually an offset of crtc in drmModeRes.crtcs
> - * and it has nothing to do with a hardware concept of a pipe.
> - * They can match but don't have to in case of DRM lease or
> - * non-contiguous pipes.
> + * See the #__igt_vblank_wait helper for more details
>   *
> - * To make thing clear we are calling DRM_IOCTL_WAIT_VBLANK's 'pipe'
> - * a crtc_offset.
> + * Wrapper function for __igt_vblank_wait() to wait for a
> + * given number of vertical blank intervals.
>   */
>  void igt_wait_for_vblank_count(int drm_fd, int crtc_offset, int count)
>  {
> @@ -4231,9 +4242,10 @@ void igt_wait_for_vblank_count(int drm_fd, int crtc_offset, int count)
>   * @drm_fd: A drm file descriptor
>   * @crtc_offset: offset of a crtc in drmModeRes.crtcs
>   *
> - * See #igt_wait_for_vblank_count for more details
> + * See the #__igt_vblank_wait helper for more details
>   *
> - * Waits for 1 vertical blank intervals
> + * Wrapper function for __igt_vblank_wait() to wait for a
> + * single vertical blank interval.
>   */
>  void igt_wait_for_vblank(int drm_fd, int crtc_offset)
>  {
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch