korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-11-26 21:54:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

drm/uapi: document kernel capabilities

Browse Source 
Document all of the DRM_CAP_* defines.

v2 (Pekka):
- Describe what the bit depth is
- Expand on preferred dumb buffer memory access patterns
- Explain what a PRIME buffer is
- Mention DRM_IOCTL_PRIME_FD_TO_HANDLE and DRM_IOCTL_PRIME_HANDLE_TO_FD
- Explicitly reference CLOCK_REALTIME and CLOCK_MONOTONIC
- Make it clear DRM_CAP_CRTC_IN_VBLANK_EVENT applies to both DRM_EVENT_VBLANK
  and DRM_EVENT_FLIP_COMPLETE

v3 (Daniel):
- Specify kernel versions for caps that don't depend on drivers
- Make it clear dumb buffers caps are only about dumb buffers

Signed-off-by: Simon Ser <contact@emersion.fr>
Acked-by: Daniel Vetter <daniel@ffwll.ch>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210308123421.747836-1-contact@emersion.fr
This commit is contained in:
Simon Ser 2021-03-04 23:08:37 +01:00
parent 377f8331d0
commit b603e810f7
1 changed files with 121 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
include/uapi/drm/drm.h
View File

@ -625,30 +625,147 @@ struct drm_gem_open {
__u64 size;
};
/**
* DRM_CAP_DUMB_BUFFER
*
* If set to 1, the driver supports creating dumb buffers via the
* &DRM_IOCTL_MODE_CREATE_DUMB ioctl.
*/
#define DRM_CAP_DUMB_BUFFER 0x1
/**
* DRM_CAP_VBLANK_HIGH_CRTC
*
* If set to 1, the kernel supports specifying a CRTC index in the high bits of
* &drm_wait_vblank_request.type.
*
* Starting kernel version 2.6.39, this capability is always set to 1.
*/
#define DRM_CAP_VBLANK_HIGH_CRTC 0x2
/**
* DRM_CAP_DUMB_PREFERRED_DEPTH
*
* The preferred bit depth for dumb buffers.
*
* The bit depth is the number of bits used to indicate the color of a single
* pixel excluding any padding. This is different from the number of bits per
* pixel. For instance, XRGB8888 has a bit depth of 24 but has 32 bits per
* pixel.
*
* Note that this preference only applies to dumb buffers, it's irrelevant for
* other types of buffers.
*/
#define DRM_CAP_DUMB_PREFERRED_DEPTH 0x3
/**
* DRM_CAP_DUMB_PREFER_SHADOW
*
* If set to 1, the driver prefers userspace to render to a shadow buffer
* instead of directly rendering to a dumb buffer. For best speed, userspace
* should do streaming ordered memory copies into the dumb buffer and never
* read from it.
*
* Note that this preference only applies to dumb buffers, it's irrelevant for
* other types of buffers.
*/
#define DRM_CAP_DUMB_PREFER_SHADOW 0x4
/**
* DRM_CAP_PRIME
*
* Bitfield of supported PRIME sharing capabilities. See &DRM_PRIME_CAP_IMPORT
* and &DRM_PRIME_CAP_EXPORT.
*
* PRIME buffers are exposed as dma-buf file descriptors. See
* Documentation/gpu/drm-mm.rst, section "PRIME Buffer Sharing".
*/
#define DRM_CAP_PRIME 0x5
/**
* DRM_PRIME_CAP_IMPORT
*
* If this bit is set in &DRM_CAP_PRIME, the driver supports importing PRIME
* buffers via the &DRM_IOCTL_PRIME_FD_TO_HANDLE ioctl.
*/
#define DRM_PRIME_CAP_IMPORT 0x1
/**
* DRM_PRIME_CAP_EXPORT
*
* If this bit is set in &DRM_CAP_PRIME, the driver supports exporting PRIME
* buffers via the &DRM_IOCTL_PRIME_HANDLE_TO_FD ioctl.
*/
#define DRM_PRIME_CAP_EXPORT 0x2
/**
* DRM_CAP_TIMESTAMP_MONOTONIC
*
* If set to 0, the kernel will report timestamps with ``CLOCK_REALTIME`` in
* struct drm_event_vblank. If set to 1, the kernel will report timestamps with
* ``CLOCK_MONOTONIC``. See ``clock_gettime(2)`` for the definition of these
* clocks.
*
* Starting from kernel version 2.6.39, the default value for this capability
* is 1. Starting kernel version 4.15, this capability is always set to 1.
*/
#define DRM_CAP_TIMESTAMP_MONOTONIC 0x6
/**
* DRM_CAP_ASYNC_PAGE_FLIP
*
* If set to 1, the driver supports &DRM_MODE_PAGE_FLIP_ASYNC.
*/
#define DRM_CAP_ASYNC_PAGE_FLIP 0x7
/*
* The CURSOR_WIDTH and CURSOR_HEIGHT capabilities return a valid widthxheight
* combination for the hardware cursor. The intention is that a hardware
* agnostic userspace can query a cursor plane size to use.
/**
* DRM_CAP_CURSOR_WIDTH
*
* The ``CURSOR_WIDTH`` and ``CURSOR_HEIGHT`` capabilities return a valid
* width x height combination for the hardware cursor. The intention is that a
* hardware agnostic userspace can query a cursor plane size to use.
*
* Note that the cross-driver contract is to merely return a valid size;
* drivers are free to attach another meaning on top, eg. i915 returns the
* maximum plane size.
*/
#define DRM_CAP_CURSOR_WIDTH 0x8
/**
* DRM_CAP_CURSOR_HEIGHT
*
* See &DRM_CAP_CURSOR_WIDTH.
*/
#define DRM_CAP_CURSOR_HEIGHT 0x9
/**
* DRM_CAP_ADDFB2_MODIFIERS
*
* If set to 1, the driver supports supplying modifiers in the
* &DRM_IOCTL_MODE_ADDFB2 ioctl.
*/
#define DRM_CAP_ADDFB2_MODIFIERS 0x10
/**
* DRM_CAP_PAGE_FLIP_TARGET
*
* If set to 1, the driver supports the &DRM_MODE_PAGE_FLIP_TARGET_ABSOLUTE and
* &DRM_MODE_PAGE_FLIP_TARGET_RELATIVE flags in
* &drm_mode_crtc_page_flip_target.flags for the &DRM_IOCTL_MODE_PAGE_FLIP
* ioctl.
*/
#define DRM_CAP_PAGE_FLIP_TARGET 0x11
/**
* DRM_CAP_CRTC_IN_VBLANK_EVENT
*
* If set to 1, the kernel supports reporting the CRTC ID in
* &drm_event_vblank.crtc_id for the &DRM_EVENT_VBLANK and
* &DRM_EVENT_FLIP_COMPLETE events.
*
* Starting kernel version 4.12, this capability is always set to 1.
*/
#define DRM_CAP_CRTC_IN_VBLANK_EVENT 0x12
/**
* DRM_CAP_SYNCOBJ
*
* If set to 1, the driver supports sync objects. See
* Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
*/
#define DRM_CAP_SYNCOBJ 0x13
/**
* DRM_CAP_SYNCOBJ_TIMELINE
*
* If set to 1, the driver supports timeline operations on sync objects. See
* Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
*/
#define DRM_CAP_SYNCOBJ_TIMELINE 0x14
/* DRM_IOCTL_GET_CAP ioctl argument type */