Commit 2ff4f6d4 authored by Simon Ser's avatar Simon Ser
Browse files

drm/doc: document drm_event and its types 



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: default avatarSimon Ser <contact@emersion.fr>
Acked-by: default avatarPekka Paalanen <pekka.paalanen@collabora.com>
Acked-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20230717093032.600773-1-contact@emersion.fr
parent f1bfcad6

include/uapi/drm/drm.h

+35 −10
Original line number Diff line number Diff line
@@ -1202,25 +1202,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 {