[mirror_ubuntu-artful-kernel.git] / include / drm / drm_framebuffer.h

/*
 * Copyright (c) 2016 Intel Corporation
 *
 * Permission to use, copy, modify, distribute, and sell this software and its
 * documentation for any purpose is hereby granted without fee, provided that
 * the above copyright notice appear in all copies and that both that copyright
 * notice and this permission notice appear in supporting documentation, and
 * that the name of the copyright holders not be used in advertising or
 * publicity pertaining to distribution of the software without specific,
 * written prior permission.  The copyright holders make no representations
 * about the suitability of this software for any purpose.  It is provided "as
 * is" without express or implied warranty.
 *
 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
 * OF THIS SOFTWARE.
 */

#ifndef __DRM_FRAMEBUFFER_H__
#define __DRM_FRAMEBUFFER_H__

#include <linux/list.h>
#include <linux/ctype.h>
#include <drm/drm_mode_object.h>

struct drm_framebuffer;
struct drm_file;
struct drm_device;

/**
 * struct drm_framebuffer_funcs - framebuffer hooks
 */
struct drm_framebuffer_funcs {
	/**
	 * @destroy:
	 *
	 * Clean up framebuffer resources, specifically also unreference the
	 * backing storage. The core guarantees to call this function for every
	 * framebuffer successfully created by calling
	 * &drm_mode_config_funcs.fb_create. Drivers must also call
	 * drm_framebuffer_cleanup() to release DRM core resources for this
	 * framebuffer.
	 */
	void (*destroy)(struct drm_framebuffer *framebuffer);

