drm/doc: Update drm_framebuffer docs

- 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@chromium.org>
Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1471034937-651-12-git-send-email-daniel.vetter@ffwll.ch
This commit is contained in:
Daniel Vetter 2016-08-12 22:48:48 +02:00
Родитель 7520a277d9
Коммит 750fb8c439
3 изменённых файлов: 130 добавлений и 37 удалений

Просмотреть файл

@ -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
--------------------------------

Просмотреть файл

@ -27,6 +27,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

Просмотреть файл

@ -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 {
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.
/**
* @dev: DRM device this framebuffer belongs to
*/
/*
* Place on the dev->mode_config.fb_list, access protected by
struct drm_device *dev;
/**
* @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;
};