Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 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> |
Daniel Vetter | 949619f | 2016-08-29 10:27:51 +0200 | [diff] [blame^] | 28 | #include <drm/drm_mode_object.h> |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 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 |
| 43 | * framebuffer successfully created by ->fb_create() in |
| 44 | * &drm_mode_config_funcs. Drivers must also call |
| 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 |
| 54 | * GEM or TTM) valid for the passed-in struct &drm_file. This is used by |
| 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 | |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 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 |
| 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 Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 109 | struct drm_framebuffer { |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 110 | /** |
| 111 | * @dev: DRM device this framebuffer belongs to |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 112 | */ |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 113 | struct drm_device *dev; |
| 114 | /** |
| 115 | * @head: Place on the dev->mode_config.fb_list, access protected by |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 116 | * dev->mode_config.fb_lock. |
| 117 | */ |
| 118 | struct list_head head; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 119 | |
| 120 | /** |
| 121 | * @base: base modeset object structure, contains the reference count. |
| 122 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 123 | struct drm_mode_object base; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 124 | /** |
| 125 | * @funcs: framebuffer vfunc table |
| 126 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 127 | const struct drm_framebuffer_funcs *funcs; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 128 | /** |
| 129 | * @pitches: Line stride per buffer. For userspace created object this |
| 130 | * is copied from drm_mode_fb_cmd2. |
| 131 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 132 | unsigned int pitches[4]; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 133 | /** |
| 134 | * @offsets: Offset from buffer start to the actual pixel data in bytes, |
| 135 | * per buffer. For userspace created object this is copied from |
| 136 | * drm_mode_fb_cmd2. |
| 137 | * |
| 138 | * Note that this is a linear offset and does not take into account |
| 139 | * tiling or buffer laytou per @modifier. It meant to be used when the |
| 140 | * actual pixel data for this framebuffer plane starts at an offset, |
| 141 | * e.g. when multiple planes are allocated within the same backing |
| 142 | * storage buffer object. For tiled layouts this generally means it |
| 143 | * @offsets must at least be tile-size aligned, but hardware often has |
| 144 | * stricter requirements. |
| 145 | * |
| 146 | * This should not be used to specifiy x/y pixel offsets into the buffer |
| 147 | * data (even for linear buffers). Specifying an x/y pixel offset is |
| 148 | * instead done through the source rectangle in struct &drm_plane_state. |
| 149 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 150 | unsigned int offsets[4]; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 151 | /** |
| 152 | * @modifier: Data layout modifier, per buffer. This is used to describe |
| 153 | * tiling, or also special layouts (like compression) of auxiliary |
| 154 | * buffers. For userspace created object this is copied from |
| 155 | * drm_mode_fb_cmd2. |
| 156 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 157 | uint64_t modifier[4]; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 158 | /** |
| 159 | * @width: Logical width of the visible area of the framebuffer, in |
| 160 | * pixels. |
| 161 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 162 | unsigned int width; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 163 | /** |
| 164 | * @height: Logical height of the visible area of the framebuffer, in |
| 165 | * pixels. |
| 166 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 167 | unsigned int height; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 168 | /** |
| 169 | * @depth: Depth in bits per pixel for RGB formats. 0 for everything |
| 170 | * else. Legacy information derived from @pixel_format, it's suggested to use |
| 171 | * the DRM FOURCC codes and helper functions directly instead. |
| 172 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 173 | unsigned int depth; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 174 | /** |
| 175 | * @bits_per_pixel: Storage used bits per pixel for RGB formats. 0 for |
| 176 | * everything else. Legacy information derived from @pixel_format, it's |
| 177 | * suggested to use the DRM FOURCC codes and helper functions directly |
| 178 | * instead. |
| 179 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 180 | int bits_per_pixel; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 181 | /** |
| 182 | * @flags: Framebuffer flags like DRM_MODE_FB_INTERLACED or |
| 183 | * DRM_MODE_FB_MODIFIERS. |
| 184 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 185 | int flags; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 186 | /** |
| 187 | * @pixel_format: DRM FOURCC code describing the pixel format. |
| 188 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 189 | uint32_t pixel_format; /* fourcc format */ |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 190 | /** |
| 191 | * @hot_x: X coordinate of the cursor hotspot. Used by the legacy cursor |
| 192 | * IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR |
| 193 | * universal plane. |
| 194 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 195 | int hot_x; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 196 | /** |
| 197 | * @hot_y: Y coordinate of the cursor hotspot. Used by the legacy cursor |
| 198 | * IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR |
| 199 | * universal plane. |
| 200 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 201 | int hot_y; |
Daniel Vetter | 750fb8c | 2016-08-12 22:48:48 +0200 | [diff] [blame] | 202 | /** |
| 203 | * @filp_head: Placed on struct &drm_file fbs list_head, protected by |
| 204 | * fbs_lock in the same structure. |
| 205 | */ |
Daniel Vetter | 7520a27 | 2016-08-15 16:07:02 +0200 | [diff] [blame] | 206 | struct list_head filp_head; |
| 207 | }; |
| 208 | |
| 209 | int drm_framebuffer_init(struct drm_device *dev, |
| 210 | struct drm_framebuffer *fb, |
| 211 | const struct drm_framebuffer_funcs *funcs); |
| 212 | struct drm_framebuffer *drm_framebuffer_lookup(struct drm_device *dev, |
| 213 | uint32_t id); |
| 214 | void drm_framebuffer_remove(struct drm_framebuffer *fb); |
| 215 | void drm_framebuffer_cleanup(struct drm_framebuffer *fb); |
| 216 | void drm_framebuffer_unregister_private(struct drm_framebuffer *fb); |
| 217 | |
| 218 | /** |
| 219 | * drm_framebuffer_reference - incr the fb refcnt |
| 220 | * @fb: framebuffer |
| 221 | * |
| 222 | * This functions increments the fb's refcount. |
| 223 | */ |
| 224 | static inline void drm_framebuffer_reference(struct drm_framebuffer *fb) |
| 225 | { |
| 226 | drm_mode_object_reference(&fb->base); |
| 227 | } |
| 228 | |
| 229 | /** |
| 230 | * drm_framebuffer_unreference - unref a framebuffer |
| 231 | * @fb: framebuffer to unref |
| 232 | * |
| 233 | * This functions decrements the fb's refcount and frees it if it drops to zero. |
| 234 | */ |
| 235 | static inline void drm_framebuffer_unreference(struct drm_framebuffer *fb) |
| 236 | { |
| 237 | drm_mode_object_unreference(&fb->base); |
| 238 | } |
| 239 | |
| 240 | /** |
| 241 | * drm_framebuffer_read_refcount - read the framebuffer reference count. |
| 242 | * @fb: framebuffer |
| 243 | * |
| 244 | * This functions returns the framebuffer's reference count. |
| 245 | */ |
| 246 | static inline uint32_t drm_framebuffer_read_refcount(struct drm_framebuffer *fb) |
| 247 | { |
| 248 | return atomic_read(&fb->base.refcount.refcount); |
| 249 | } |
| 250 | #endif |