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         /**
 199          * @hint_leak_smem_start:
 200          *
 201          * Hint to the fbdev emulation to store the framebuffer's physical
 202          * address in struct &fb_info.fix.smem_start. If the hint is unset,
 203          * the smem_start field should always be cleared to zero.
 204          */
 205         bool hint_leak_smem_start;
 206
 207 #ifdef CONFIG_FB_DEFERRED_IO
 208         /**
 209          * @fbdefio:
 210          *
 211          * Temporary storage for the driver's FB deferred I/O handler. If the
 212          * driver uses the DRM fbdev emulation layer, this is set by the core
 213          * to a generic deferred I/O handler if a driver is preferring to use
 214          * a shadow buffer.
 215          */
 216         struct fb_deferred_io fbdefio;
 217 #endif
 218 };
 219
 220 static inline struct drm_fb_helper *
 221 drm_fb_helper_from_client(struct drm_client_dev *client)
 222 {
 223         return container_of(client, struct drm_fb_helper, client);
 224 }
 225
 226 /**
 227  * define DRM_FB_HELPER_DEFAULT_OPS - helper define for drm drivers
 228  *
 229  * Helper define to register default implementations of drm_fb_helper
 230  * functions. To be used in struct fb_ops of drm drivers.
 231  */
 232 #define DRM_FB_HELPER_DEFAULT_OPS \
 233         .fb_check_var   = drm_fb_helper_check_var, \
 234         .fb_set_par     = drm_fb_helper_set_par, \
 235         .fb_setcmap     = drm_fb_helper_setcmap, \
 236         .fb_blank       = drm_fb_helper_blank, \
 237         .fb_pan_display = drm_fb_helper_pan_display, \
 238         .fb_debug_enter = drm_fb_helper_debug_enter, \
 239         .fb_debug_leave = drm_fb_helper_debug_leave, \
 240         .fb_ioctl       = drm_fb_helper_ioctl
 241
 242 #ifdef CONFIG_DRM_FBDEV_EMULATION
 243 void drm_fb_helper_prepare(struct drm_device *dev, struct drm_fb_helper *helper,
 244                            unsigned int preferred_bpp,
 245                            const struct drm_fb_helper_funcs *funcs);
 246 void drm_fb_helper_unprepare(struct drm_fb_helper *fb_helper);
 247 int drm_fb_helper_init(struct drm_device *dev, struct drm_fb_helper *helper);
 248 void drm_fb_helper_fini(struct drm_fb_helper *helper);
 249 int drm_fb_helper_blank(int blank, struct fb_info *info);
 250 int drm_fb_helper_pan_display(struct fb_var_screeninfo *var,
 251                               struct fb_info *info);
 252 int drm_fb_helper_set_par(struct fb_info *info);
 253 int drm_fb_helper_check_var(struct fb_var_screeninfo *var,
 254                             struct fb_info *info);
 255
 256 int drm_fb_helper_restore_fbdev_mode_unlocked(struct drm_fb_helper *fb_helper);
 257
 258 struct fb_info *drm_fb_helper_alloc_info(struct drm_fb_helper *fb_helper);
 259 void drm_fb_helper_unregister_info(struct drm_fb_helper *fb_helper);
 260 void drm_fb_helper_fill_info(struct fb_info *info,
 261                              struct drm_fb_helper *fb_helper,
 262                              struct drm_fb_helper_surface_size *sizes);
 263
 264 void drm_fb_helper_deferred_io(struct fb_info *info, struct list_head *pagereflist);
 265
 266 ssize_t drm_fb_helper_sys_read(struct fb_info *info, char __user *buf,
 267                                size_t count, loff_t *ppos);
 268 ssize_t drm_fb_helper_sys_write(struct fb_info *info, const char __user *buf,
 269                                 size_t count, loff_t *ppos);
 270
 271 void drm_fb_helper_sys_fillrect(struct fb_info *info,
 272                                 const struct fb_fillrect *rect);
 273 void drm_fb_helper_sys_copyarea(struct fb_info *info,
 274                                 const struct fb_copyarea *area);
 275 void drm_fb_helper_sys_imageblit(struct fb_info *info,
 276                                  const struct fb_image *image);
 277
 278 ssize_t drm_fb_helper_cfb_read(struct fb_info *info, char __user *buf,
 279                                size_t count, loff_t *ppos);
 280 ssize_t drm_fb_helper_cfb_write(struct fb_info *info, const char __user *buf,
 281                                 size_t count, loff_t *ppos);
 282
 283 void drm_fb_helper_cfb_fillrect(struct fb_info *info,
 284                                 const struct fb_fillrect *rect);
 285 void drm_fb_helper_cfb_copyarea(struct fb_info *info,
 286                                 const struct fb_copyarea *area);
 287 void drm_fb_helper_cfb_imageblit(struct fb_info *info,
 288                                  const struct fb_image *image);
 289
 290 void drm_fb_helper_set_suspend(struct drm_fb_helper *fb_helper, bool suspend);
 291 void drm_fb_helper_set_suspend_unlocked(struct drm_fb_helper *fb_helper,
 292                                         bool suspend);
 293
 294 int drm_fb_helper_setcmap(struct fb_cmap *cmap, struct fb_info *info);
 295
 296 int drm_fb_helper_ioctl(struct fb_info *info, unsigned int cmd,
 297                         unsigned long arg);
 298
 299 int drm_fb_helper_hotplug_event(struct drm_fb_helper *fb_helper);
 300 int drm_fb_helper_initial_config(struct drm_fb_helper *fb_helper);
 301 int drm_fb_helper_debug_enter(struct fb_info *info);
 302 int drm_fb_helper_debug_leave(struct fb_info *info);
 303
 304 void drm_fb_helper_lastclose(struct drm_device *dev);
 305 void drm_fb_helper_output_poll_changed(struct drm_device *dev);
 306 #else
 307 static inline void drm_fb_helper_prepare(struct drm_device *dev,
 308                                          struct drm_fb_helper *helper,
 309                                          unsigned int preferred_bpp,
 310                                          const struct drm_fb_helper_funcs *funcs)
 311 {
 312 }
 313
 314 static inline void drm_fb_helper_unprepare(struct drm_fb_helper *fb_helper)
 315 {
 316 }
 317
 318 static inline int drm_fb_helper_init(struct drm_device *dev,
 319                        struct drm_fb_helper *helper)
 320 {
 321         /* So drivers can use it to free the struct */
 322         helper->dev = dev;
 323         dev->fb_helper = helper;
 324
 325         return 0;
 326 }
 327
 328 static inline void drm_fb_helper_fini(struct drm_fb_helper *helper)
 329 {
 330         if (helper && helper->dev)
 331                 helper->dev->fb_helper = NULL;
 332 }
 333
 334 static inline int drm_fb_helper_blank(int blank, struct fb_info *info)
 335 {
 336         return 0;
 337 }
 338
 339 static inline int drm_fb_helper_pan_display(struct fb_var_screeninfo *var,
 340                                             struct fb_info *info)
 341 {
 342         return 0;
 343 }
 344
 345 static inline int drm_fb_helper_set_par(struct fb_info *info)
 346 {
 347         return 0;
 348 }
 349
 350 static inline int drm_fb_helper_check_var(struct fb_var_screeninfo *var,
 351                                           struct fb_info *info)
 352 {
 353         return 0;
 354 }
 355
 356 static inline int
 357 drm_fb_helper_restore_fbdev_mode_unlocked(struct drm_fb_helper *fb_helper)
 358 {
 359         return 0;
 360 }
 361
 362 static inline struct fb_info *
 363 drm_fb_helper_alloc_info(struct drm_fb_helper *fb_helper)
 364 {
 365         return NULL;
 366 }
 367
 368 static inline void drm_fb_helper_unregister_info(struct drm_fb_helper *fb_helper)
 369 {
 370 }
 371
 372 static inline void
 373 drm_fb_helper_fill_info(struct fb_info *info,
 374                         struct drm_fb_helper *fb_helper,
 375                         struct drm_fb_helper_surface_size *sizes)
 376 {
 377 }
 378
 379 static inline int drm_fb_helper_setcmap(struct fb_cmap *cmap,
 380                                         struct fb_info *info)
 381 {
 382         return 0;
 383 }
 384
 385 static inline int drm_fb_helper_ioctl(struct fb_info *info, unsigned int cmd,
 386                                       unsigned long arg)
 387 {
 388         return 0;
 389 }
 390
 391 static inline void drm_fb_helper_deferred_io(struct fb_info *info,
 392                                              struct list_head *pagelist)
 393 {
 394 }
 395
 396 static inline int drm_fb_helper_defio_init(struct drm_fb_helper *fb_helper)
 397 {
 398         return -ENODEV;
 399 }
 400
 401 static inline ssize_t drm_fb_helper_sys_read(struct fb_info *info,
 402                                              char __user *buf, size_t count,
 403                                              loff_t *ppos)
 404 {
 405         return -ENODEV;
 406 }
 407
 408 static inline ssize_t drm_fb_helper_sys_write(struct fb_info *info,
 409                                               const char __user *buf,
 410                                               size_t count, loff_t *ppos)
 411 {
 412         return -ENODEV;
 413 }
 414
 415 static inline void drm_fb_helper_sys_fillrect(struct fb_info *info,
 416                                               const struct fb_fillrect *rect)
 417 {
 418 }
 419
 420 static inline void drm_fb_helper_sys_copyarea(struct fb_info *info,
 421                                               const struct fb_copyarea *area)
 422 {
 423 }
 424
 425 static inline void drm_fb_helper_sys_imageblit(struct fb_info *info,
 426                                                const struct fb_image *image)
 427 {
 428 }
 429
 430 static inline ssize_t drm_fb_helper_cfb_read(struct fb_info *info, char __user *buf,
 431                                              size_t count, loff_t *ppos)
 432 {
 433         return -ENODEV;
 434 }
 435
 436 static inline ssize_t drm_fb_helper_cfb_write(struct fb_info *info, const char __user *buf,
 437                                               size_t count, loff_t *ppos)
 438 {
 439         return -ENODEV;
 440 }
 441
 442 static inline void drm_fb_helper_cfb_fillrect(struct fb_info *info,
 443                                               const struct fb_fillrect *rect)
 444 {
 445 }
 446
 447 static inline void drm_fb_helper_cfb_copyarea(struct fb_info *info,
 448                                               const struct fb_copyarea *area)
 449 {
 450 }
 451
 452 static inline void drm_fb_helper_cfb_imageblit(struct fb_info *info,
 453                                                const struct fb_image *image)
 454 {
 455 }
 456
 457 static inline void drm_fb_helper_set_suspend(struct drm_fb_helper *fb_helper,
 458                                              bool suspend)
 459 {
 460 }
 461
 462 static inline void
 463 drm_fb_helper_set_suspend_unlocked(struct drm_fb_helper *fb_helper, bool suspend)
 464 {
 465 }
 466
 467 static inline int drm_fb_helper_hotplug_event(struct drm_fb_helper *fb_helper)
 468 {
 469         return 0;
 470 }
 471
 472 static inline int drm_fb_helper_initial_config(struct drm_fb_helper *fb_helper)
 473 {
 474         return 0;
 475 }
 476
 477 static inline int drm_fb_helper_debug_enter(struct fb_info *info)
 478 {
 479         return 0;
 480 }
 481
 482 static inline int drm_fb_helper_debug_leave(struct fb_info *info)
 483 {
 484         return 0;
 485 }
 486
 487 static inline void drm_fb_helper_lastclose(struct drm_device *dev)
 488 {
 489 }
 490
 491 static inline void drm_fb_helper_output_poll_changed(struct drm_device *dev)
 492 {
 493 }
 494 #endif
 495
 496 #endif