include/drm/drm_fb_helper.h

   1 /*
   2  * Copyright (c) 2006-2009 Red Hat Inc.
   3  * Copyright (c) 2006-2008 Intel Corporation
   4  * Copyright (c) 2007 Dave Airlie <airlied@linux.ie>
   5  *
   6  * DRM framebuffer helper functions
   7  *
   8  * Permission to use, copy, modify, distribute, and sell this software and its
   9  * documentation for any purpose is hereby granted without fee, provided that
  10  * the above copyright notice appear in all copies and that both that copyright
  11  * notice and this permission notice appear in supporting documentation, and
  12  * that the name of the copyright holders not be used in advertising or
  13  * publicity pertaining to distribution of the software without specific,
  14  * written prior permission.  The copyright holders make no representations
  15  * about the suitability of this software for any purpose.  It is provided "as
  16  * is" without express or implied warranty.
  17  *
  18  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  19  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  20  * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  21  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  22  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  23  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  24  * OF THIS SOFTWARE.
  25  *
  26  * Authors:
  27  *      Dave Airlie <airlied@linux.ie>
  28  *      Jesse Barnes <jesse.barnes@intel.com>
  29  */
  30 #ifndef DRM_FB_HELPER_H
  31 #define DRM_FB_HELPER_H
  32
  33 struct drm_clip_rect;
  34 struct drm_fb_helper;
  35
  36 #include <linux/fb.h>
  37
  38 #include <drm/drm_client.h>
  39
  40 /**
  41  * struct drm_fb_helper_surface_size - describes fbdev size and scanout surface size
  42  * @fb_width: fbdev width
  43  * @fb_height: fbdev height
  44  * @surface_width: scanout buffer width
  45  * @surface_height: scanout buffer height
  46  * @surface_bpp: scanout buffer bpp
  47  * @surface_depth: scanout buffer depth
  48  *
  49  * Note that the scanout surface width/height may be larger than the fbdev
  50  * width/height.  In case of multiple displays, the scanout surface is sized
  51  * according to the largest width/height (so it is large enough for all CRTCs
  52  * to scanout).  But the fbdev width/height is sized to the minimum width/
  53  * height of all the displays.  This ensures that fbcon fits on the smallest
  54  * of the attached displays. fb_width/fb_height is used by
  55  * drm_fb_helper_fill_info() to fill out the &fb_info.var structure.
  56  */
  57 struct drm_fb_helper_surface_size {
  58         u32 fb_width;
  59         u32 fb_height;
  60         u32 surface_width;
  61         u32 surface_height;
  62         u32 surface_bpp;
  63         u32 surface_depth;
  64 };
  65
  66 /**
  67  * struct drm_fb_helper_funcs - driver callbacks for the fbdev emulation library
  68  *
  69  * Driver callbacks used by the fbdev emulation helper library.
  70  */
  71 struct drm_fb_helper_funcs {
  72         /**
  73          * @fb_probe:
  74          *
  75          * Driver callback to allocate and initialize the fbdev info structure.
  76          * Furthermore it also needs to allocate the DRM framebuffer used to
  77          * back the fbdev.
  78          *
  79          * This callback is mandatory.
  80          *
  81          * RETURNS:
  82          *
  83          * The driver should return 0 on success and a negative error code on
  84          * failure.
  85          */
  86         int (*fb_probe)(struct drm_fb_helper *helper,
  87                         struct drm_fb_helper_surface_size *sizes);
  88
  89         /**
  90          * @fb_dirty:
  91          *
  92          * Driver callback to update the framebuffer memory. If set, fbdev
  93          * emulation will invoke this callback in regular intervals after
  94          * the framebuffer has been written.
  95          *
  96          * This callback is optional.
  97          *
  98          * Returns:
  99          * 0 on success, or an error code otherwise.
 100          */
 101         int (*fb_dirty)(struct drm_fb_helper *helper, struct drm_clip_rect *clip);
 102 };
 103
 104 /**
 105  * struct drm_fb_helper - main structure to emulate fbdev on top of KMS
 106  * @fb: Scanout framebuffer object
 107  * @dev: DRM device
 108  * @funcs: driver callbacks for fb helper
 109  * @info: emulated fbdev device info struct
 110  * @pseudo_palette: fake palette of 16 colors
 111  * @damage_clip: clip rectangle used with deferred_io to accumulate damage to
 112  *                the screen buffer
 113  * @damage_lock: spinlock protecting @damage_clip
 114  * @damage_work: worker used to flush the framebuffer
 115  * @resume_work: worker used during resume if the console lock is already taken
 116  *
 117  * This is the main structure used by the fbdev helpers. Drivers supporting
 118  * fbdev emulation should embedded this into their overall driver structure.
 119  * Drivers must also fill out a &struct drm_fb_helper_funcs with a few
 120  * operations.
 121  */
 122 struct drm_fb_helper {
 123         /**
 124          * @client:
 125          *
 126          * DRM client used by the generic fbdev emulation.
 127          */
 128         struct drm_client_dev client;
 129
 130         /**
 131          * @buffer:
 132          *
 133          * Framebuffer used by the generic fbdev emulation.
 134          */
 135         struct drm_client_buffer *buffer;
 136
 137         struct drm_framebuffer *fb;
 138         struct drm_device *dev;
 139         const struct drm_fb_helper_funcs *funcs;
 140         struct fb_info *info;
 141         u32 pseudo_palette[17];
 142         struct drm_clip_rect damage_clip;
 143         spinlock_t damage_lock;
 144         struct work_struct damage_work;
 145         struct work_struct resume_work;
 146
 147         /**
 148          * @lock:
 149          *
 150          * Top-level FBDEV helper lock. This protects all internal data
 151          * structures and lists, such as @connector_info and @crtc_info.
 152          *
 153          * FIXME: fbdev emulation locking is a mess and long term we want to
 154          * protect all helper internal state with this lock as well as reduce
 155          * core KMS locking as much as possible.
 156          */
 157         struct mutex lock;
 158
 159         /**
 160          * @kernel_fb_list:
 161          *
 162          * Entry on the global kernel_fb_helper_list, used for kgdb entry/exit.
 163          */
 164         struct list_head kernel_fb_list;
 165
 166         /**
 167          * @delayed_hotplug:
 168          *
 169          * A hotplug was received while fbdev wasn't in control of the DRM
 170          * device, i.e. another KMS master was active. The output configuration
 171          * needs to be reprobe when fbdev is in control again.
 172          */
 173         bool delayed_hotplug;
 174
 175         /**
 176          * @deferred_setup:
 177          *
 178          * If no outputs are connected (disconnected or unknown) the FB helper
 179          * code will defer setup until at least one of the outputs shows up.
 180          * This field keeps track of the status so that setup can be retried
 181          * at every hotplug event until it succeeds eventually.
 182          *
 183          * Protected by @lock.
 184          */
 185         bool deferred_setup;
 186
 187         /**
 188          * @preferred_bpp:
 189          *
 190          * Temporary storage for the driver's preferred BPP setting passed to
 191          * FB helper initialization. This needs to be tracked so that deferred
 192          * FB helper setup can pass this on.
 193          *
 194          * See also: @deferred_setup
 195          */
 196         int preferred_bpp;
 197
 198 #ifdef CONFIG_FB_DEFERRED_IO
 199         /**
 200          * @fbdefio:
 201          *
 202          * Temporary storage for the driver's FB deferred I/O handler. If the
 203          * driver uses the DRM fbdev emulation layer, this is set by the core
 204          * to a generic deferred I/O handler if a driver is preferring to use
 205          * a shadow buffer.
 206          */
 207         struct fb_deferred_io fbdefio;
 208 #endif
 209 };
 210
 211 static inline struct drm_fb_helper *
 212 drm_fb_helper_from_client(struct drm_client_dev *client)
 213 {
 214         return container_of(client, struct drm_fb_helper, client);
 215 }
 216
 217 /**
 218  * define DRM_FB_HELPER_DEFAULT_OPS - helper define for drm drivers
 219  *
 220  * Helper define to register default implementations of drm_fb_helper
 221  * functions. To be used in struct fb_ops of drm drivers.
 222  */
 223 #define DRM_FB_HELPER_DEFAULT_OPS \
 224         .fb_check_var   = drm_fb_helper_check_var, \
 225         .fb_set_par     = drm_fb_helper_set_par, \
 226         .fb_setcmap     = drm_fb_helper_setcmap, \
 227         .fb_blank       = drm_fb_helper_blank, \
 228         .fb_pan_display = drm_fb_helper_pan_display, \
 229         .fb_debug_enter = drm_fb_helper_debug_enter, \
 230         .fb_debug_leave = drm_fb_helper_debug_leave, \
 231         .fb_ioctl       = drm_fb_helper_ioctl
 232
 233 #ifdef CONFIG_DRM_FBDEV_EMULATION
 234 void drm_fb_helper_prepare(struct drm_device *dev, struct drm_fb_helper *helper,
 235                            unsigned int preferred_bpp,
 236                            const struct drm_fb_helper_funcs *funcs);
 237 void drm_fb_helper_unprepare(struct drm_fb_helper *fb_helper);
 238 int drm_fb_helper_init(struct drm_device *dev, struct drm_fb_helper *helper);
 239 void drm_fb_helper_fini(struct drm_fb_helper *helper);
 240 int drm_fb_helper_blank(int blank, struct fb_info *info);
 241 int drm_fb_helper_pan_display(struct fb_var_screeninfo *var,
 242                               struct fb_info *info);
 243 int drm_fb_helper_set_par(struct fb_info *info);
 244 int drm_fb_helper_check_var(struct fb_var_screeninfo *var,
 245                             struct fb_info *info);
 246
 247 int drm_fb_helper_restore_fbdev_mode_unlocked(struct drm_fb_helper *fb_helper);
 248
 249 struct fb_info *drm_fb_helper_alloc_info(struct drm_fb_helper *fb_helper);
 250 void drm_fb_helper_release_info(struct drm_fb_helper *fb_helper);
 251 void drm_fb_helper_unregister_info(struct drm_fb_helper *fb_helper);
 252 void drm_fb_helper_fill_info(struct fb_info *info,
 253                              struct drm_fb_helper *fb_helper,
 254                              struct drm_fb_helper_surface_size *sizes);
 255
 256 void drm_fb_helper_damage_range(struct fb_info *info, off_t off, size_t len);
 257 void drm_fb_helper_damage_area(struct fb_info *info, u32 x, u32 y, u32 width, u32 height);
 258
 259 #ifdef CONFIG_FB_DEFERRED_IO
 260 void drm_fb_helper_deferred_io(struct fb_info *info, struct list_head *pagereflist);
 261 #endif
 262
 263 void drm_fb_helper_set_suspend(struct drm_fb_helper *fb_helper, bool suspend);
 264 void drm_fb_helper_set_suspend_unlocked(struct drm_fb_helper *fb_helper,
 265                                         bool suspend);
 266
 267 int drm_fb_helper_setcmap(struct fb_cmap *cmap, struct fb_info *info);
 268
 269 int drm_fb_helper_ioctl(struct fb_info *info, unsigned int cmd,
 270                         unsigned long arg);
 271
 272 int drm_fb_helper_hotplug_event(struct drm_fb_helper *fb_helper);
 273 int drm_fb_helper_initial_config(struct drm_fb_helper *fb_helper);
 274 int drm_fb_helper_debug_enter(struct fb_info *info);
 275 int drm_fb_helper_debug_leave(struct fb_info *info);
 276 void drm_fb_helper_lastclose(struct drm_device *dev);
 277 #else
 278 static inline void drm_fb_helper_prepare(struct drm_device *dev,
 279                                          struct drm_fb_helper *helper,
 280                                          unsigned int preferred_bpp,
 281                                          const struct drm_fb_helper_funcs *funcs)
 282 {
 283 }
 284
 285 static inline void drm_fb_helper_unprepare(struct drm_fb_helper *fb_helper)
 286 {
 287 }
 288
 289 static inline int drm_fb_helper_init(struct drm_device *dev,
 290                        struct drm_fb_helper *helper)
 291 {
 292         /* So drivers can use it to free the struct */
 293         helper->dev = dev;
 294         dev->fb_helper = helper;
 295
 296         return 0;
 297 }
 298
 299 static inline void drm_fb_helper_fini(struct drm_fb_helper *helper)
 300 {
 301         if (helper && helper->dev)
 302                 helper->dev->fb_helper = NULL;
 303 }
 304
 305 static inline int drm_fb_helper_blank(int blank, struct fb_info *info)
 306 {
 307         return 0;
 308 }
 309
 310 static inline int drm_fb_helper_pan_display(struct fb_var_screeninfo *var,
 311                                             struct fb_info *info)
 312 {
 313         return 0;
 314 }
 315
 316 static inline int drm_fb_helper_set_par(struct fb_info *info)
 317 {
 318         return 0;
 319 }
 320
 321 static inline int drm_fb_helper_check_var(struct fb_var_screeninfo *var,
 322                                           struct fb_info *info)
 323 {
 324         return 0;
 325 }
 326
 327 static inline int
 328 drm_fb_helper_restore_fbdev_mode_unlocked(struct drm_fb_helper *fb_helper)
 329 {
 330         return 0;
 331 }
 332
 333 static inline struct fb_info *
 334 drm_fb_helper_alloc_info(struct drm_fb_helper *fb_helper)
 335 {
 336         return NULL;
 337 }
 338
 339 static inline void drm_fb_helper_release_info(struct drm_fb_helper *fb_helper)
 340 {
 341 }
 342
 343 static inline void drm_fb_helper_unregister_info(struct drm_fb_helper *fb_helper)
 344 {
 345 }
 346
 347 static inline void
 348 drm_fb_helper_fill_info(struct fb_info *info,
 349                         struct drm_fb_helper *fb_helper,
 350                         struct drm_fb_helper_surface_size *sizes)
 351 {
 352 }
 353
 354 static inline int drm_fb_helper_setcmap(struct fb_cmap *cmap,
 355                                         struct fb_info *info)
 356 {
 357         return 0;
 358 }
 359
 360 static inline int drm_fb_helper_ioctl(struct fb_info *info, unsigned int cmd,
 361                                       unsigned long arg)
 362 {
 363         return 0;
 364 }
 365
 366 #ifdef CONFIG_FB_DEFERRED_IO
 367 static inline void drm_fb_helper_deferred_io(struct fb_info *info,
 368                                              struct list_head *pagelist)
 369 {
 370 }
 371 #endif
 372
 373 static inline void drm_fb_helper_set_suspend(struct drm_fb_helper *fb_helper,
 374                                              bool suspend)
 375 {
 376 }
 377
 378 static inline void
 379 drm_fb_helper_set_suspend_unlocked(struct drm_fb_helper *fb_helper, bool suspend)
 380 {
 381 }
 382
 383 static inline int drm_fb_helper_hotplug_event(struct drm_fb_helper *fb_helper)
 384 {
 385         return 0;
 386 }
 387
 388 static inline int drm_fb_helper_initial_config(struct drm_fb_helper *fb_helper)
 389 {
 390         return 0;
 391 }
 392
 393 static inline int drm_fb_helper_debug_enter(struct fb_info *info)
 394 {
 395         return 0;
 396 }
 397
 398 static inline int drm_fb_helper_debug_leave(struct fb_info *info)
 399 {
 400         return 0;
 401 }
 402
 403 static inline void drm_fb_helper_lastclose(struct drm_device *dev)
 404 {
 405 }
 406 #endif
 407
 408 #endif