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
diff --git a/include/drm/drm_framebuffer.h b/include/drm/drm_framebuffer.h
index 46abdac..50deb40 100644
--- a/include/drm/drm_framebuffer.h
+++ b/include/drm/drm_framebuffer.h
@@ -92,37 +92,117 @@
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;
};