Commit f633a206 authored by Simon Ser's avatar Simon Ser
Browse files

drm: document uAPI page-flip flags 



Document flags accepted by the page-flip and atomic IOCTLs.

v2 (Pekka):
- Mention DRM_EVENT_FLIP_COMPLETE in DRM_MODE_PAGE_FLIP_EVENT docs.
- Expand DRM_MODE_ATOMIC_NONBLOCK and DRM_MODE_ATOMIC_ALLOW_MODESET
  description.
v3:
- Fix struct field ref syntax (Daniel)
- Clarify when artifacts are no longer displayed (Daniel)
- Add note about sinks deciding to show artifacts on their own (Pekka, Daniel)
v4:
- Fix typo (Pekka)

Signed-off-by: default avatarSimon Ser <contact@emersion.fr>
Reviewed-by: default avatarPekka Paalanen <pekka.paalanen@collabora.com>
Acked-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Cc: Ville Syrjala <ville.syrjala@linux.intel.com>
Link: https://patchwork.freedesktop.org/patch/505107/
parent 96c92551

include/uapi/drm/drm_mode.h

+62 −1
Original line number Diff line number Diff line
@@ -935,12 +935,31 @@ struct hdr_output_metadata { 
	};

};



/**

 * DRM_MODE_PAGE_FLIP_EVENT

 *

 * Request that the kernel sends back a vblank event (see

 * struct drm_event_vblank) with the &DRM_EVENT_FLIP_COMPLETE type when the

 * page-flip is done.

 */

#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.

 */

#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 +1053,53 @@ 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. The &DRM_IOCTL_MODE_ATOMIC

 * IOCTL returns immediately instead of waiting for the changes to be applied

 * in hardware. Note, the driver will still check that the update can be

 * applied before retuning.

 */

#define DRM_MODE_ATOMIC_NONBLOCK  0x0200

/**

 * DRM_MODE_ATOMIC_ALLOW_MODESET

 *

 * Allow the update to result in temporary or transient visible artifacts while

 * the update is being applied. Applying the update may also take significantly

 * more time than a page flip. All visual artifacts will disappear by the time

 * the update is completed, as signalled through the vblank event's timestamp

 * (see struct drm_event_vblank).

 *

 * This flag must be set when the KMS update might cause visible artifacts.

 * Without this flag such KMS update will return a EINVAL error. What kind of

 * update may cause visible artifacts depends on the driver and the hardware.

 * User-space 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.

 *

 * To the best of the driver's knowledge, visual artifacts are guaranteed to

 * not appear when this flag is not set. Some sinks might display visual

 * artifacts outside of the driver's control.

 */

#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 |\