[PATCH] drm/doc: document drm_event and its types

[Pekka Paalanen]

On Mon, 17 Jul 2023 09:30:39 +0000
Simon Ser <contact at 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 at emersion.fr>
> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> Cc: Pekka Paalanen <pekka.paalanen at 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 at collabora.com>


Thanks,
pq