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