[PATCH] drm/uapi: document kernel capabilities

[Pekka Paalanen]

On Thu,  4 Mar 2021 23:10:57 +0100
Simon Ser <contact at emersion.fr> wrote:

> Document all of the DRM_CAP_* defines.
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Daniel Vetter <daniel at ffwll.ch>
> Cc: Pekka Paalanen <ppaalanen at gmail.com>
> ---
>  include/uapi/drm/drm.h | 100 +++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 96 insertions(+), 4 deletions(-)
> 
> diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h
> index 0827037c5484..4ef07f505725 100644
> --- a/include/uapi/drm/drm.h
> +++ b/include/uapi/drm/drm.h
> @@ -625,30 +625,122 @@ 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.
> + */
>  #define DRM_CAP_VBLANK_HIGH_CRTC	0x2
> +/**
> + * DRM_CAP_DUMB_PREFERRED_DEPTH
> + *
> + * The preferred depth (in bits) for dumb buffers.

Hi,

this is literally depth, not bits per pixel, right?

> + */
>  #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.

Maybe add something like:

For best speed, userspace should do streaming ordered memory copies
into the dumb buffer and never read from it.

Isn't that correct?

> + */
>  #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.
> + */
>  #define DRM_CAP_PRIME			0x5
> +/**
> + * DRM_PRIME_CAP_IMPORT
> + *
> + * If this bit is set in &DRM_CAP_PRIME, the driver supports importing PRIME
> + * buffers.

What are PRIME buffers?

> + */
>  #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.

What's the export API? HandleToFD()?

> + */
>  #define  DRM_PRIME_CAP_EXPORT		0x2
> +/**
> + * DRM_CAP_TIMESTAMP_MONOTONIC
> + *
> + * If set to 0, the kernel will report timestamps with the realtime clock in
> + * struct drm_event_vblank. If set to 1, the kernel will report timestamps with
> + * the monotonic clock.

I think it would be more explicit to say CLOCK_REALTIME and
CLOCK_MONOTONIC, because there are things like CLOCK_MONOTONIC_RAW
which is different. Mention clock_gettime()?

> + */
>  #define DRM_CAP_TIMESTAMP_MONOTONIC	0x6
> +/**
> + * DRM_CAP_ASYNC_PAGE_FLIP
> + *
> + * If set to 1, the driver supports &DRM_MODE_PAGE_FLIP_ASYNC.

Does this apply equally to both legacy and atomic KMS API?

> + */
>  #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.

Does this not apply also to the pageflip / atomic completion event?

> + */
>  #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 */

I'm so happy seeing this doc appear! :-)
Sorry for trolling you into it. ;-)


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20210305/ff88dd1a/attachment.sig>