| Message ID | 20220829153957.153745-1-contact@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] drm: document uAPI page-flip flags | expand |
On Mon, 29 Aug 2022 15:40:01 +0000 Simon Ser <contact@emersion.fr> wrote: > 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. > > Signed-off-by: Simon Ser <contact@emersion.fr> > Cc: Daniel Vetter <daniel.vetter@ffwll.ch> > Cc: Pekka Paalanen <ppaalanen@gmail.com> > Cc: Ville Syrjala <ville.syrjala@linux.intel.com> > --- > include/uapi/drm/drm_mode.h | 60 ++++++++++++++++++++++++++++++++++++- > 1 file changed, 59 insertions(+), 1 deletion(-) > > diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h > index fa953309d9ce..fa26bda6ffb3 100644 > --- a/include/uapi/drm/drm_mode.h > +++ b/include/uapi/drm/drm_mode.h > @@ -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,50 @@ 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. 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 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. > + * > + * Visual artifacts are guaranteed to not appear when this flag is not set. Hi Simon, all this looks good to me, aside from the question of whether ALLOW_MODESET should be talking about visual artifacts or only about interrupting the video signal or something. Thanks, pq > + */ > #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 |\
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h index fa953309d9ce..fa26bda6ffb3 100644 --- a/include/uapi/drm/drm_mode.h +++ b/include/uapi/drm/drm_mode.h @@ -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,50 @@ 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. 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 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. + * + * Visual artifacts are guaranteed to not appear when this flag is not set. + */ #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 |\
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. Signed-off-by: Simon Ser <contact@emersion.fr> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Pekka Paalanen <ppaalanen@gmail.com> Cc: Ville Syrjala <ville.syrjala@linux.intel.com> --- include/uapi/drm/drm_mode.h | 60 ++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-)