[PATCH 12/21] drm/doc: Update drm_framebuffer docs
Sean Paul
seanpaul at chromium.org
Tue Aug 16 16:11:14 UTC 2016
On Fri, Aug 12, 2016 at 1:48 PM, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> - Move the intro section into a DOC comment, and update it slightly.
> - kernel-doc for struct drm_framebuffer!
>
> v2:
> - Copypaste fail (Sean).
> - Explain the linear @offsets clearer (Ville).
>
> Cc: Sean Paul <seanpaul at chromium.org>
> Cc: Ville Syrjälä <ville.syrjala at linux.intel.com>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
Reviewed-by: Sean Paul <seanpaul at chromium.org>
> ---
> Documentation/gpu/drm-kms.rst | 26 +---------
> drivers/gpu/drm/drm_framebuffer.c | 35 +++++++++++++
> include/drm/drm_framebuffer.h | 106 +++++++++++++++++++++++++++++++++-----
> 3 files changed, 130 insertions(+), 37 deletions(-)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 8264a88a8695..d244e03658cc 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -39,30 +39,8 @@ Atomic Mode Setting Function Reference
> Frame Buffer Abstraction
> ========================
>
> -Frame buffers are abstract memory objects that provide a source of
> -pixels to scanout to a CRTC. Applications explicitly request the
> -creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls
> -and receive an opaque handle that can be passed to the KMS CRTC control,
> -plane configuration and page flip functions.
> -
> -Frame buffers rely on the underneath memory manager for low-level memory
> -operations. When creating a frame buffer applications pass a memory
> -handle (or a list of memory handles for multi-planar formats) through
> -the ``drm_mode_fb_cmd2`` argument. For drivers using GEM as their
> -userspace buffer management interface this would be a GEM handle.
> -Drivers are however free to use their own backing storage object
> -handles, e.g. vmwgfx directly exposes special TTM handles to userspace
> -and so expects TTM handles in the create ioctl and not GEM handles.
> -
> -The lifetime of a drm framebuffer is controlled with a reference count,
> -drivers can grab additional references with
> -:c:func:`drm_framebuffer_reference()`and drop them again with
> -:c:func:`drm_framebuffer_unreference()`. For driver-private
> -framebuffers for which the last reference is never dropped (e.g. for the
> -fbdev framebuffer when the struct :c:type:`struct drm_framebuffer
> -<drm_framebuffer>` is embedded into the fbdev helper struct)
> -drivers can manually clean up a framebuffer at module unload time with
> -:c:func:`drm_framebuffer_unregister_private()`.
> +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
> + :doc: overview
>
> Frame Buffer Functions Reference
> --------------------------------
> diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c
> index 19478a25ac20..34e3c4acbc8a 100644
> --- a/drivers/gpu/drm/drm_framebuffer.c
> +++ b/drivers/gpu/drm/drm_framebuffer.c
> @@ -28,6 +28,41 @@
> #include "drm_crtc_internal.h"
>
> /**
> + * DOC: overview
> + *
> + * Frame buffers are abstract memory objects that provide a source of pixels to
> + * scanout to a CRTC. Applications explicitly request the creation of frame
> + * buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and receive an opaque
> + * handle that can be passed to the KMS CRTC control, plane configuration and
> + * page flip functions.
> + *
> + * Frame buffers rely on the underlying memory manager for allocating backing
> + * storage. When creating a frame buffer applications pass a memory handle
> + * (or a list of memory handles for multi-planar formats) through the
> + * struct &drm_mode_fb_cmd2 argument. For drivers using GEM as their userspace
> + * buffer management interface this would be a GEM handle. Drivers are however
> + * free to use their own backing storage object handles, e.g. vmwgfx directly
> + * exposes special TTM handles to userspace and so expects TTM handles in the
> + * create ioctl and not GEM handles.
> + *
> + * Framebuffers are tracked with struct &drm_framebuffer. They are published
> + * using drm_framebuffer_init() - after calling that function userspace can use
> + * and access the framebuffer object. The helper function
> + * drm_helper_mode_fill_fb_struct() can be used to pre-fill the required
> + * metadata fields.
> + *
> + * The lifetime of a drm framebuffer is controlled with a reference count,
> + * drivers can grab additional references with drm_framebuffer_reference() and
> + * drop them again with drm_framebuffer_unreference(). For driver-private
> + * framebuffers for which the last reference is never dropped (e.g. for the
> + * fbdev framebuffer when the struct struct &drm_framebuffer is embedded into
> + * the fbdev helper struct) drivers can manually clean up a framebuffer at
> + * module unload time with drm_framebuffer_unregister_private(). But doing this
> + * is not recommended, and it's better to have a normal free-standing struct
> + * &drm_framebuffer.
> + */
> +
> +/**
> * drm_mode_addfb - add an FB to the graphics configuration
> * @dev: drm device for the ioctl
> * @data: data pointer for the ioctl
> diff --git a/include/drm/drm_framebuffer.h b/include/drm/drm_framebuffer.h
> index 46abdace8fa5..50deb40d3bfd 100644
> --- a/include/drm/drm_framebuffer.h
> +++ b/include/drm/drm_framebuffer.h
> @@ -92,37 +92,117 @@ struct drm_framebuffer_funcs {
> unsigned num_clips);
> };
>
> +/**
> + * struct drm_framebuffer - frame buffer object
> + *
> + * Note that the fb is refcounted for the benefit of driver internals,
> + * for example some hw, disabling a CRTC/plane is asynchronous, and
> + * scanout does not actually complete until the next vblank. So some
> + * cleanup (like releasing the reference(s) on the backing GEM bo(s))
> + * should be deferred. In cases like this, the driver would like to
> + * hold a ref to the fb even though it has already been removed from
> + * userspace perspective. See drm_framebuffer_reference() and
> + * drm_framebuffer_unreference().
> + *
> + * The refcount is stored inside the mode object @base.
> + */
> struct drm_framebuffer {
> + /**
> + * @dev: DRM device this framebuffer belongs to
> + */
> struct drm_device *dev;
> - /*
> - * Note that the fb is refcounted for the benefit of driver internals,
> - * for example some hw, disabling a CRTC/plane is asynchronous, and
> - * scanout does not actually complete until the next vblank. So some
> - * cleanup (like releasing the reference(s) on the backing GEM bo(s))
> - * should be deferred. In cases like this, the driver would like to
> - * hold a ref to the fb even though it has already been removed from
> - * userspace perspective.
> - * The refcount is stored inside the mode object.
> - */
> - /*
> - * Place on the dev->mode_config.fb_list, access protected by
> + /**
> + * @head: Place on the dev->mode_config.fb_list, access protected by
> * dev->mode_config.fb_lock.
> */
> struct list_head head;
> +
> + /**
> + * @base: base modeset object structure, contains the reference count.
> + */
> struct drm_mode_object base;
> + /**
> + * @funcs: framebuffer vfunc table
> + */
> const struct drm_framebuffer_funcs *funcs;
> + /**
> + * @pitches: Line stride per buffer. For userspace created object this
> + * is copied from drm_mode_fb_cmd2.
> + */
> unsigned int pitches[4];
> + /**
> + * @offsets: Offset from buffer start to the actual pixel data in bytes,
> + * per buffer. For userspace created object this is copied from
> + * drm_mode_fb_cmd2.
> + *
> + * Note that this is a linear offset and does not take into account
> + * tiling or buffer laytou per @modifier. It meant to be used when the
> + * actual pixel data for this framebuffer plane starts at an offset,
> + * e.g. when multiple planes are allocated within the same backing
> + * storage buffer object. For tiled layouts this generally means it
> + * @offsets must at least be tile-size aligned, but hardware often has
> + * stricter requirements.
> + *
> + * This should not be used to specifiy x/y pixel offsets into the buffer
> + * data (even for linear buffers). Specifying an x/y pixel offset is
> + * instead done through the source rectangle in struct &drm_plane_state.
> + */
> unsigned int offsets[4];
> + /**
> + * @modifier: Data layout modifier, per buffer. This is used to describe
> + * tiling, or also special layouts (like compression) of auxiliary
> + * buffers. For userspace created object this is copied from
> + * drm_mode_fb_cmd2.
> + */
> uint64_t modifier[4];
> + /**
> + * @width: Logical width of the visible area of the framebuffer, in
> + * pixels.
> + */
> unsigned int width;
> + /**
> + * @height: Logical height of the visible area of the framebuffer, in
> + * pixels.
> + */
> unsigned int height;
> - /* depth can be 15 or 16 */
> + /**
> + * @depth: Depth in bits per pixel for RGB formats. 0 for everything
> + * else. Legacy information derived from @pixel_format, it's suggested to use
> + * the DRM FOURCC codes and helper functions directly instead.
> + */
> unsigned int depth;
> + /**
> + * @bits_per_pixel: Storage used bits per pixel for RGB formats. 0 for
> + * everything else. Legacy information derived from @pixel_format, it's
> + * suggested to use the DRM FOURCC codes and helper functions directly
> + * instead.
> + */
> int bits_per_pixel;
> + /**
> + * @flags: Framebuffer flags like DRM_MODE_FB_INTERLACED or
> + * DRM_MODE_FB_MODIFIERS.
> + */
> int flags;
> + /**
> + * @pixel_format: DRM FOURCC code describing the pixel format.
> + */
> uint32_t pixel_format; /* fourcc format */
> + /**
> + * @hot_x: X coordinate of the cursor hotspot. Used by the legacy cursor
> + * IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR
> + * universal plane.
> + */
> int hot_x;
> + /**
> + * @hot_y: Y coordinate of the cursor hotspot. Used by the legacy cursor
> + * IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR
> + * universal plane.
> + */
> int hot_y;
> + /**
> + * @filp_head: Placed on struct &drm_file fbs list_head, protected by
> + * fbs_lock in the same structure.
> + */
> struct list_head filp_head;
> };
>
> --
> 2.8.1
>
More information about the dri-devel
mailing list