drm/doc: document drm_event and its types
Subsystems (2)
PATCH 1/1 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 Simon Ser <[email protected]>
Cc Daniel Vetter <[email protected]>
Cc Pekka Paalanen <[email protected]>
--- include/uapi/drm/drm.h | 45 ++++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 10 deletions(-)
include/uapi/drm/drm.h +35 -10
@@ -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 0x03struct drm_event_vblank {
Signature · 1 line
2.41.0
Quoted 16 lines · On Mon, 17 Jul 2023 09:30:39 +0000 Simon Ser <[email protected]> wrote:
Convert struct
drm_eventto a kernel doc comment. Link to the generic DRM event types. Add a basic description of each event type.Signed-off-by Simon Ser <[email protected]>Cc Daniel Vetter <[email protected]>Cc Pekka Paalanen <[email protected]>--- include/uapi/drm/drm.h | 45 ++++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 10 deletions(-)include/uapi/drm/drm.h +0
-0
include/uapi/drm/drm.h extern "C" { · line 1188
Quoted 9 lines
include/uapi/drm/drm.h +0
-6@@ -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.
Quoted 41 lines
include/uapi/drm/drm.h +28
-4-* 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
include/uapi/drm/drm.h extern "C" { · line 1229
Quoted 10 lines
include/uapi/drm/drm.h +7
-0+/** +* 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 0x03struct drm_event_vblank {
Looks good.
Acked-by Pekka Paalanen <[email protected]>
Thanks,
pq