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:
Родитель
7520a277d9
Коммит
750fb8c439
|
@ -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;
|
||||
};
|
||||
|
||||
|
|
Загрузка…
Ссылка в новой задаче