	/**
	 * @create_handle:
	 *
	 * Create a buffer handle in the driver-specific buffer manager (either
	 * GEM or TTM) valid for the passed-in &struct drm_file. This is used by
	 * the core to implement the GETFB IOCTL, which returns (for
	 * sufficiently priviledged user) also a native buffer handle. This can
	 * be used for seamless transitions between modesetting clients by
	 * copying the current screen contents to a private buffer and blending
	 * between that and the new contents.
	 *
	 * GEM based drivers should call drm_gem_handle_create() to create the
	 * handle.
	 *
	 * RETURNS:
	 *
	 * 0 on success or a negative error code on failure.
	 */
	int (*create_handle)(struct drm_framebuffer *fb,
			     struct drm_file *file_priv,
			     unsigned int *handle);
	/**
	 * @dirty:
	 *
	 * Optional callback for the dirty fb IOCTL.
	 *
	 * Userspace can notify the driver via this callback that an area of the
	 * framebuffer has changed and should be flushed to the display
	 * hardware. This can also be used internally, e.g. by the fbdev
	 * emulation, though that's not the case currently.
	 *
	 * See documentation in drm_mode.h for the struct drm_mode_fb_dirty_cmd
	 * for more information as all the semantics and arguments have a one to
	 * one mapping on this function.
	 *
	 * RETURNS:
	 *
	 * 0 on success or a negative error code on failure.
	 */
	int (*dirty)(struct drm_framebuffer *framebuffer,
		     struct drm_file *file_priv, unsigned flags,
		     unsigned color, struct drm_clip_rect *clips,
		     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_get() and
 * drm_framebuffer_put().
 *
 * The refcount is stored inside the mode object @base.
 */
struct drm_framebuffer {
	/**
	 * @dev: DRM device this framebuffer belongs to
	 */
	struct drm_device *dev;
	/**
	 * @head: Place on the &drm_mode_config.fb_list, access protected by
	 * &drm_mode_config.fb_lock.
	 */
	struct list_head head;

	/**
	 * @base: base modeset object structure, contains the reference count.
	 */
	struct drm_mode_object base;
	/**
	 * @format: framebuffer format information
	 */
	const struct drm_format_info *format;
	/**
	 * @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. 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;
	/**
	 * @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;
	/**
	 * @flags: Framebuffer flags like DRM_MODE_FB_INTERLACED or
	 * DRM_MODE_FB_MODIFIERS.
	 */
	int flags;
	/**
	 * @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 &drm_file.fbs, protected by &drm_file.fbs_lock.
	 */
	struct list_head filp_head;
};

#define obj_to_fb(x) container_of(x, struct drm_framebuffer, base)

int drm_framebuffer_init(struct drm_device *dev,
			 struct drm_framebuffer *fb,
			 const struct drm_framebuffer_funcs *funcs);
struct drm_framebuffer *drm_framebuffer_lookup(struct drm_device *dev,
					       uint32_t id);
void drm_framebuffer_remove(struct drm_framebuffer *fb);
void drm_framebuffer_cleanup(struct drm_framebuffer *fb);
void drm_framebuffer_unregister_private(struct drm_framebuffer *fb);

/**
 * drm_framebuffer_get - acquire a framebuffer reference
 * @fb: DRM framebuffer
 *
 * This function increments the framebuffer's reference count.
 */
static inline void drm_framebuffer_get(struct drm_framebuffer *fb)
{
	drm_mode_object_get(&fb->base);
}

/**
 * drm_framebuffer_put - release a framebuffer reference
 * @fb: DRM framebuffer
 *
 * This function decrements the framebuffer's reference count and frees the
 * framebuffer if the reference count drops to zero.
 */
static inline void drm_framebuffer_put(struct drm_framebuffer *fb)
{
	drm_mode_object_put(&fb->base);
}

/**
 * drm_framebuffer_reference - acquire a framebuffer reference
 * @fb: DRM framebuffer
 *
 * This is a compatibility alias for drm_framebuffer_get() and should not be
 * used by new code.
 */
static inline void drm_framebuffer_reference(struct drm_framebuffer *fb)
{
	drm_framebuffer_get(fb);
}

/**
 * drm_framebuffer_unreference - release a framebuffer reference
 * @fb: DRM framebuffer
 *
 * This is a compatibility alias for drm_framebuffer_put() and should not be
 * used by new code.
 */
static inline void drm_framebuffer_unreference(struct drm_framebuffer *fb)
{
	drm_framebuffer_put(fb);
}

/**
 * drm_framebuffer_read_refcount - read the framebuffer reference count.
 * @fb: framebuffer
 *
 * This functions returns the framebuffer's reference count.
 */
static inline uint32_t drm_framebuffer_read_refcount(struct drm_framebuffer *fb)
{
	return kref_read(&fb->base.refcount);
}

/**
 * drm_framebuffer_assign - store a reference to the fb
 * @p: location to store framebuffer
 * @fb: new framebuffer (maybe NULL)
 *
 * This functions sets the location to store a reference to the framebuffer,
 * unreferencing the framebuffer that was previously stored in that location.
 */
static inline void drm_framebuffer_assign(struct drm_framebuffer **p,
					  struct drm_framebuffer *fb)
{
	if (fb)
		drm_framebuffer_get(fb);
	if (*p)
		drm_framebuffer_put(*p);
	*p = fb;
}

/*
 * drm_for_each_fb - iterate over all framebuffers
 * @fb: the loop cursor
 * @dev: the DRM device
 *
 * Iterate over all framebuffers of @dev. User must hold
 * &drm_mode_config.fb_lock.
 */
#define drm_for_each_fb(fb, dev) \
	for (WARN_ON(!mutex_is_locked(&(dev)->mode_config.fb_lock)),		\
	     fb = list_first_entry(&(dev)->mode_config.fb_list,	\
					  struct drm_framebuffer, head);	\
	     &fb->head != (&(dev)->mode_config.fb_list);			\
	     fb = list_next_entry(fb, head))

int drm_framebuffer_plane_width(int width,
				const struct drm_framebuffer *fb, int plane);
int drm_framebuffer_plane_height(int height,
				 const struct drm_framebuffer *fb, int plane);

#endif
Commit	Line	Data
7520a277 DV	1	/*
	2	* Copyright (c) 2016 Intel Corporation
	3	*
	4	* Permission to use, copy, modify, distribute, and sell this software and its
	5	* documentation for any purpose is hereby granted without fee, provided that
	6	* the above copyright notice appear in all copies and that both that copyright
	7	* notice and this permission notice appear in supporting documentation, and
	8	* that the name of the copyright holders not be used in advertising or
	9	* publicity pertaining to distribution of the software without specific,
	10	* written prior permission. The copyright holders make no representations
	11	* about the suitability of this software for any purpose. It is provided "as
	12	* is" without express or implied warranty.
	13	*
	14	* THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
	15	* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
	16	* EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
	17	* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
	18	* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
	19	* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
	20	* OF THIS SOFTWARE.
	21	*/
	22
	23	#ifndef __DRM_FRAMEBUFFER_H__
	24	#define __DRM_FRAMEBUFFER_H__
	25
	26	#include <linux/list.h>
	27	#include <linux/ctype.h>
949619f3	28	#include <drm/drm_mode_object.h>
7520a277 DV	29
	30	struct drm_framebuffer;
	31	struct drm_file;
	32	struct drm_device;
	33
	34	/**
	35	* struct drm_framebuffer_funcs - framebuffer hooks
	36	*/
	37	struct drm_framebuffer_funcs {
	38	/**
	39	* @destroy:
	40	*
	41	* Clean up framebuffer resources, specifically also unreference the
	42	* backing storage. The core guarantees to call this function for every
d574528a DV	43	* framebuffer successfully created by calling
d574528a DV	44	* &drm_mode_config_funcs.fb_create. Drivers must also call
7520a277 DV	45	* drm_framebuffer_cleanup() to release DRM core resources for this
	46	* framebuffer.
	47	*/
	48	void (destroy)(struct drm_framebuffer framebuffer);
	49
	50	/**
	51	* @create_handle:
	52	*
	53	* Create a buffer handle in the driver-specific buffer manager (either
ea0dd85a	54	* GEM or TTM) valid for the passed-in &struct drm_file. This is used by
7520a277 DV	55	* the core to implement the GETFB IOCTL, which returns (for
	56	* sufficiently priviledged user) also a native buffer handle. This can
	57	* be used for seamless transitions between modesetting clients by
	58	* copying the current screen contents to a private buffer and blending
	59	* between that and the new contents.
	60	*
	61	* GEM based drivers should call drm_gem_handle_create() to create the
	62	* handle.
	63	*
	64	* RETURNS:
	65	*
	66	* 0 on success or a negative error code on failure.
	67	*/
	68	int (create_handle)(struct drm_framebuffer fb,
	69	struct drm_file *file_priv,
	70	unsigned int *handle);
	71	/**
	72	* @dirty:
	73	*
	74	* Optional callback for the dirty fb IOCTL.
	75	*
	76	* Userspace can notify the driver via this callback that an area of the
	77	* framebuffer has changed and should be flushed to the display
	78	* hardware. This can also be used internally, e.g. by the fbdev
	79	* emulation, though that's not the case currently.
	80	*
	81	* See documentation in drm_mode.h for the struct drm_mode_fb_dirty_cmd
	82	* for more information as all the semantics and arguments have a one to
	83	* one mapping on this function.
	84	*
	85	* RETURNS:
	86	*
	87	* 0 on success or a negative error code on failure.
	88	*/
	89	int (dirty)(struct drm_framebuffer framebuffer,
	90	struct drm_file *file_priv, unsigned flags,
	91	unsigned color, struct drm_clip_rect *clips,
	92	unsigned num_clips);
	93	};
	94
750fb8c4 DV	95	/**
	96	* struct drm_framebuffer - frame buffer object
	97	*
	98	* Note that the fb is refcounted for the benefit of driver internals,
	99	* for example some hw, disabling a CRTC/plane is asynchronous, and
	100	* scanout does not actually complete until the next vblank. So some
	101	* cleanup (like releasing the reference(s) on the backing GEM bo(s))
	102	* should be deferred. In cases like this, the driver would like to
	103	* hold a ref to the fb even though it has already been removed from
a4a69da0 TR	104	* userspace perspective. See drm_framebuffer_get() and
a4a69da0 TR	105	* drm_framebuffer_put().
750fb8c4 DV	106	*
	107	* The refcount is stored inside the mode object @base.
	108	*/
7520a277	109	struct drm_framebuffer {
750fb8c4 DV	110	/**
	111	* @dev: DRM device this framebuffer belongs to
	112	*/
7520a277	113	struct drm_device *dev;
750fb8c4	114	/**
d574528a DV	115	* @head: Place on the &drm_mode_config.fb_list, access protected by
d574528a DV	116	* &drm_mode_config.fb_lock.
7520a277 DV	117	*/
7520a277 DV	118	struct list_head head;
750fb8c4 DV	119
	120	/**
	121	* @base: base modeset object structure, contains the reference count.
	122	*/
7520a277	123	struct drm_mode_object base;
e14c23c6 VS	124	/**
	125	* @format: framebuffer format information
	126	*/
	127	const struct drm_format_info *format;
750fb8c4 DV	128	/**
	129	* @funcs: framebuffer vfunc table
	130	*/
7520a277	131	const struct drm_framebuffer_funcs *funcs;
750fb8c4 DV	132	/**
	133	* @pitches: Line stride per buffer. For userspace created object this
	134	* is copied from drm_mode_fb_cmd2.
	135	*/
7520a277	136	unsigned int pitches[4];
750fb8c4 DV	137	/**
	138	* @offsets: Offset from buffer start to the actual pixel data in bytes,
	139	* per buffer. For userspace created object this is copied from
	140	* drm_mode_fb_cmd2.
	141	*
	142	* Note that this is a linear offset and does not take into account
	143	* tiling or buffer laytou per @modifier. It meant to be used when the
	144	* actual pixel data for this framebuffer plane starts at an offset,
	145	* e.g. when multiple planes are allocated within the same backing
	146	* storage buffer object. For tiled layouts this generally means it
	147	* @offsets must at least be tile-size aligned, but hardware often has
	148	* stricter requirements.
	149	*
	150	* This should not be used to specifiy x/y pixel offsets into the buffer
	151	* data (even for linear buffers). Specifying an x/y pixel offset is
ea0dd85a	152	* instead done through the source rectangle in &struct drm_plane_state.
750fb8c4	153	*/
7520a277	154	unsigned int offsets[4];
750fb8c4	155	/**
bae781b2	156	* @modifier: Data layout modifier. This is used to describe
750fb8c4 DV	157	* tiling, or also special layouts (like compression) of auxiliary
	158	* buffers. For userspace created object this is copied from
	159	* drm_mode_fb_cmd2.
	160	*/
bae781b2	161	uint64_t modifier;
750fb8c4 DV	162	/**
	163	* @width: Logical width of the visible area of the framebuffer, in
	164	* pixels.
	165	*/
7520a277	166	unsigned int width;
750fb8c4 DV	167	/**
	168	* @height: Logical height of the visible area of the framebuffer, in
	169	* pixels.
	170	*/
7520a277	171	unsigned int height;
750fb8c4 DV	172	/**
	173	* @flags: Framebuffer flags like DRM_MODE_FB_INTERLACED or
	174	* DRM_MODE_FB_MODIFIERS.
	175	*/
7520a277	176	int flags;
750fb8c4 DV	177	/**
	178	* @hot_x: X coordinate of the cursor hotspot. Used by the legacy cursor
	179	* IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR
	180	* universal plane.
	181	*/
7520a277	182	int hot_x;
750fb8c4 DV	183	/**
	184	* @hot_y: Y coordinate of the cursor hotspot. Used by the legacy cursor
	185	* IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR
	186	* universal plane.
	187	*/
7520a277	188	int hot_y;
750fb8c4	189	/**
d574528a	190	* @filp_head: Placed on &drm_file.fbs, protected by &drm_file.fbs_lock.
750fb8c4	191	*/
7520a277 DV	192	struct list_head filp_head;
	193	};
	194
afb21ea6 DV	195	#define obj_to_fb(x) container_of(x, struct drm_framebuffer, base)
afb21ea6 DV	196
7520a277 DV	197	int drm_framebuffer_init(struct drm_device *dev,
	198	struct drm_framebuffer *fb,
	199	const struct drm_framebuffer_funcs *funcs);
	200	struct drm_framebuffer drm_framebuffer_lookup(struct drm_device dev,
	201	uint32_t id);
	202	void drm_framebuffer_remove(struct drm_framebuffer *fb);
	203	void drm_framebuffer_cleanup(struct drm_framebuffer *fb);
	204	void drm_framebuffer_unregister_private(struct drm_framebuffer *fb);
	205
	206	/**
a4a69da0 TR	207	* drm_framebuffer_get - acquire a framebuffer reference
	208	* @fb: DRM framebuffer
	209	*
	210	* This function increments the framebuffer's reference count.
	211	*/
	212	static inline void drm_framebuffer_get(struct drm_framebuffer *fb)
	213	{
	214	drm_mode_object_get(&fb->base);
	215	}
	216
	217	/**
	218	* drm_framebuffer_put - release a framebuffer reference
	219	* @fb: DRM framebuffer
	220	*
	221	* This function decrements the framebuffer's reference count and frees the
	222	* framebuffer if the reference count drops to zero.
	223	*/
	224	static inline void drm_framebuffer_put(struct drm_framebuffer *fb)
	225	{
	226	drm_mode_object_put(&fb->base);
	227	}
	228
	229	/**
	230	* drm_framebuffer_reference - acquire a framebuffer reference
	231	* @fb: DRM framebuffer
7520a277	232	*
a4a69da0 TR	233	* This is a compatibility alias for drm_framebuffer_get() and should not be
a4a69da0 TR	234	* used by new code.
7520a277 DV	235	*/
	236	static inline void drm_framebuffer_reference(struct drm_framebuffer *fb)
	237	{
a4a69da0	238	drm_framebuffer_get(fb);
7520a277 DV	239	}
	240
	241	/**
a4a69da0 TR	242	* drm_framebuffer_unreference - release a framebuffer reference
a4a69da0 TR	243	* @fb: DRM framebuffer
7520a277	244	*
a4a69da0 TR	245	* This is a compatibility alias for drm_framebuffer_put() and should not be
a4a69da0 TR	246	* used by new code.
7520a277 DV	247	*/
	248	static inline void drm_framebuffer_unreference(struct drm_framebuffer *fb)
	249	{
a4a69da0	250	drm_framebuffer_put(fb);
7520a277 DV	251	}
	252
	253	/**
	254	* drm_framebuffer_read_refcount - read the framebuffer reference count.
	255	* @fb: framebuffer
	256	*
	257	* This functions returns the framebuffer's reference count.
	258	*/
	259	static inline uint32_t drm_framebuffer_read_refcount(struct drm_framebuffer *fb)
	260	{
2c935bc5	261	return kref_read(&fb->base.refcount);
7520a277	262	}
afb21ea6 DV	263
afb21ea6 DV	264	/**
389f78b3 CW	265	* drm_framebuffer_assign - store a reference to the fb
	266	* @p: location to store framebuffer
	267	* @fb: new framebuffer (maybe NULL)
	268	*
	269	* This functions sets the location to store a reference to the framebuffer,
	270	* unreferencing the framebuffer that was previously stored in that location.
	271	*/
	272	static inline void drm_framebuffer_assign(struct drm_framebuffer **p,
	273	struct drm_framebuffer *fb)
	274	{
	275	if (fb)
a4a69da0	276	drm_framebuffer_get(fb);
389f78b3	277	if (*p)
a4a69da0	278	drm_framebuffer_put(*p);
389f78b3 CW	279	*p = fb;
	280	}
	281
	282	/*
afb21ea6 DV	283	* drm_for_each_fb - iterate over all framebuffers
	284	* @fb: the loop cursor
	285	* @dev: the DRM device
	286	*
d574528a DV	287	* Iterate over all framebuffers of @dev. User must hold
d574528a DV	288	* &drm_mode_config.fb_lock.
afb21ea6 DV	289	*/
	290	#define drm_for_each_fb(fb, dev) \
	291	for (WARN_ON(!mutex_is_locked(&(dev)->mode_config.fb_lock)), \
	292	fb = list_first_entry(&(dev)->mode_config.fb_list, \
	293	struct drm_framebuffer, head); \
	294	&fb->head != (&(dev)->mode_config.fb_list); \
	295	fb = list_next_entry(fb, head))
8f8f6a6c VS	296
	297	int drm_framebuffer_plane_width(int width,
	298	const struct drm_framebuffer *fb, int plane);
	299	int drm_framebuffer_plane_height(int height,
	300	const struct drm_framebuffer *fb, int plane);
	301
7520a277	302	#endif