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