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/bits.h> 27 #include <linux/ctype.h> 28 #include <linux/list.h> 29 #include <linux/sched.h> 30 31 #include <drm/drm_fourcc.h> 32 #include <drm/drm_mode_object.h> 33 34 struct drm_clip_rect; 35 struct drm_device; 36 struct drm_file; 37 struct drm_framebuffer; 38 struct drm_gem_object; 39 40 /** 41 * struct drm_framebuffer_funcs - framebuffer hooks 42 */ 43 struct drm_framebuffer_funcs { 44 /** 45 * @destroy: 46 * 47 * Clean up framebuffer resources, specifically also unreference the 48 * backing storage. The core guarantees to call this function for every 49 * framebuffer successfully created by calling 50 * &drm_mode_config_funcs.fb_create. Drivers must also call 51 * drm_framebuffer_cleanup() to release DRM core resources for this 52 * framebuffer. 53 */ 54 void (*destroy)(struct drm_framebuffer *framebuffer); 55 56 /** 57 * @create_handle: 58 * 59 * Create a buffer handle in the driver-specific buffer manager (either 60 * GEM or TTM) valid for the passed-in &struct drm_file. This is used by 61 * the core to implement the GETFB IOCTL, which returns (for 62 * sufficiently priviledged user) also a native buffer handle. This can 63 * be used for seamless transitions between modesetting clients by 64 * copying the current screen contents to a private buffer and blending 65 * between that and the new contents. 66 * 67 * GEM based drivers should call drm_gem_handle_create() to create the 68 * handle. 69 * 70 * RETURNS: 71 * 72 * 0 on success or a negative error code on failure. 73 */ 74 int (*create_handle)(struct drm_framebuffer *fb, 75 struct drm_file *file_priv, 76 unsigned int *handle); 77 /** 78 * @dirty: 79 * 80 * Optional callback for the dirty fb IOCTL. 81 * 82 * Userspace can notify the driver via this callback that an area of the 83 * framebuffer has changed and should be flushed to the display 84 * hardware. This can also be used internally, e.g. by the fbdev 85 * emulation, though that's not the case currently. 86 * 87 * See documentation in drm_mode.h for the struct drm_mode_fb_dirty_cmd 88 * for more information as all the semantics and arguments have a one to 89 * one mapping on this function. 90 * 91 * Atomic drivers should use drm_atomic_helper_dirtyfb() to implement 92 * this hook. 93 * 94 * RETURNS: 95 * 96 * 0 on success or a negative error code on failure. 97 */ 98 int (*dirty)(struct drm_framebuffer *framebuffer, 99 struct drm_file *file_priv, unsigned flags, 100 unsigned color, struct drm_clip_rect *clips, 101 unsigned num_clips); 102 }; 103 104 #define DRM_FRAMEBUFFER_HAS_HANDLE_REF(_i) BIT(0u + (_i)) 105 106 /** 107 * struct drm_framebuffer - frame buffer object 108 * 109 * Note that the fb is refcounted for the benefit of driver internals, 110 * for example some hw, disabling a CRTC/plane is asynchronous, and 111 * scanout does not actually complete until the next vblank. So some 112 * cleanup (like releasing the reference(s) on the backing GEM bo(s)) 113 * should be deferred. In cases like this, the driver would like to 114 * hold a ref to the fb even though it has already been removed from 115 * userspace perspective. See drm_framebuffer_get() and 116 * drm_framebuffer_put(). 117 * 118 * The refcount is stored inside the mode object @base. 119 */ 120 struct drm_framebuffer { 121 /** 122 * @dev: DRM device this framebuffer belongs to 123 */ 124 struct drm_device *dev; 125 /** 126 * @head: Place on the &drm_mode_config.fb_list, access protected by 127 * &drm_mode_config.fb_lock. 128 */ 129 struct list_head head; 130 131 /** 132 * @base: base modeset object structure, contains the reference count. 133 */ 134 struct drm_mode_object base; 135 136 /** 137 * @comm: Name of the process allocating the fb, used for fb dumping. 138 */ 139 char comm[TASK_COMM_LEN]; 140 141 /** 142 * @format: framebuffer format information 143 */ 144 const struct drm_format_info *format; 145 /** 146 * @funcs: framebuffer vfunc table 147 */ 148 const struct drm_framebuffer_funcs *funcs; 149 /** 150 * @pitches: Line stride per buffer. For userspace created object this 151 * is copied from drm_mode_fb_cmd2. 152 */ 153 unsigned int pitches[DRM_FORMAT_MAX_PLANES]; 154 /** 155 * @offsets: Offset from buffer start to the actual pixel data in bytes, 156 * per buffer. For userspace created object this is copied from 157 * drm_mode_fb_cmd2. 158 * 159 * Note that this is a linear offset and does not take into account 160 * tiling or buffer layout per @modifier. It is meant to be used when 161 * the actual pixel data for this framebuffer plane starts at an offset, 162 * e.g. when multiple planes are allocated within the same backing 163 * storage buffer object. For tiled layouts this generally means its 164 * @offsets must at least be tile-size aligned, but hardware often has 165 * stricter requirements. 166 * 167 * This should not be used to specifiy x/y pixel offsets into the buffer 168 * data (even for linear buffers). Specifying an x/y pixel offset is 169 * instead done through the source rectangle in &struct drm_plane_state. 170 */ 171 unsigned int offsets[DRM_FORMAT_MAX_PLANES]; 172 /** 173 * @modifier: Data layout modifier. This is used to describe 174 * tiling, or also special layouts (like compression) of auxiliary 175 * buffers. For userspace created object this is copied from 176 * drm_mode_fb_cmd2. 177 */ 178 uint64_t modifier; 179 /** 180 * @width: Logical width of the visible area of the framebuffer, in 181 * pixels. 182 */ 183 unsigned int width; 184 /** 185 * @height: Logical height of the visible area of the framebuffer, in 186 * pixels. 187 */ 188 unsigned int height; 189 /** 190 * @flags: Framebuffer flags like DRM_MODE_FB_INTERLACED or 191 * DRM_MODE_FB_MODIFIERS. 192 */ 193 int flags; 194 /** 195 * @internal_flags: Framebuffer flags like DRM_FRAMEBUFFER_HAS_HANDLE_REF. 196 */ 197 unsigned int internal_flags; 198 /** 199 * @filp_head: Placed on &drm_file.fbs, protected by &drm_file.fbs_lock. 200 */ 201 struct list_head filp_head; 202 /** 203 * @obj: GEM objects backing the framebuffer, one per plane (optional). 204 * 205 * This is used by the GEM framebuffer helpers, see e.g. 206 * drm_gem_fb_create(). 207 */ 208 struct drm_gem_object *obj[DRM_FORMAT_MAX_PLANES]; 209 }; 210 211 #define obj_to_fb(x) container_of(x, struct drm_framebuffer, base) 212 213 int drm_framebuffer_init(struct drm_device *dev, 214 struct drm_framebuffer *fb, 215 const struct drm_framebuffer_funcs *funcs); 216 struct drm_framebuffer *drm_framebuffer_lookup(struct drm_device *dev, 217 struct drm_file *file_priv, 218 uint32_t id); 219 void drm_framebuffer_remove(struct drm_framebuffer *fb); 220 void drm_framebuffer_cleanup(struct drm_framebuffer *fb); 221 void drm_framebuffer_unregister_private(struct drm_framebuffer *fb); 222 223 /** 224 * drm_framebuffer_get - acquire a framebuffer reference 225 * @fb: DRM framebuffer 226 * 227 * This function increments the framebuffer's reference count. 228 */ 229 static inline void drm_framebuffer_get(struct drm_framebuffer *fb) 230 { 231 drm_mode_object_get(&fb->base); 232 } 233 234 /** 235 * drm_framebuffer_put - release a framebuffer reference 236 * @fb: DRM framebuffer 237 * 238 * This function decrements the framebuffer's reference count and frees the 239 * framebuffer if the reference count drops to zero. 240 */ 241 static inline void drm_framebuffer_put(struct drm_framebuffer *fb) 242 { 243 drm_mode_object_put(&fb->base); 244 } 245 246 /** 247 * drm_framebuffer_read_refcount - read the framebuffer reference count. 248 * @fb: framebuffer 249 * 250 * This functions returns the framebuffer's reference count. 251 */ 252 static inline uint32_t drm_framebuffer_read_refcount(const struct drm_framebuffer *fb) 253 { 254 return kref_read(&fb->base.refcount); 255 } 256 257 /** 258 * drm_framebuffer_assign - store a reference to the fb 259 * @p: location to store framebuffer 260 * @fb: new framebuffer (maybe NULL) 261 * 262 * This functions sets the location to store a reference to the framebuffer, 263 * unreferencing the framebuffer that was previously stored in that location. 264 */ 265 static inline void drm_framebuffer_assign(struct drm_framebuffer **p, 266 struct drm_framebuffer *fb) 267 { 268 if (fb) 269 drm_framebuffer_get(fb); 270 if (*p) 271 drm_framebuffer_put(*p); 272 *p = fb; 273 } 274 275 /* 276 * drm_for_each_fb - iterate over all framebuffers 277 * @fb: the loop cursor 278 * @dev: the DRM device 279 * 280 * Iterate over all framebuffers of @dev. User must hold 281 * &drm_mode_config.fb_lock. 282 */ 283 #define drm_for_each_fb(fb, dev) \ 284 for (WARN_ON(!mutex_is_locked(&(dev)->mode_config.fb_lock)), \ 285 fb = list_first_entry(&(dev)->mode_config.fb_list, \ 286 struct drm_framebuffer, head); \ 287 &fb->head != (&(dev)->mode_config.fb_list); \ 288 fb = list_next_entry(fb, head)) 289 290 /** 291 * struct drm_afbc_framebuffer - a special afbc frame buffer object 292 * 293 * A derived class of struct drm_framebuffer, dedicated for afbc use cases. 294 */ 295 struct drm_afbc_framebuffer { 296 /** 297 * @base: base framebuffer structure. 298 */ 299 struct drm_framebuffer base; 300 /** 301 * @block_width: width of a single afbc block 302 */ 303 u32 block_width; 304 /** 305 * @block_height: height of a single afbc block 306 */ 307 u32 block_height; 308 /** 309 * @aligned_width: aligned frame buffer width 310 */ 311 u32 aligned_width; 312 /** 313 * @aligned_height: aligned frame buffer height 314 */ 315 u32 aligned_height; 316 /** 317 * @offset: offset of the first afbc header 318 */ 319 u32 offset; 320 /** 321 * @afbc_size: minimum size of afbc buffer 322 */ 323 u32 afbc_size; 324 }; 325 326 #define fb_to_afbc_fb(x) container_of(x, struct drm_afbc_framebuffer, base) 327 328 #endif 329