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_PLANE_H__ 24 #define __DRM_PLANE_H__ 25 26 #include <linux/list.h> 27 #include <linux/ctype.h> 28 #include <drm/drm_mode_object.h> 29 30 struct drm_crtc; 31 struct drm_printer; 32 33 /** 34 * struct drm_plane_state - mutable plane state 35 * @plane: backpointer to the plane 36 * @crtc_w: width of visible portion of plane on crtc 37 * @crtc_h: height of visible portion of plane on crtc 38 * @src_x: left position of visible portion of plane within 39 * plane (in 16.16) 40 * @src_y: upper position of visible portion of plane within 41 * plane (in 16.16) 42 * @src_w: width of visible portion of plane (in 16.16) 43 * @src_h: height of visible portion of plane (in 16.16) 44 * @rotation: rotation of the plane 45 * @zpos: priority of the given plane on crtc (optional) 46 * Note that multiple active planes on the same crtc can have an identical 47 * zpos value. The rule to solving the conflict is to compare the plane 48 * object IDs; the plane with a higher ID must be stacked on top of a 49 * plane with a lower ID. 50 * @normalized_zpos: normalized value of zpos: unique, range from 0 to N-1 51 * where N is the number of active planes for given crtc. Note that 52 * the driver must call drm_atomic_normalize_zpos() to update this before 53 * it can be trusted. 54 * @src: clipped source coordinates of the plane (in 16.16) 55 * @dst: clipped destination coordinates of the plane 56 * @state: backpointer to global drm_atomic_state 57 */ 58 struct drm_plane_state { 59 struct drm_plane *plane; 60 61 /** 62 * @crtc: 63 * 64 * Currently bound CRTC, NULL if disabled. Do not this write directly, 65 * use drm_atomic_set_crtc_for_plane() 66 */ 67 struct drm_crtc *crtc; 68 69 /** 70 * @fb: 71 * 72 * Currently bound framebuffer. Do not write this directly, use 73 * drm_atomic_set_fb_for_plane() 74 */ 75 struct drm_framebuffer *fb; 76 77 /** 78 * @fence: 79 * 80 * Optional fence to wait for before scanning out @fb. Do not write this 81 * directly, use drm_atomic_set_fence_for_plane() 82 */ 83 struct dma_fence *fence; 84 85 /** 86 * @crtc_x: 87 * 88 * Left position of visible portion of plane on crtc, signed dest 89 * location allows it to be partially off screen. 90 */ 91 92 int32_t crtc_x; 93 /** 94 * @crtc_y: 95 * 96 * Upper position of visible portion of plane on crtc, signed dest 97 * location allows it to be partially off screen. 98 */ 99 int32_t crtc_y; 100 101 uint32_t crtc_w, crtc_h; 102 103 /* Source values are 16.16 fixed point */ 104 uint32_t src_x, src_y; 105 uint32_t src_h, src_w; 106 107 /* Plane rotation */ 108 unsigned int rotation; 109 110 /* Plane zpos */ 111 unsigned int zpos; 112 unsigned int normalized_zpos; 113 114 /* Clipped coordinates */ 115 struct drm_rect src, dst; 116 117 /** 118 * @visible: 119 * 120 * Visibility of the plane. This can be false even if fb!=NULL and 121 * crtc!=NULL, due to clipping. 122 */ 123 bool visible; 124 125 struct drm_atomic_state *state; 126 }; 127 128 static inline struct drm_rect 129 drm_plane_state_src(const struct drm_plane_state *state) 130 { 131 struct drm_rect src = { 132 .x1 = state->src_x, 133 .y1 = state->src_y, 134 .x2 = state->src_x + state->src_w, 135 .y2 = state->src_y + state->src_h, 136 }; 137 return src; 138 } 139 140 static inline struct drm_rect 141 drm_plane_state_dest(const struct drm_plane_state *state) 142 { 143 struct drm_rect dest = { 144 .x1 = state->crtc_x, 145 .y1 = state->crtc_y, 146 .x2 = state->crtc_x + state->crtc_w, 147 .y2 = state->crtc_y + state->crtc_h, 148 }; 149 return dest; 150 } 151 152 /** 153 * struct drm_plane_funcs - driver plane control functions 154 */ 155 struct drm_plane_funcs { 156 /** 157 * @update_plane: 158 * 159 * This is the legacy entry point to enable and configure the plane for 160 * the given CRTC and framebuffer. It is never called to disable the 161 * plane, i.e. the passed-in crtc and fb paramters are never NULL. 162 * 163 * The source rectangle in frame buffer memory coordinates is given by 164 * the src_x, src_y, src_w and src_h parameters (as 16.16 fixed point 165 * values). Devices that don't support subpixel plane coordinates can 166 * ignore the fractional part. 167 * 168 * The destination rectangle in CRTC coordinates is given by the 169 * crtc_x, crtc_y, crtc_w and crtc_h parameters (as integer values). 170 * Devices scale the source rectangle to the destination rectangle. If 171 * scaling is not supported, and the source rectangle size doesn't match 172 * the destination rectangle size, the driver must return a 173 * -<errorname>EINVAL</errorname> error. 174 * 175 * Drivers implementing atomic modeset should use 176 * drm_atomic_helper_update_plane() to implement this hook. 177 * 178 * RETURNS: 179 * 180 * 0 on success or a negative error code on failure. 181 */ 182 int (*update_plane)(struct drm_plane *plane, 183 struct drm_crtc *crtc, struct drm_framebuffer *fb, 184 int crtc_x, int crtc_y, 185 unsigned int crtc_w, unsigned int crtc_h, 186 uint32_t src_x, uint32_t src_y, 187 uint32_t src_w, uint32_t src_h); 188 189 /** 190 * @disable_plane: 191 * 192 * This is the legacy entry point to disable the plane. The DRM core 193 * calls this method in response to a DRM_IOCTL_MODE_SETPLANE IOCTL call 194 * with the frame buffer ID set to 0. Disabled planes must not be 195 * processed by the CRTC. 196 * 197 * Drivers implementing atomic modeset should use 198 * drm_atomic_helper_disable_plane() to implement this hook. 199 * 200 * RETURNS: 201 * 202 * 0 on success or a negative error code on failure. 203 */ 204 int (*disable_plane)(struct drm_plane *plane); 205 206 /** 207 * @destroy: 208 * 209 * Clean up plane resources. This is only called at driver unload time 210 * through drm_mode_config_cleanup() since a plane cannot be hotplugged 211 * in DRM. 212 */ 213 void (*destroy)(struct drm_plane *plane); 214 215 /** 216 * @reset: 217 * 218 * Reset plane hardware and software state to off. This function isn't 219 * called by the core directly, only through drm_mode_config_reset(). 220 * It's not a helper hook only for historical reasons. 221 * 222 * Atomic drivers can use drm_atomic_helper_plane_reset() to reset 223 * atomic state using this hook. 224 */ 225 void (*reset)(struct drm_plane *plane); 226 227 /** 228 * @set_property: 229 * 230 * This is the legacy entry point to update a property attached to the 231 * plane. 232 * 233 * Drivers implementing atomic modeset should use 234 * drm_atomic_helper_plane_set_property() to implement this hook. 235 * 236 * This callback is optional if the driver does not support any legacy 237 * driver-private properties. 238 * 239 * RETURNS: 240 * 241 * 0 on success or a negative error code on failure. 242 */ 243 int (*set_property)(struct drm_plane *plane, 244 struct drm_property *property, uint64_t val); 245 246 /** 247 * @atomic_duplicate_state: 248 * 249 * Duplicate the current atomic state for this plane and return it. 250 * The core and helpers guarantee that any atomic state duplicated with 251 * this hook and still owned by the caller (i.e. not transferred to the 252 * driver by calling &drm_mode_config_funcs.atomic_commit) will be 253 * cleaned up by calling the @atomic_destroy_state hook in this 254 * structure. 255 * 256 * Atomic drivers which don't subclass &struct drm_plane_state should use 257 * drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the 258 * state structure to extend it with driver-private state should use 259 * __drm_atomic_helper_plane_duplicate_state() to make sure shared state is 260 * duplicated in a consistent fashion across drivers. 261 * 262 * It is an error to call this hook before &drm_plane.state has been 263 * initialized correctly. 264 * 265 * NOTE: 266 * 267 * If the duplicate state references refcounted resources this hook must 268 * acquire a reference for each of them. The driver must release these 269 * references again in @atomic_destroy_state. 270 * 271 * RETURNS: 272 * 273 * Duplicated atomic state or NULL when the allocation failed. 274 */ 275 struct drm_plane_state *(*atomic_duplicate_state)(struct drm_plane *plane); 276 277 /** 278 * @atomic_destroy_state: 279 * 280 * Destroy a state duplicated with @atomic_duplicate_state and release 281 * or unreference all resources it references 282 */ 283 void (*atomic_destroy_state)(struct drm_plane *plane, 284 struct drm_plane_state *state); 285 286 /** 287 * @atomic_set_property: 288 * 289 * Decode a driver-private property value and store the decoded value 290 * into the passed-in state structure. Since the atomic core decodes all 291 * standardized properties (even for extensions beyond the core set of 292 * properties which might not be implemented by all drivers) this 293 * requires drivers to subclass the state structure. 294 * 295 * Such driver-private properties should really only be implemented for 296 * truly hardware/vendor specific state. Instead it is preferred to 297 * standardize atomic extension and decode the properties used to expose 298 * such an extension in the core. 299 * 300 * Do not call this function directly, use 301 * drm_atomic_plane_set_property() instead. 302 * 303 * This callback is optional if the driver does not support any 304 * driver-private atomic properties. 305 * 306 * NOTE: 307 * 308 * This function is called in the state assembly phase of atomic 309 * modesets, which can be aborted for any reason (including on 310 * userspace's request to just check whether a configuration would be 311 * possible). Drivers MUST NOT touch any persistent state (hardware or 312 * software) or data structures except the passed in @state parameter. 313 * 314 * Also since userspace controls in which order properties are set this 315 * function must not do any input validation (since the state update is 316 * incomplete and hence likely inconsistent). Instead any such input 317 * validation must be done in the various atomic_check callbacks. 318 * 319 * RETURNS: 320 * 321 * 0 if the property has been found, -EINVAL if the property isn't 322 * implemented by the driver (which shouldn't ever happen, the core only 323 * asks for properties attached to this plane). No other validation is 324 * allowed by the driver. The core already checks that the property 325 * value is within the range (integer, valid enum value, ...) the driver 326 * set when registering the property. 327 */ 328 int (*atomic_set_property)(struct drm_plane *plane, 329 struct drm_plane_state *state, 330 struct drm_property *property, 331 uint64_t val); 332 333 /** 334 * @atomic_get_property: 335 * 336 * Reads out the decoded driver-private property. This is used to 337 * implement the GETPLANE IOCTL. 338 * 339 * Do not call this function directly, use 340 * drm_atomic_plane_get_property() instead. 341 * 342 * This callback is optional if the driver does not support any 343 * driver-private atomic properties. 344 * 345 * RETURNS: 346 * 347 * 0 on success, -EINVAL if the property isn't implemented by the 348 * driver (which should never happen, the core only asks for 349 * properties attached to this plane). 350 */ 351 int (*atomic_get_property)(struct drm_plane *plane, 352 const struct drm_plane_state *state, 353 struct drm_property *property, 354 uint64_t *val); 355 /** 356 * @late_register: 357 * 358 * This optional hook can be used to register additional userspace 359 * interfaces attached to the plane like debugfs interfaces. 360 * It is called late in the driver load sequence from drm_dev_register(). 361 * Everything added from this callback should be unregistered in 362 * the early_unregister callback. 363 * 364 * Returns: 365 * 366 * 0 on success, or a negative error code on failure. 367 */ 368 int (*late_register)(struct drm_plane *plane); 369 370 /** 371 * @early_unregister: 372 * 373 * This optional hook should be used to unregister the additional 374 * userspace interfaces attached to the plane from 375 * @late_register. It is called from drm_dev_unregister(), 376 * early in the driver unload sequence to disable userspace access 377 * before data structures are torndown. 378 */ 379 void (*early_unregister)(struct drm_plane *plane); 380 381 /** 382 * @atomic_print_state: 383 * 384 * If driver subclasses &struct drm_plane_state, it should implement 385 * this optional hook for printing additional driver specific state. 386 * 387 * Do not call this directly, use drm_atomic_plane_print_state() 388 * instead. 389 */ 390 void (*atomic_print_state)(struct drm_printer *p, 391 const struct drm_plane_state *state); 392 }; 393 394 /** 395 * enum drm_plane_type - uapi plane type enumeration 396 * 397 * For historical reasons not all planes are made the same. This enumeration is 398 * used to tell the different types of planes apart to implement the different 399 * uapi semantics for them. For userspace which is universal plane aware and 400 * which is using that atomic IOCTL there's no difference between these planes 401 * (beyong what the driver and hardware can support of course). 402 * 403 * For compatibility with legacy userspace, only overlay planes are made 404 * available to userspace by default. Userspace clients may set the 405 * DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that they 406 * wish to receive a universal plane list containing all plane types. See also 407 * drm_for_each_legacy_plane(). 408 * 409 * WARNING: The values of this enum is UABI since they're exposed in the "type" 410 * property. 411 */ 412 enum drm_plane_type { 413 /** 414 * @DRM_PLANE_TYPE_OVERLAY: 415 * 416 * Overlay planes represent all non-primary, non-cursor planes. Some 417 * drivers refer to these types of planes as "sprites" internally. 418 */ 419 DRM_PLANE_TYPE_OVERLAY, 420 421 /** 422 * @DRM_PLANE_TYPE_PRIMARY: 423 * 424 * Primary planes represent a "main" plane for a CRTC. Primary planes 425 * are the planes operated upon by CRTC modesetting and flipping 426 * operations described in the &drm_crtc_funcs.page_flip and 427 * &drm_crtc_funcs.set_config hooks. 428 */ 429 DRM_PLANE_TYPE_PRIMARY, 430 431 /** 432 * @DRM_PLANE_TYPE_CURSOR: 433 * 434 * Cursor planes represent a "cursor" plane for a CRTC. Cursor planes 435 * are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and 436 * DRM_IOCTL_MODE_CURSOR2 IOCTLs. 437 */ 438 DRM_PLANE_TYPE_CURSOR, 439 }; 440 441 442 /** 443 * struct drm_plane - central DRM plane control structure 444 * @dev: DRM device this plane belongs to 445 * @head: for list management 446 * @name: human readable name, can be overwritten by the driver 447 * @base: base mode object 448 * @possible_crtcs: pipes this plane can be bound to 449 * @format_types: array of formats supported by this plane 450 * @format_count: number of formats supported 451 * @format_default: driver hasn't supplied supported formats for the plane 452 * @crtc: currently bound CRTC 453 * @fb: currently bound fb 454 * @old_fb: Temporary tracking of the old fb while a modeset is ongoing. Used by 455 * drm_mode_set_config_internal() to implement correct refcounting. 456 * @funcs: helper functions 457 * @properties: property tracking for this plane 458 * @type: type of plane (overlay, primary, cursor) 459 * @state: current atomic state for this plane 460 * @zpos_property: zpos property for this plane 461 * @rotation_property: rotation property for this plane 462 * @helper_private: mid-layer private data 463 */ 464 struct drm_plane { 465 struct drm_device *dev; 466 struct list_head head; 467 468 char *name; 469 470 /** 471 * @mutex: 472 * 473 * Protects modeset plane state, together with the &drm_crtc.mutex of 474 * CRTC this plane is linked to (when active, getting activated or 475 * getting disabled). 476 */ 477 struct drm_modeset_lock mutex; 478 479 struct drm_mode_object base; 480 481 uint32_t possible_crtcs; 482 uint32_t *format_types; 483 unsigned int format_count; 484 bool format_default; 485 486 struct drm_crtc *crtc; 487 struct drm_framebuffer *fb; 488 489 struct drm_framebuffer *old_fb; 490 491 const struct drm_plane_funcs *funcs; 492 493 struct drm_object_properties properties; 494 495 enum drm_plane_type type; 496 497 /** 498 * @index: Position inside the mode_config.list, can be used as an array 499 * index. It is invariant over the lifetime of the plane. 500 */ 501 unsigned index; 502 503 const struct drm_plane_helper_funcs *helper_private; 504 505 struct drm_plane_state *state; 506 507 struct drm_property *zpos_property; 508 struct drm_property *rotation_property; 509 }; 510 511 #define obj_to_plane(x) container_of(x, struct drm_plane, base) 512 513 extern __printf(8, 9) 514 int drm_universal_plane_init(struct drm_device *dev, 515 struct drm_plane *plane, 516 uint32_t possible_crtcs, 517 const struct drm_plane_funcs *funcs, 518 const uint32_t *formats, 519 unsigned int format_count, 520 enum drm_plane_type type, 521 const char *name, ...); 522 extern int drm_plane_init(struct drm_device *dev, 523 struct drm_plane *plane, 524 uint32_t possible_crtcs, 525 const struct drm_plane_funcs *funcs, 526 const uint32_t *formats, unsigned int format_count, 527 bool is_primary); 528 extern void drm_plane_cleanup(struct drm_plane *plane); 529 530 /** 531 * drm_plane_index - find the index of a registered plane 532 * @plane: plane to find index for 533 * 534 * Given a registered plane, return the index of that plane within a DRM 535 * device's list of planes. 536 */ 537 static inline unsigned int drm_plane_index(struct drm_plane *plane) 538 { 539 return plane->index; 540 } 541 extern struct drm_plane * drm_plane_from_index(struct drm_device *dev, int idx); 542 extern void drm_plane_force_disable(struct drm_plane *plane); 543 544 int drm_mode_plane_set_obj_prop(struct drm_plane *plane, 545 struct drm_property *property, 546 uint64_t value); 547 548 /** 549 * drm_plane_find - find a &drm_plane 550 * @dev: DRM device 551 * @id: plane id 552 * 553 * Returns the plane with @id, NULL if it doesn't exist. Simple wrapper around 554 * drm_mode_object_find(). 555 */ 556 static inline struct drm_plane *drm_plane_find(struct drm_device *dev, 557 uint32_t id) 558 { 559 struct drm_mode_object *mo; 560 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PLANE); 561 return mo ? obj_to_plane(mo) : NULL; 562 } 563 564 /** 565 * drm_for_each_plane_mask - iterate over planes specified by bitmask 566 * @plane: the loop cursor 567 * @dev: the DRM device 568 * @plane_mask: bitmask of plane indices 569 * 570 * Iterate over all planes specified by bitmask. 571 */ 572 #define drm_for_each_plane_mask(plane, dev, plane_mask) \ 573 list_for_each_entry((plane), &(dev)->mode_config.plane_list, head) \ 574 for_each_if ((plane_mask) & (1 << drm_plane_index(plane))) 575 576 /** 577 * drm_for_each_legacy_plane - iterate over all planes for legacy userspace 578 * @plane: the loop cursor 579 * @dev: the DRM device 580 * 581 * Iterate over all legacy planes of @dev, excluding primary and cursor planes. 582 * This is useful for implementing userspace apis when userspace is not 583 * universal plane aware. See also &enum drm_plane_type. 584 */ 585 #define drm_for_each_legacy_plane(plane, dev) \ 586 list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) \ 587 for_each_if (plane->type == DRM_PLANE_TYPE_OVERLAY) 588 589 /** 590 * drm_for_each_plane - iterate over all planes 591 * @plane: the loop cursor 592 * @dev: the DRM device 593 * 594 * Iterate over all planes of @dev, include primary and cursor planes. 595 */ 596 #define drm_for_each_plane(plane, dev) \ 597 list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) 598 599 600 #endif 601