| Message ID | 20230717093032.600773-1-contact@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/doc: document drm_event and its types | expand |
On Mon, 17 Jul 2023 09:30:39 +0000 Simon Ser <contact@emersion.fr> wrote: > Convert struct drm_event to a kernel doc comment. Link to the > generic DRM event types. Add a basic description of each event > type. > > Signed-off-by: Simon Ser <contact@emersion.fr> > Cc: Daniel Vetter <daniel.vetter@ffwll.ch> > Cc: Pekka Paalanen <pekka.paalanen@collabora.com> > --- > include/uapi/drm/drm.h | 45 ++++++++++++++++++++++++++++++++---------- > 1 file changed, 35 insertions(+), 10 deletions(-) > > diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h > index a87bbbbca2d4..7cc6bf9bec43 100644 > --- a/include/uapi/drm/drm.h > +++ b/include/uapi/drm/drm.h > @@ -1180,25 +1180,50 @@ extern "C" { > #define DRM_COMMAND_BASE 0x40 > #define DRM_COMMAND_END 0xA0 > > -/* > - * Header for events written back to userspace on the drm fd. The > - * type defines the type of event, the length specifies the total > - * length of the event (including the header), and user_data is > - * typically a 64 bit value passed with the ioctl that triggered the > - * event. A read on the drm fd will always only return complete The user_data doc there seems lost. It would be more at home with the payload structs, anyway. > - * events, that is, if for example the read buffer is 100 bytes, and > - * there are two 64 byte events pending, only one will be returned. > +/** > + * struct drm_event - Header for DRM events > + * @type: event type. > + * @length: total number of payload bytes (including header). > * > - * Event types 0 - 0x7fffffff are generic drm events, 0x80000000 and > - * up are chipset specific. > + * This struct is a header for events written back to user-space on the DRM FD. > + * A read on the DRM FD will always only return complete events: e.g. if the > + * read buffer is 100 bytes large and there are two 64 byte events pending, > + * only one will be returned. > + * > + * Event types 0 - 0x7fffffff are generic DRM events, 0x80000000 and > + * up are chipset specific. Generic DRM events include &DRM_EVENT_VBLANK, > + * &DRM_EVENT_FLIP_COMPLETE and &DRM_EVENT_CRTC_SEQUENCE. > */ > struct drm_event { > __u32 type; > __u32 length; > }; > > +/** > + * DRM_EVENT_VBLANK - vertical blanking event > + * > + * This event is sent in response to &DRM_IOCTL_WAIT_VBLANK with the > + * &_DRM_VBLANK_EVENT flag set. > + * > + * The event payload is a struct drm_event_vblank. > + */ > #define DRM_EVENT_VBLANK 0x01 > +/** > + * DRM_EVENT_FLIP_COMPLETE - page-flip completion event > + * > + * This event is sent in response to an atomic commit or legacy page-flip with > + * the &DRM_MODE_PAGE_FLIP_EVENT flag set. > + * > + * The event payload is a struct drm_event_vblank. > + */ > #define DRM_EVENT_FLIP_COMPLETE 0x02 > +/** > + * DRM_EVENT_CRTC_SEQUENCE - CRTC sequence event > + * > + * This event is sent in response to &DRM_IOCTL_CRTC_QUEUE_SEQUENCE. > + * > + * The event payload is a struct drm_event_crtc_sequence. > + */ > #define DRM_EVENT_CRTC_SEQUENCE 0x03 > > struct drm_event_vblank { Looks good. Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com> Thanks, pq
diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h index a87bbbbca2d4..7cc6bf9bec43 100644 --- a/include/uapi/drm/drm.h +++ b/include/uapi/drm/drm.h @@ -1180,25 +1180,50 @@ extern "C" { #define DRM_COMMAND_BASE 0x40 #define DRM_COMMAND_END 0xA0 -/* - * Header for events written back to userspace on the drm fd. The - * type defines the type of event, the length specifies the total - * length of the event (including the header), and user_data is - * typically a 64 bit value passed with the ioctl that triggered the - * event. A read on the drm fd will always only return complete - * events, that is, if for example the read buffer is 100 bytes, and - * there are two 64 byte events pending, only one will be returned. +/** + * struct drm_event - Header for DRM events + * @type: event type. + * @length: total number of payload bytes (including header). * - * Event types 0 - 0x7fffffff are generic drm events, 0x80000000 and - * up are chipset specific. + * This struct is a header for events written back to user-space on the DRM FD. + * A read on the DRM FD will always only return complete events: e.g. if the + * read buffer is 100 bytes large and there are two 64 byte events pending, + * only one will be returned. + * + * Event types 0 - 0x7fffffff are generic DRM events, 0x80000000 and + * up are chipset specific. Generic DRM events include &DRM_EVENT_VBLANK, + * &DRM_EVENT_FLIP_COMPLETE and &DRM_EVENT_CRTC_SEQUENCE. */ struct drm_event { __u32 type; __u32 length; }; +/** + * DRM_EVENT_VBLANK - vertical blanking event + * + * This event is sent in response to &DRM_IOCTL_WAIT_VBLANK with the + * &_DRM_VBLANK_EVENT flag set. + * + * The event payload is a struct drm_event_vblank. + */ #define DRM_EVENT_VBLANK 0x01 +/** + * DRM_EVENT_FLIP_COMPLETE - page-flip completion event + * + * This event is sent in response to an atomic commit or legacy page-flip with + * the &DRM_MODE_PAGE_FLIP_EVENT flag set. + * + * The event payload is a struct drm_event_vblank. + */ #define DRM_EVENT_FLIP_COMPLETE 0x02 +/** + * DRM_EVENT_CRTC_SEQUENCE - CRTC sequence event + * + * This event is sent in response to &DRM_IOCTL_CRTC_QUEUE_SEQUENCE. + * + * The event payload is a struct drm_event_crtc_sequence. + */ #define DRM_EVENT_CRTC_SEQUENCE 0x03 struct drm_event_vblank {
Convert struct drm_event to a kernel doc comment. Link to the generic DRM event types. Add a basic description of each event type. Signed-off-by: Simon Ser <contact@emersion.fr> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Pekka Paalanen <pekka.paalanen@collabora.com> --- include/uapi/drm/drm.h | 45 ++++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 10 deletions(-)