drm: document uAPI page-flip flags

[Pekka Paalanen]

On Wed, 24 Aug 2022 17:45:06 +0000
Simon Ser <contact at emersion.fr> wrote:

> Document flags accepted by the page-flip and atomic IOCTLs.
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> ---
>  include/uapi/drm/drm_mode.h | 44 ++++++++++++++++++++++++++++++++++++-
>  1 file changed, 43 insertions(+), 1 deletion(-)
> 
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index fa953309d9ce..e1b04ffd54c3 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -935,12 +935,30 @@ struct hdr_output_metadata {
>  	};
>  };
>  
> +/**
> + * DRM_MODE_PAGE_FLIP_EVENT
> + *
> + * Request that the kernel sends back a vblank event (see
> + * struct drm_event_vblank) when the page-flip is done.

...with type = DRM_EVENT_FLIP_COMPLETE?

This was a bit new to me, because libdrm abstracts vblank and pageflip
events into different APIs.

> + */
>  #define DRM_MODE_PAGE_FLIP_EVENT 0x01
> +/**
> + * DRM_MODE_PAGE_FLIP_ASYNC
> + *
> + * Request that the page-flip is performed as soon as possible, ie. with no
> + * delay due to waiting for vblank. This may cause tearing to be visible on
> + * the screen.

Btw. does the kernel fail the flip if the driver does not support async?
Or does it silently fall back to sync flip?
Asking for both legacy and atomic APIs.

> + */
>  #define DRM_MODE_PAGE_FLIP_ASYNC 0x02
>  #define DRM_MODE_PAGE_FLIP_TARGET_ABSOLUTE 0x4
>  #define DRM_MODE_PAGE_FLIP_TARGET_RELATIVE 0x8
>  #define DRM_MODE_PAGE_FLIP_TARGET (DRM_MODE_PAGE_FLIP_TARGET_ABSOLUTE | \
>  				   DRM_MODE_PAGE_FLIP_TARGET_RELATIVE)
> +/**
> + * DRM_MODE_PAGE_FLIP_FLAGS
> + *
> + * Bitmask of flags suitable for &drm_mode_crtc_page_flip_target.flags.
> + */
>  #define DRM_MODE_PAGE_FLIP_FLAGS (DRM_MODE_PAGE_FLIP_EVENT | \
>  				  DRM_MODE_PAGE_FLIP_ASYNC | \
>  				  DRM_MODE_PAGE_FLIP_TARGET)
> @@ -1034,11 +1052,35 @@ struct drm_mode_destroy_dumb {
>  	__u32 handle;
>  };
>  
> -/* page-flip flags are valid, plus: */
> +/**
> + * DRM_MODE_ATOMIC_TEST_ONLY
> + *
> + * Do not apply the atomic commit, instead check whether the hardware supports
> + * this configuration.
> + *
> + * See drm_mode_config_funcs.atomic_check for more details on test-only
> + * commits.
> + */
>  #define DRM_MODE_ATOMIC_TEST_ONLY 0x0100
> +/**
> + * DRM_MODE_ATOMIC_NONBLOCK
> + *
> + * Do not block while applying the atomic commit.

Maybe add something like:

	The atomic commit ioctl returns immediately instead of waiting
	for the changes to be applied in hardware.

> + */
>  #define DRM_MODE_ATOMIC_NONBLOCK  0x0200
> +/**
> + * DRM_MODE_ATOMIC_ALLOW_MODESET
> + *
> + * Allow the update to result in visible artifacts such as a black screen.

Maybe add:

	...temporary or transient visible artifacts while the update is
	being applied. Applying the update may also take significantly
	more time than a page flip. The visual artifacts will not
	appear after the update is completed.

	This flag must be set when the KMS update might cause visible
	artifacts. Without this flag such KMS update will return EINVAL
	error. What kind of updates may cause visible artifacts depends
	on the driver and the hardware. Userspace that needs to know
	beforehand if an update might cause visible artifacts can use
	DRM_MODE_ATOMIC_TEST_ONLY without DRM_MODE_ATOMIC_ALLOW_MODESET
	to see if it fails.

	Visual artifacts are guaranteed to not appear when this flag is
	not set.

That "artifacts will not appear after the update is completed" is a bit
awkward, because when this commit completes and triggers the completion
event (if requested), the visual artifacts might still be on screen, but
as soon as the scanout cycle that just started finishes, all artifacts
are gone for good. Isn't that how it works?

Or does the kernel wait with the completion event until a good picture
has been fully scanned out at least once? I'd expect not.

> + */
>  #define DRM_MODE_ATOMIC_ALLOW_MODESET 0x0400
>  
> +/**
> + * DRM_MODE_ATOMIC_FLAGS
> + *
> + * Bitfield of flags accepted by the &DRM_IOCTL_MODE_ATOMIC IOCTL in
> + * &drm_mode_atomic.flags.
> + */
>  #define DRM_MODE_ATOMIC_FLAGS (\
>  		DRM_MODE_PAGE_FLIP_EVENT |\
>  		DRM_MODE_PAGE_FLIP_ASYNC |\


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20220826/1a7a5a37/attachment.sig>