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_deferred_io(struct fb_info *info, struct list_head *pagereflist);
 257
 258 ssize_t drm_fb_helper_sys_read(struct fb_info *info, char __user *buf,
 259                                size_t count, loff_t *ppos);
 260 ssize_t drm_fb_helper_sys_write(struct fb_info *info, const char __user *buf,
 261                                 size_t count, loff_t *ppos);
 262
 263 void drm_fb_helper_sys_fillrect(struct fb_info *info,
 264                                 const struct fb_fillrect *rect);
 265 void drm_fb_helper_sys_copyarea(struct fb_info *info,
 266                                 const struct fb_copyarea *area);
 267 void drm_fb_helper_sys_imageblit(struct fb_info *info,
 268                                  const struct fb_image *image);
 269
 270 ssize_t drm_fb_helper_cfb_read(struct fb_info *info, char __user *buf,
 271                                size_t count, loff_t *ppos);
 272 ssize_t drm_fb_helper_cfb_write(struct fb_info *info, const char __user *buf,
 273                                 size_t count, loff_t *ppos);
 274
 275 void drm_fb_helper_cfb_fillrect(struct fb_info *info,
 276                                 const struct fb_fillrect *rect);
 277 void drm_fb_helper_cfb_copyarea(struct fb_info *info,
 278                                 const struct fb_copyarea *area);
 279 void drm_fb_helper_cfb_imageblit(struct fb_info *info,
 280                                  const struct fb_image *image);
 281
 282 void drm_fb_helper_set_suspend(struct drm_fb_helper *fb_helper, bool suspend);
 283 void drm_fb_helper_set_suspend_unlocked(struct drm_fb_helper *fb_helper,
 284                                         bool suspend);
 285
 286 int drm_fb_helper_setcmap(struct fb_cmap *cmap, struct fb_info *info);
 287
 288 int drm_fb_helper_ioctl(struct fb_info *info, unsigned int cmd,
 289                         unsigned long arg);
 290
 291 int drm_fb_helper_hotplug_event(struct drm_fb_helper *fb_helper);
 292 int drm_fb_helper_initial_config(struct drm_fb_helper *fb_helper);
 293 int drm_fb_helper_debug_enter(struct fb_info *info);
 294 int drm_fb_helper_debug_leave(struct fb_info *info);
 295
 296 void drm_fb_helper_lastclose(struct drm_device *dev);
 297 void drm_fb_helper_output_poll_changed(struct drm_device *dev);
 298 #else
 299 static inline void drm_fb_helper_prepare(struct drm_device *dev,
 300                                          struct drm_fb_helper *helper,
 301                                          unsigned int preferred_bpp,
 302                                          const struct drm_fb_helper_funcs *funcs)
 303 {
 304 }
 305
 306 static inline void drm_fb_helper_unprepare(struct drm_fb_helper *fb_helper)
 307 {
 308 }
 309
 310 static inline int drm_fb_helper_init(struct drm_device *dev,
 311                        struct drm_fb_helper *helper)
 312 {
 313         /* So drivers can use it to free the struct */
 314         helper->dev = dev;
 315         dev->fb_helper = helper;
 316
 317         return 0;
 318 }
 319
 320 static inline void drm_fb_helper_fini(struct drm_fb_helper *helper)
 321 {
 322         if (helper && helper->dev)
 323                 helper->dev->fb_helper = NULL;
 324 }
 325
 326 static inline int drm_fb_helper_blank(int blank, struct fb_info *info)
 327 {
 328         return 0;
 329 }
 330
 331 static inline int drm_fb_helper_pan_display(struct fb_var_screeninfo *var,
 332                                             struct fb_info *info)
 333 {
 334         return 0;
 335 }
 336
 337 static inline int drm_fb_helper_set_par(struct fb_info *info)
 338 {
 339         return 0;
 340 }
 341
 342 static inline int drm_fb_helper_check_var(struct fb_var_screeninfo *var,
 343                                           struct fb_info *info)
 344 {
 345         return 0;
 346 }
 347
 348 static inline int
 349 drm_fb_helper_restore_fbdev_mode_unlocked(struct drm_fb_helper *fb_helper)
 350 {
 351         return 0;
 352 }
 353
 354 static inline struct fb_info *
 355 drm_fb_helper_alloc_info(struct drm_fb_helper *fb_helper)
 356 {
 357         return NULL;
 358 }
 359
 360 static inline void drm_fb_helper_release_info(struct drm_fb_helper *fb_helper)
 361 {
 362 }
 363
 364 static inline void drm_fb_helper_unregister_info(struct drm_fb_helper *fb_helper)
 365 {
 366 }
 367
 368 static inline void
 369 drm_fb_helper_fill_info(struct fb_info *info,
 370                         struct drm_fb_helper *fb_helper,
 371                         struct drm_fb_helper_surface_size *sizes)
 372 {
 373 }
 374
 375 static inline int drm_fb_helper_setcmap(struct fb_cmap *cmap,
 376                                         struct fb_info *info)
 377 {
 378         return 0;
 379 }
 380
 381 static inline int drm_fb_helper_ioctl(struct fb_info *info, unsigned int cmd,
 382                                       unsigned long arg)
 383 {
 384         return 0;
 385 }
 386
 387 static inline void drm_fb_helper_deferred_io(struct fb_info *info,
 388                                              struct list_head *pagelist)
 389 {
 390 }
 391
 392 static inline int drm_fb_helper_defio_init(struct drm_fb_helper *fb_helper)
 393 {
 394         return -ENODEV;
 395 }
 396
 397 static inline ssize_t drm_fb_helper_sys_read(struct fb_info *info,
 398                                              char __user *buf, size_t count,
 399                                              loff_t *ppos)
 400 {
 401         return -ENODEV;
 402 }
 403
 404 static inline ssize_t drm_fb_helper_sys_write(struct fb_info *info,
 405                                               const char __user *buf,
 406                                               size_t count, loff_t *ppos)
 407 {
 408         return -ENODEV;
 409 }
 410
 411 static inline void drm_fb_helper_sys_fillrect(struct fb_info *info,
 412                                               const struct fb_fillrect *rect)
 413 {
 414 }
 415
 416 static inline void drm_fb_helper_sys_copyarea(struct fb_info *info,
 417                                               const struct fb_copyarea *area)
 418 {
 419 }
 420
 421 static inline void drm_fb_helper_sys_imageblit(struct fb_info *info,
 422                                                const struct fb_image *image)
 423 {
 424 }
 425
 426 static inline ssize_t drm_fb_helper_cfb_read(struct fb_info *info, char __user *buf,
 427                                              size_t count, loff_t *ppos)
 428 {
 429         return -ENODEV;
 430 }
 431
 432 static inline ssize_t drm_fb_helper_cfb_write(struct fb_info *info, const char __user *buf,
 433                                               size_t count, loff_t *ppos)
 434 {
 435         return -ENODEV;
 436 }
 437
 438 static inline void drm_fb_helper_cfb_fillrect(struct fb_info *info,
 439                                               const struct fb_fillrect *rect)
 440 {
 441 }
 442
 443 static inline void drm_fb_helper_cfb_copyarea(struct fb_info *info,
 444                                               const struct fb_copyarea *area)
 445 {
 446 }
 447
 448 static inline void drm_fb_helper_cfb_imageblit(struct fb_info *info,
 449                                                const struct fb_image *image)
 450 {
 451 }
 452
 453 static inline void drm_fb_helper_set_suspend(struct drm_fb_helper *fb_helper,
 454                                              bool suspend)
 455 {
 456 }
 457
 458 static inline void
 459 drm_fb_helper_set_suspend_unlocked(struct drm_fb_helper *fb_helper, bool suspend)
 460 {
 461 }
 462
 463 static inline int drm_fb_helper_hotplug_event(struct drm_fb_helper *fb_helper)
 464 {
 465         return 0;
 466 }
 467
 468 static inline int drm_fb_helper_initial_config(struct drm_fb_helper *fb_helper)
 469 {
 470         return 0;
 471 }
 472
 473 static inline int drm_fb_helper_debug_enter(struct fb_info *info)
 474 {
 475         return 0;
 476 }
 477
 478 static inline int drm_fb_helper_debug_leave(struct fb_info *info)
 479 {
 480         return 0;
 481 }
 482
 483 static inline void drm_fb_helper_lastclose(struct drm_device *dev)
 484 {
 485 }
 486
 487 static inline void drm_fb_helper_output_poll_changed(struct drm_device *dev)
 488 {
 489 }
 490 #endif
 491
 492 #endif