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 #include <drm/drm_color_mgmt.h>
30 
31 struct drm_crtc;
32 struct drm_printer;
33 struct drm_modeset_acquire_ctx;
34 
35 /**
36  * struct drm_plane_state - mutable plane state
37  *
38  * Please not that the destination coordinates @crtc_x, @crtc_y, @crtc_h and
39  * @crtc_w and the source coordinates @src_x, @src_y, @src_h and @src_w are the
40  * raw coordinates provided by userspace. Drivers should use
41  * drm_atomic_helper_check_plane_state() and only use the derived rectangles in
42  * @src and @dst to program the hardware.
43  */
44 struct drm_plane_state {
45 	/** @plane: backpointer to the plane */
46 	struct drm_plane *plane;
47 
48 	/**
49 	 * @crtc:
50 	 *
51 	 * Currently bound CRTC, NULL if disabled. Do not this write directly,
52 	 * use drm_atomic_set_crtc_for_plane()
53 	 */
54 	struct drm_crtc *crtc;
55 
56 	/**
57 	 * @fb:
58 	 *
59 	 * Currently bound framebuffer. Do not write this directly, use
60 	 * drm_atomic_set_fb_for_plane()
61 	 */
62 	struct drm_framebuffer *fb;
63 
64 	/**
65 	 * @fence:
66 	 *
67 	 * Optional fence to wait for before scanning out @fb. The core atomic
68 	 * code will set this when userspace is using explicit fencing. Do not
69 	 * write this directly for a driver's implicit fence, use
70 	 * drm_atomic_set_fence_for_plane() to ensure that an explicit fence is
71 	 * preserved.
72 	 *
73 	 * Drivers should store any implicit fence in this from their
74 	 * &drm_plane_helper_funcs.prepare_fb callback. See drm_gem_fb_prepare_fb()
75 	 * and drm_gem_fb_simple_display_pipe_prepare_fb() for suitable helpers.
76 	 */
77 	struct dma_fence *fence;
78 
79 	/**
80 	 * @crtc_x:
81 	 *
82 	 * Left position of visible portion of plane on crtc, signed dest
83 	 * location allows it to be partially off screen.
84 	 */
85 
86 	int32_t crtc_x;
87 	/**
88 	 * @crtc_y:
89 	 *
90 	 * Upper position of visible portion of plane on crtc, signed dest
91 	 * location allows it to be partially off screen.
92 	 */
93 	int32_t crtc_y;
94 
95 	/** @crtc_w: width of visible portion of plane on crtc */
96 	/** @crtc_h: height of visible portion of plane on crtc */
97 	uint32_t crtc_w, crtc_h;
98 
99 	/**
100 	 * @src_x: left position of visible portion of plane within plane (in
101 	 * 16.16 fixed point).
102 	 */
103 	uint32_t src_x;
104 	/**
105 	 * @src_y: upper position of visible portion of plane within plane (in
106 	 * 16.16 fixed point).
107 	 */
108 	uint32_t src_y;
109 	/** @src_w: width of visible portion of plane (in 16.16) */
110 	/** @src_h: height of visible portion of plane (in 16.16) */
111 	uint32_t src_h, src_w;
112 
113 	/**
114 	 * @alpha:
115 	 * Opacity of the plane with 0 as completely transparent and 0xffff as
116 	 * completely opaque. See drm_plane_create_alpha_property() for more
117 	 * details.
118 	 */
119 	u16 alpha;
120 
121 	/**
122 	 * @rotation:
123 	 * Rotation of the plane. See drm_plane_create_rotation_property() for
124 	 * more details.
125 	 */
126 	unsigned int rotation;
127 
128 	/**
129 	 * @zpos:
130 	 * Priority of the given plane on crtc (optional).
131 	 *
132 	 * Note that multiple active planes on the same crtc can have an
133 	 * identical zpos value. The rule to solving the conflict is to compare
134 	 * the plane object IDs; the plane with a higher ID must be stacked on
135 	 * top of a plane with a lower ID.
136 	 *
137 	 * See drm_plane_create_zpos_property() and
138 	 * drm_plane_create_zpos_immutable_property() for more details.
139 	 */
140 	unsigned int zpos;
141 
142 	/**
143 	 * @normalized_zpos:
144 	 * Normalized value of zpos: unique, range from 0 to N-1 where N is the
145 	 * number of active planes for given crtc. Note that the driver must set
146 	 * &drm_mode_config.normalize_zpos or call drm_atomic_normalize_zpos() to
147 	 * update this before it can be trusted.
148 	 */
149 	unsigned int normalized_zpos;
150 
151 	/**
152 	 * @color_encoding:
153 	 *
154 	 * Color encoding for non RGB formats
155 	 */
156 	enum drm_color_encoding color_encoding;
157 
158 	/**
159 	 * @color_range:
160 	 *
161 	 * Color range for non RGB formats
162 	 */
163 	enum drm_color_range color_range;
164 
165 	/** @src: clipped source coordinates of the plane (in 16.16) */
166 	/** @dst: clipped destination coordinates of the plane */
167 	struct drm_rect src, dst;
168 
169 	/**
170 	 * @visible:
171 	 *
172 	 * Visibility of the plane. This can be false even if fb!=NULL and
173 	 * crtc!=NULL, due to clipping.
174 	 */
175 	bool visible;
176 
177 	/**
178 	 * @commit: Tracks the pending commit to prevent use-after-free conditions,
179 	 * and for async plane updates.
180 	 *
181 	 * May be NULL.
182 	 */
183 	struct drm_crtc_commit *commit;
184 
185 	/** @state: backpointer to global drm_atomic_state */
186 	struct drm_atomic_state *state;
187 };
188 
189 static inline struct drm_rect
drm_plane_state_src(const struct drm_plane_state * state)190 drm_plane_state_src(const struct drm_plane_state *state)
191 {
192 	struct drm_rect src = {
193 		.x1 = state->src_x,
194 		.y1 = state->src_y,
195 		.x2 = state->src_x + state->src_w,
196 		.y2 = state->src_y + state->src_h,
197 	};
198 	return src;
199 }
200 
201 static inline struct drm_rect
drm_plane_state_dest(const struct drm_plane_state * state)202 drm_plane_state_dest(const struct drm_plane_state *state)
203 {
204 	struct drm_rect dest = {
205 		.x1 = state->crtc_x,
206 		.y1 = state->crtc_y,
207 		.x2 = state->crtc_x + state->crtc_w,
208 		.y2 = state->crtc_y + state->crtc_h,
209 	};
210 	return dest;
211 }
212 
213 /**
214  * struct drm_plane_funcs - driver plane control functions
215  */
216 struct drm_plane_funcs {
217 	/**
218 	 * @update_plane:
219 	 *
220 	 * This is the legacy entry point to enable and configure the plane for
221 	 * the given CRTC and framebuffer. It is never called to disable the
222 	 * plane, i.e. the passed-in crtc and fb paramters are never NULL.
223 	 *
224 	 * The source rectangle in frame buffer memory coordinates is given by
225 	 * the src_x, src_y, src_w and src_h parameters (as 16.16 fixed point
226 	 * values). Devices that don't support subpixel plane coordinates can
227 	 * ignore the fractional part.
228 	 *
229 	 * The destination rectangle in CRTC coordinates is given by the
230 	 * crtc_x, crtc_y, crtc_w and crtc_h parameters (as integer values).
231 	 * Devices scale the source rectangle to the destination rectangle. If
232 	 * scaling is not supported, and the source rectangle size doesn't match
233 	 * the destination rectangle size, the driver must return a
234 	 * -<errorname>EINVAL</errorname> error.
235 	 *
236 	 * Drivers implementing atomic modeset should use
237 	 * drm_atomic_helper_update_plane() to implement this hook.
238 	 *
239 	 * RETURNS:
240 	 *
241 	 * 0 on success or a negative error code on failure.
242 	 */
243 	int (*update_plane)(struct drm_plane *plane,
244 			    struct drm_crtc *crtc, struct drm_framebuffer *fb,
245 			    int crtc_x, int crtc_y,
246 			    unsigned int crtc_w, unsigned int crtc_h,
247 			    uint32_t src_x, uint32_t src_y,
248 			    uint32_t src_w, uint32_t src_h,
249 			    struct drm_modeset_acquire_ctx *ctx);
250 
251 	/**
252 	 * @disable_plane:
253 	 *
254 	 * This is the legacy entry point to disable the plane. The DRM core
255 	 * calls this method in response to a DRM_IOCTL_MODE_SETPLANE IOCTL call
256 	 * with the frame buffer ID set to 0.  Disabled planes must not be
257 	 * processed by the CRTC.
258 	 *
259 	 * Drivers implementing atomic modeset should use
260 	 * drm_atomic_helper_disable_plane() to implement this hook.
261 	 *
262 	 * RETURNS:
263 	 *
264 	 * 0 on success or a negative error code on failure.
265 	 */
266 	int (*disable_plane)(struct drm_plane *plane,
267 			     struct drm_modeset_acquire_ctx *ctx);
268 
269 	/**
270 	 * @destroy:
271 	 *
272 	 * Clean up plane resources. This is only called at driver unload time
273 	 * through drm_mode_config_cleanup() since a plane cannot be hotplugged
274 	 * in DRM.
275 	 */
276 	void (*destroy)(struct drm_plane *plane);
277 
278 	/**
279 	 * @reset:
280 	 *
281 	 * Reset plane hardware and software state to off. This function isn't
282 	 * called by the core directly, only through drm_mode_config_reset().
283 	 * It's not a helper hook only for historical reasons.
284 	 *
285 	 * Atomic drivers can use drm_atomic_helper_plane_reset() to reset
286 	 * atomic state using this hook.
287 	 */
288 	void (*reset)(struct drm_plane *plane);
289 
290 	/**
291 	 * @set_property:
292 	 *
293 	 * This is the legacy entry point to update a property attached to the
294 	 * plane.
295 	 *
296 	 * This callback is optional if the driver does not support any legacy
297 	 * driver-private properties. For atomic drivers it is not used because
298 	 * property handling is done entirely in the DRM core.
299 	 *
300 	 * RETURNS:
301 	 *
302 	 * 0 on success or a negative error code on failure.
303 	 */
304 	int (*set_property)(struct drm_plane *plane,
305 			    struct drm_property *property, uint64_t val);
306 
307 	/**
308 	 * @atomic_duplicate_state:
309 	 *
310 	 * Duplicate the current atomic state for this plane and return it.
311 	 * The core and helpers guarantee that any atomic state duplicated with
312 	 * this hook and still owned by the caller (i.e. not transferred to the
313 	 * driver by calling &drm_mode_config_funcs.atomic_commit) will be
314 	 * cleaned up by calling the @atomic_destroy_state hook in this
315 	 * structure.
316 	 *
317 	 * This callback is mandatory for atomic drivers.
318 	 *
319 	 * Atomic drivers which don't subclass &struct drm_plane_state should use
320 	 * drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the
321 	 * state structure to extend it with driver-private state should use
322 	 * __drm_atomic_helper_plane_duplicate_state() to make sure shared state is
323 	 * duplicated in a consistent fashion across drivers.
324 	 *
325 	 * It is an error to call this hook before &drm_plane.state has been
326 	 * initialized correctly.
327 	 *
328 	 * NOTE:
329 	 *
330 	 * If the duplicate state references refcounted resources this hook must
331 	 * acquire a reference for each of them. The driver must release these
332 	 * references again in @atomic_destroy_state.
333 	 *
334 	 * RETURNS:
335 	 *
336 	 * Duplicated atomic state or NULL when the allocation failed.
337 	 */
338 	struct drm_plane_state *(*atomic_duplicate_state)(struct drm_plane *plane);
339 
340 	/**
341 	 * @atomic_destroy_state:
342 	 *
343 	 * Destroy a state duplicated with @atomic_duplicate_state and release
344 	 * or unreference all resources it references
345 	 *
346 	 * This callback is mandatory for atomic drivers.
347 	 */
348 	void (*atomic_destroy_state)(struct drm_plane *plane,
349 				     struct drm_plane_state *state);
350 
351 	/**
352 	 * @atomic_set_property:
353 	 *
354 	 * Decode a driver-private property value and store the decoded value
355 	 * into the passed-in state structure. Since the atomic core decodes all
356 	 * standardized properties (even for extensions beyond the core set of
357 	 * properties which might not be implemented by all drivers) this
358 	 * requires drivers to subclass the state structure.
359 	 *
360 	 * Such driver-private properties should really only be implemented for
361 	 * truly hardware/vendor specific state. Instead it is preferred to
362 	 * standardize atomic extension and decode the properties used to expose
363 	 * such an extension in the core.
364 	 *
365 	 * Do not call this function directly, use
366 	 * drm_atomic_plane_set_property() instead.
367 	 *
368 	 * This callback is optional if the driver does not support any
369 	 * driver-private atomic properties.
370 	 *
371 	 * NOTE:
372 	 *
373 	 * This function is called in the state assembly phase of atomic
374 	 * modesets, which can be aborted for any reason (including on
375 	 * userspace's request to just check whether a configuration would be
376 	 * possible). Drivers MUST NOT touch any persistent state (hardware or
377 	 * software) or data structures except the passed in @state parameter.
378 	 *
379 	 * Also since userspace controls in which order properties are set this
380 	 * function must not do any input validation (since the state update is
381 	 * incomplete and hence likely inconsistent). Instead any such input
382 	 * validation must be done in the various atomic_check callbacks.
383 	 *
384 	 * RETURNS:
385 	 *
386 	 * 0 if the property has been found, -EINVAL if the property isn't
387 	 * implemented by the driver (which shouldn't ever happen, the core only
388 	 * asks for properties attached to this plane). No other validation is
389 	 * allowed by the driver. The core already checks that the property
390 	 * value is within the range (integer, valid enum value, ...) the driver
391 	 * set when registering the property.
392 	 */
393 	int (*atomic_set_property)(struct drm_plane *plane,
394 				   struct drm_plane_state *state,
395 				   struct drm_property *property,
396 				   uint64_t val);
397 
398 	/**
399 	 * @atomic_get_property:
400 	 *
401 	 * Reads out the decoded driver-private property. This is used to
402 	 * implement the GETPLANE IOCTL.
403 	 *
404 	 * Do not call this function directly, use
405 	 * drm_atomic_plane_get_property() instead.
406 	 *
407 	 * This callback is optional if the driver does not support any
408 	 * driver-private atomic properties.
409 	 *
410 	 * RETURNS:
411 	 *
412 	 * 0 on success, -EINVAL if the property isn't implemented by the
413 	 * driver (which should never happen, the core only asks for
414 	 * properties attached to this plane).
415 	 */
416 	int (*atomic_get_property)(struct drm_plane *plane,
417 				   const struct drm_plane_state *state,
418 				   struct drm_property *property,
419 				   uint64_t *val);
420 	/**
421 	 * @late_register:
422 	 *
423 	 * This optional hook can be used to register additional userspace
424 	 * interfaces attached to the plane like debugfs interfaces.
425 	 * It is called late in the driver load sequence from drm_dev_register().
426 	 * Everything added from this callback should be unregistered in
427 	 * the early_unregister callback.
428 	 *
429 	 * Returns:
430 	 *
431 	 * 0 on success, or a negative error code on failure.
432 	 */
433 	int (*late_register)(struct drm_plane *plane);
434 
435 	/**
436 	 * @early_unregister:
437 	 *
438 	 * This optional hook should be used to unregister the additional
439 	 * userspace interfaces attached to the plane from
440 	 * @late_register. It is called from drm_dev_unregister(),
441 	 * early in the driver unload sequence to disable userspace access
442 	 * before data structures are torndown.
443 	 */
444 	void (*early_unregister)(struct drm_plane *plane);
445 
446 	/**
447 	 * @atomic_print_state:
448 	 *
449 	 * If driver subclasses &struct drm_plane_state, it should implement
450 	 * this optional hook for printing additional driver specific state.
451 	 *
452 	 * Do not call this directly, use drm_atomic_plane_print_state()
453 	 * instead.
454 	 */
455 	void (*atomic_print_state)(struct drm_printer *p,
456 				   const struct drm_plane_state *state);
457 
458 	/**
459 	 * @format_mod_supported:
460 	 *
461 	 * This optional hook is used for the DRM to determine if the given
462 	 * format/modifier combination is valid for the plane. This allows the
463 	 * DRM to generate the correct format bitmask (which formats apply to
464 	 * which modifier), and to valdiate modifiers at atomic_check time.
465 	 *
466 	 * If not present, then any modifier in the plane's modifier
467 	 * list is allowed with any of the plane's formats.
468 	 *
469 	 * Returns:
470 	 *
471 	 * True if the given modifier is valid for that format on the plane.
472 	 * False otherwise.
473 	 */
474 	bool (*format_mod_supported)(struct drm_plane *plane, uint32_t format,
475 				     uint64_t modifier);
476 };
477 
478 /**
479  * enum drm_plane_type - uapi plane type enumeration
480  *
481  * For historical reasons not all planes are made the same. This enumeration is
482  * used to tell the different types of planes apart to implement the different
483  * uapi semantics for them. For userspace which is universal plane aware and
484  * which is using that atomic IOCTL there's no difference between these planes
485  * (beyong what the driver and hardware can support of course).
486  *
487  * For compatibility with legacy userspace, only overlay planes are made
488  * available to userspace by default. Userspace clients may set the
489  * DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that they
490  * wish to receive a universal plane list containing all plane types. See also
491  * drm_for_each_legacy_plane().
492  *
493  * WARNING: The values of this enum is UABI since they're exposed in the "type"
494  * property.
495  */
496 enum drm_plane_type {
497 	/**
498 	 * @DRM_PLANE_TYPE_OVERLAY:
499 	 *
500 	 * Overlay planes represent all non-primary, non-cursor planes. Some
501 	 * drivers refer to these types of planes as "sprites" internally.
502 	 */
503 	DRM_PLANE_TYPE_OVERLAY,
504 
505 	/**
506 	 * @DRM_PLANE_TYPE_PRIMARY:
507 	 *
508 	 * Primary planes represent a "main" plane for a CRTC.  Primary planes
509 	 * are the planes operated upon by CRTC modesetting and flipping
510 	 * operations described in the &drm_crtc_funcs.page_flip and
511 	 * &drm_crtc_funcs.set_config hooks.
512 	 */
513 	DRM_PLANE_TYPE_PRIMARY,
514 
515 	/**
516 	 * @DRM_PLANE_TYPE_CURSOR:
517 	 *
518 	 * Cursor planes represent a "cursor" plane for a CRTC.  Cursor planes
519 	 * are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and
520 	 * DRM_IOCTL_MODE_CURSOR2 IOCTLs.
521 	 */
522 	DRM_PLANE_TYPE_CURSOR,
523 };
524 
525 
526 /**
527  * struct drm_plane - central DRM plane control structure
528  *
529  * Planes represent the scanout hardware of a display block. They receive their
530  * input data from a &drm_framebuffer and feed it to a &drm_crtc. Planes control
531  * the color conversion, see `Plane Composition Properties`_ for more details,
532  * and are also involved in the color conversion of input pixels, see `Color
533  * Management Properties`_ for details on that.
534  */
535 struct drm_plane {
536 	/** @dev: DRM device this plane belongs to */
537 	struct drm_device *dev;
538 
539 	/**
540 	 * @head:
541 	 *
542 	 * List of all planes on @dev, linked from &drm_mode_config.plane_list.
543 	 * Invariant over the lifetime of @dev and therefore does not need
544 	 * locking.
545 	 */
546 	struct list_head head;
547 
548 	/** @name: human readable name, can be overwritten by the driver */
549 	char *name;
550 
551 	/**
552 	 * @mutex:
553 	 *
554 	 * Protects modeset plane state, together with the &drm_crtc.mutex of
555 	 * CRTC this plane is linked to (when active, getting activated or
556 	 * getting disabled).
557 	 *
558 	 * For atomic drivers specifically this protects @state.
559 	 */
560 	struct drm_modeset_lock mutex;
561 
562 	/** @base: base mode object */
563 	struct drm_mode_object base;
564 
565 	/**
566 	 * @possible_crtcs: pipes this plane can be bound to constructed from
567 	 * drm_crtc_mask()
568 	 */
569 	uint32_t possible_crtcs;
570 	/** @format_types: array of formats supported by this plane */
571 	uint32_t *format_types;
572 	/** @format_count: Size of the array pointed at by @format_types. */
573 	unsigned int format_count;
574 	/**
575 	 * @format_default: driver hasn't supplied supported formats for the
576 	 * plane. Used by the drm_plane_init compatibility wrapper only.
577 	 */
578 	bool format_default;
579 
580 	/** @modifiers: array of modifiers supported by this plane */
581 	uint64_t *modifiers;
582 	/** @modifier_count: Size of the array pointed at by @modifier_count. */
583 	unsigned int modifier_count;
584 
585 	/**
586 	 * @crtc:
587 	 *
588 	 * Currently bound CRTC, only meaningful for non-atomic drivers. For
589 	 * atomic drivers this is forced to be NULL, atomic drivers should
590 	 * instead check &drm_plane_state.crtc.
591 	 */
592 	struct drm_crtc *crtc;
593 
594 	/**
595 	 * @fb:
596 	 *
597 	 * Currently bound framebuffer, only meaningful for non-atomic drivers.
598 	 * For atomic drivers this is forced to be NULL, atomic drivers should
599 	 * instead check &drm_plane_state.fb.
600 	 */
601 	struct drm_framebuffer *fb;
602 
603 	/**
604 	 * @old_fb:
605 	 *
606 	 * Temporary tracking of the old fb while a modeset is ongoing. Only
607 	 * used by non-atomic drivers, forced to be NULL for atomic drivers.
608 	 */
609 	struct drm_framebuffer *old_fb;
610 
611 	/** @funcs: plane control functions */
612 	const struct drm_plane_funcs *funcs;
613 
614 	/** @properties: property tracking for this plane */
615 	struct drm_object_properties properties;
616 
617 	/** @type: Type of plane, see &enum drm_plane_type for details. */
618 	enum drm_plane_type type;
619 
620 	/**
621 	 * @index: Position inside the mode_config.list, can be used as an array
622 	 * index. It is invariant over the lifetime of the plane.
623 	 */
624 	unsigned index;
625 
626 	/** @helper_private: mid-layer private data */
627 	const struct drm_plane_helper_funcs *helper_private;
628 
629 	/**
630 	 * @state:
631 	 *
632 	 * Current atomic state for this plane.
633 	 *
634 	 * This is protected by @mutex. Note that nonblocking atomic commits
635 	 * access the current plane state without taking locks. Either by going
636 	 * through the &struct drm_atomic_state pointers, see
637 	 * for_each_oldnew_plane_in_state(), for_each_old_plane_in_state() and
638 	 * for_each_new_plane_in_state(). Or through careful ordering of atomic
639 	 * commit operations as implemented in the atomic helpers, see
640 	 * &struct drm_crtc_commit.
641 	 */
642 	struct drm_plane_state *state;
643 
644 	/**
645 	 * @alpha_property:
646 	 * Optional alpha property for this plane. See
647 	 * drm_plane_create_alpha_property().
648 	 */
649 	struct drm_property *alpha_property;
650 	/**
651 	 * @zpos_property:
652 	 * Optional zpos property for this plane. See
653 	 * drm_plane_create_zpos_property().
654 	 */
655 	struct drm_property *zpos_property;
656 	/**
657 	 * @rotation_property:
658 	 * Optional rotation property for this plane. See
659 	 * drm_plane_create_rotation_property().
660 	 */
661 	struct drm_property *rotation_property;
662 
663 	/**
664 	 * @color_encoding_property:
665 	 *
666 	 * Optional "COLOR_ENCODING" enum property for specifying
667 	 * color encoding for non RGB formats.
668 	 * See drm_plane_create_color_properties().
669 	 */
670 	struct drm_property *color_encoding_property;
671 	/**
672 	 * @color_range_property:
673 	 *
674 	 * Optional "COLOR_RANGE" enum property for specifying
675 	 * color range for non RGB formats.
676 	 * See drm_plane_create_color_properties().
677 	 */
678 	struct drm_property *color_range_property;
679 };
680 
681 #define obj_to_plane(x) container_of(x, struct drm_plane, base)
682 
683 __printf(9, 10)
684 int drm_universal_plane_init(struct drm_device *dev,
685 			     struct drm_plane *plane,
686 			     uint32_t possible_crtcs,
687 			     const struct drm_plane_funcs *funcs,
688 			     const uint32_t *formats,
689 			     unsigned int format_count,
690 			     const uint64_t *format_modifiers,
691 			     enum drm_plane_type type,
692 			     const char *name, ...);
693 int drm_plane_init(struct drm_device *dev,
694 		   struct drm_plane *plane,
695 		   uint32_t possible_crtcs,
696 		   const struct drm_plane_funcs *funcs,
697 		   const uint32_t *formats, unsigned int format_count,
698 		   bool is_primary);
699 void drm_plane_cleanup(struct drm_plane *plane);
700 
701 /**
702  * drm_plane_index - find the index of a registered plane
703  * @plane: plane to find index for
704  *
705  * Given a registered plane, return the index of that plane within a DRM
706  * device's list of planes.
707  */
drm_plane_index(const struct drm_plane * plane)708 static inline unsigned int drm_plane_index(const struct drm_plane *plane)
709 {
710 	return plane->index;
711 }
712 
713 /**
714  * drm_plane_mask - find the mask of a registered plane
715  * @plane: plane to find mask for
716  */
drm_plane_mask(const struct drm_plane * plane)717 static inline u32 drm_plane_mask(const struct drm_plane *plane)
718 {
719 	return 1 << drm_plane_index(plane);
720 }
721 
722 struct drm_plane * drm_plane_from_index(struct drm_device *dev, int idx);
723 void drm_plane_force_disable(struct drm_plane *plane);
724 
725 int drm_mode_plane_set_obj_prop(struct drm_plane *plane,
726 				       struct drm_property *property,
727 				       uint64_t value);
728 
729 /**
730  * drm_plane_find - find a &drm_plane
731  * @dev: DRM device
732  * @file_priv: drm file to check for lease against.
733  * @id: plane id
734  *
735  * Returns the plane with @id, NULL if it doesn't exist. Simple wrapper around
736  * drm_mode_object_find().
737  */
drm_plane_find(struct drm_device * dev,struct drm_file * file_priv,uint32_t id)738 static inline struct drm_plane *drm_plane_find(struct drm_device *dev,
739 		struct drm_file *file_priv,
740 		uint32_t id)
741 {
742 	struct drm_mode_object *mo;
743 	mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PLANE);
744 	return mo ? obj_to_plane(mo) : NULL;
745 }
746 
747 /**
748  * drm_for_each_plane_mask - iterate over planes specified by bitmask
749  * @plane: the loop cursor
750  * @dev: the DRM device
751  * @plane_mask: bitmask of plane indices
752  *
753  * Iterate over all planes specified by bitmask.
754  */
755 #define drm_for_each_plane_mask(plane, dev, plane_mask) \
756 	list_for_each_entry((plane), &(dev)->mode_config.plane_list, head) \
757 		for_each_if ((plane_mask) & drm_plane_mask(plane))
758 
759 /**
760  * drm_for_each_legacy_plane - iterate over all planes for legacy userspace
761  * @plane: the loop cursor
762  * @dev: the DRM device
763  *
764  * Iterate over all legacy planes of @dev, excluding primary and cursor planes.
765  * This is useful for implementing userspace apis when userspace is not
766  * universal plane aware. See also &enum drm_plane_type.
767  */
768 #define drm_for_each_legacy_plane(plane, dev) \
769 	list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) \
770 		for_each_if (plane->type == DRM_PLANE_TYPE_OVERLAY)
771 
772 /**
773  * drm_for_each_plane - iterate over all planes
774  * @plane: the loop cursor
775  * @dev: the DRM device
776  *
777  * Iterate over all planes of @dev, include primary and cursor planes.
778  */
779 #define drm_for_each_plane(plane, dev) \
780 	list_for_each_entry(plane, &(dev)->mode_config.plane_list, head)
781 
782 
783 #endif
784