blob: 04c77eee9c20930dea4672be8080b95c8a509606 [file] [log] [blame]
Daniel Vetter7520a272016-08-15 16:07:02 +02001/*
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>
Daniel Vetter949619f2016-08-29 10:27:51 +020028#include <drm/drm_mode_object.h>
Daniel Vetter7520a272016-08-15 16:07:02 +020029
30struct drm_framebuffer;
31struct drm_file;
32struct drm_device;
33
34/**
35 * struct drm_framebuffer_funcs - framebuffer hooks
36 */
37struct 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
Daniel Vetterd5745282017-01-25 07:26:45 +010043 * framebuffer successfully created by calling
44 * &drm_mode_config_funcs.fb_create. Drivers must also call
Daniel Vetter7520a272016-08-15 16:07:02 +020045 * 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
Daniel Vetterea0dd852016-12-29 21:48:26 +010054 * GEM or TTM) valid for the passed-in &struct drm_file. This is used by
Daniel Vetter7520a272016-08-15 16:07:02 +020055 * 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
Daniel Vetter750fb8c2016-08-12 22:48:48 +020095/**
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
104 * userspace perspective. See drm_framebuffer_reference() and
105 * drm_framebuffer_unreference().
106 *
107 * The refcount is stored inside the mode object @base.
108 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200109struct drm_framebuffer {
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200110 /**
111 * @dev: DRM device this framebuffer belongs to
Daniel Vetter7520a272016-08-15 16:07:02 +0200112 */
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200113 struct drm_device *dev;
114 /**
Daniel Vetterd5745282017-01-25 07:26:45 +0100115 * @head: Place on the &drm_mode_config.fb_list, access protected by
116 * &drm_mode_config.fb_lock.
Daniel Vetter7520a272016-08-15 16:07:02 +0200117 */
118 struct list_head head;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200119
120 /**
121 * @base: base modeset object structure, contains the reference count.
122 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200123 struct drm_mode_object base;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200124 /**
Ville Syrjäläe14c23c2016-11-18 21:52:55 +0200125 * @format: framebuffer format information
126 */
127 const struct drm_format_info *format;
128 /**
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200129 * @funcs: framebuffer vfunc table
130 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200131 const struct drm_framebuffer_funcs *funcs;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200132 /**
133 * @pitches: Line stride per buffer. For userspace created object this
134 * is copied from drm_mode_fb_cmd2.
135 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200136 unsigned int pitches[4];
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200137 /**
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
Daniel Vetterea0dd852016-12-29 21:48:26 +0100152 * instead done through the source rectangle in &struct drm_plane_state.
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200153 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200154 unsigned int offsets[4];
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200155 /**
Ville Syrjäläbae781b2016-11-16 13:33:16 +0200156 * @modifier: Data layout modifier. This is used to describe
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200157 * 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 */
Ville Syrjäläbae781b2016-11-16 13:33:16 +0200161 uint64_t modifier;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200162 /**
163 * @width: Logical width of the visible area of the framebuffer, in
164 * pixels.
165 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200166 unsigned int width;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200167 /**
168 * @height: Logical height of the visible area of the framebuffer, in
169 * pixels.
170 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200171 unsigned int height;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200172 /**
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200173 * @flags: Framebuffer flags like DRM_MODE_FB_INTERLACED or
174 * DRM_MODE_FB_MODIFIERS.
175 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200176 int flags;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200177 /**
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200178 * @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 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200182 int hot_x;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200183 /**
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 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200188 int hot_y;
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200189 /**
Daniel Vetterd5745282017-01-25 07:26:45 +0100190 * @filp_head: Placed on &drm_file.fbs, protected by &drm_file.fbs_lock.
Daniel Vetter750fb8c2016-08-12 22:48:48 +0200191 */
Daniel Vetter7520a272016-08-15 16:07:02 +0200192 struct list_head filp_head;
193};
194
Daniel Vetterafb21ea62016-08-31 18:09:04 +0200195#define obj_to_fb(x) container_of(x, struct drm_framebuffer, base)
196
Daniel Vetter7520a272016-08-15 16:07:02 +0200197int drm_framebuffer_init(struct drm_device *dev,
198 struct drm_framebuffer *fb,
199 const struct drm_framebuffer_funcs *funcs);
200struct drm_framebuffer *drm_framebuffer_lookup(struct drm_device *dev,
201 uint32_t id);
202void drm_framebuffer_remove(struct drm_framebuffer *fb);
203void drm_framebuffer_cleanup(struct drm_framebuffer *fb);
204void drm_framebuffer_unregister_private(struct drm_framebuffer *fb);
205
206/**
207 * drm_framebuffer_reference - incr the fb refcnt
208 * @fb: framebuffer
209 *
210 * This functions increments the fb's refcount.
211 */
212static inline void drm_framebuffer_reference(struct drm_framebuffer *fb)
213{
214 drm_mode_object_reference(&fb->base);
215}
216
217/**
218 * drm_framebuffer_unreference - unref a framebuffer
219 * @fb: framebuffer to unref
220 *
221 * This functions decrements the fb's refcount and frees it if it drops to zero.
222 */
223static inline void drm_framebuffer_unreference(struct drm_framebuffer *fb)
224{
225 drm_mode_object_unreference(&fb->base);
226}
227
228/**
229 * drm_framebuffer_read_refcount - read the framebuffer reference count.
230 * @fb: framebuffer
231 *
232 * This functions returns the framebuffer's reference count.
233 */
234static inline uint32_t drm_framebuffer_read_refcount(struct drm_framebuffer *fb)
235{
236 return atomic_read(&fb->base.refcount.refcount);
237}
Daniel Vetterafb21ea62016-08-31 18:09:04 +0200238
239/**
Chris Wilson389f78b2016-11-25 15:32:30 +0000240 * drm_framebuffer_assign - store a reference to the fb
241 * @p: location to store framebuffer
242 * @fb: new framebuffer (maybe NULL)
243 *
244 * This functions sets the location to store a reference to the framebuffer,
245 * unreferencing the framebuffer that was previously stored in that location.
246 */
247static inline void drm_framebuffer_assign(struct drm_framebuffer **p,
248 struct drm_framebuffer *fb)
249{
250 if (fb)
251 drm_framebuffer_reference(fb);
252 if (*p)
253 drm_framebuffer_unreference(*p);
254 *p = fb;
255}
256
257/*
Daniel Vetterafb21ea62016-08-31 18:09:04 +0200258 * drm_for_each_fb - iterate over all framebuffers
259 * @fb: the loop cursor
260 * @dev: the DRM device
261 *
Daniel Vetterd5745282017-01-25 07:26:45 +0100262 * Iterate over all framebuffers of @dev. User must hold
263 * &drm_mode_config.fb_lock.
Daniel Vetterafb21ea62016-08-31 18:09:04 +0200264 */
265#define drm_for_each_fb(fb, dev) \
266 for (WARN_ON(!mutex_is_locked(&(dev)->mode_config.fb_lock)), \
267 fb = list_first_entry(&(dev)->mode_config.fb_list, \
268 struct drm_framebuffer, head); \
269 &fb->head != (&(dev)->mode_config.fb_list); \
270 fb = list_next_entry(fb, head))
Ville Syrjälä8f8f6a62016-11-18 21:53:05 +0200271
272int drm_framebuffer_plane_width(int width,
273 const struct drm_framebuffer *fb, int plane);
274int drm_framebuffer_plane_height(int height,
275 const struct drm_framebuffer *fb, int plane);
276
Daniel Vetter7520a272016-08-15 16:07:02 +0200277#endif