1 /*
2  * Copyright (C) 2014 Intel Corporation
3  *
4  * DRM universal plane helper functions
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the "Software"),
8  * to deal in the Software without restriction, including without limitation
9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  * and/or sell copies of the Software, and to permit persons to whom the
11  * Software is furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice (including the next
14  * paragraph) shall be included in all copies or substantial portions of the
15  * Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
20  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23  * SOFTWARE.
24  */
25 
26 #include <linux/list.h>
27 #include <drm/drmP.h>
28 #include <drm/drm_plane_helper.h>
29 #include <drm/drm_rect.h>
30 #include <drm/drm_atomic.h>
31 #include <drm/drm_crtc_helper.h>
32 #include <drm/drm_encoder.h>
33 #include <drm/drm_atomic_helper.h>
34 
35 #define SUBPIXEL_MASK 0xffff
36 
37 /**
38  * DOC: overview
39  *
40  * This helper library has two parts. The first part has support to implement
41  * primary plane support on top of the normal CRTC configuration interface.
42  * Since the legacy &drm_mode_config_funcs.set_config interface ties the primary
43  * plane together with the CRTC state this does not allow userspace to disable
44  * the primary plane itself.  To avoid too much duplicated code use
45  * drm_plane_helper_check_update() which can be used to enforce the same
46  * restrictions as primary planes had thus. The default primary plane only
47  * expose XRBG8888 and ARGB8888 as valid pixel formats for the attached
48  * framebuffer.
49  *
50  * Drivers are highly recommended to implement proper support for primary
51  * planes, and newly merged drivers must not rely upon these transitional
52  * helpers.
53  *
54  * The second part also implements transitional helpers which allow drivers to
55  * gradually switch to the atomic helper infrastructure for plane updates. Once
56  * that switch is complete drivers shouldn't use these any longer, instead using
57  * the proper legacy implementations for update and disable plane hooks provided
58  * by the atomic helpers.
59  *
60  * Again drivers are strongly urged to switch to the new interfaces.
61  *
62  * The plane helpers share the function table structures with other helpers,
63  * specifically also the atomic helpers. See &struct drm_plane_helper_funcs for
64  * the details.
65  */
66 
67 /*
68  * Returns the connectors currently associated with a CRTC.  This function
69  * should be called twice:  once with a NULL connector list to retrieve
70  * the list size, and once with the properly allocated list to be filled in.
71  */
72 static int get_connectors_for_crtc(struct drm_crtc *crtc,
73 				   struct drm_connector **connector_list,
74 				   int num_connectors)
75 {
76 	struct drm_device *dev = crtc->dev;
77 	struct drm_connector *connector;
78 	struct drm_connector_list_iter conn_iter;
79 	int count = 0;
80 
81 	/*
82 	 * Note: Once we change the plane hooks to more fine-grained locking we
83 	 * need to grab the connection_mutex here to be able to make these
84 	 * checks.
85 	 */
86 	WARN_ON(!drm_modeset_is_locked(&dev->mode_config.connection_mutex));
87 
88 	drm_connector_list_iter_begin(dev, &conn_iter);
89 	drm_for_each_connector_iter(connector, &conn_iter) {
90 		if (connector->encoder && connector->encoder->crtc == crtc) {
91 			if (connector_list != NULL && count < num_connectors)
92 				*(connector_list++) = connector;
93 
94 			count++;
95 		}
96 	}
97 	drm_connector_list_iter_end(&conn_iter);
98 
99 	return count;
100 }
101 
102 /**
103  * drm_plane_helper_check_state() - Check plane state for validity
104  * @state: plane state to check
105  * @clip: integer clipping coordinates
106  * @min_scale: minimum @src:@dest scaling factor in 16.16 fixed point
107  * @max_scale: maximum @src:@dest scaling factor in 16.16 fixed point
108  * @can_position: is it legal to position the plane such that it
109  *                doesn't cover the entire crtc?  This will generally
110  *                only be false for primary planes.
111  * @can_update_disabled: can the plane be updated while the crtc
112  *                       is disabled?
113  *
114  * Checks that a desired plane update is valid, and updates various
115  * bits of derived state (clipped coordinates etc.). Drivers that provide
116  * their own plane handling rather than helper-provided implementations may
117  * still wish to call this function to avoid duplication of error checking
118  * code.
119  *
120  * RETURNS:
121  * Zero if update appears valid, error code on failure
122  */
123 int drm_plane_helper_check_state(struct drm_plane_state *state,
124 				 const struct drm_rect *clip,
125 				 int min_scale,
126 				 int max_scale,
127 				 bool can_position,
128 				 bool can_update_disabled)
129 {
130 	struct drm_crtc *crtc = state->crtc;
131 	struct drm_framebuffer *fb = state->fb;
132 	struct drm_rect *src = &state->src;
133 	struct drm_rect *dst = &state->dst;
134 	unsigned int rotation = state->rotation;
135 	int hscale, vscale;
136 
137 	*src = drm_plane_state_src(state);
138 	*dst = drm_plane_state_dest(state);
139 
140 	if (!fb) {
141 		state->visible = false;
142 		return 0;
143 	}
144 
145 	/* crtc should only be NULL when disabling (i.e., !fb) */
146 	if (WARN_ON(!crtc)) {
147 		state->visible = false;
148 		return 0;
149 	}
150 
151 	if (!crtc->enabled && !can_update_disabled) {
152 		DRM_DEBUG_KMS("Cannot update plane of a disabled CRTC.\n");
153 		return -EINVAL;
154 	}
155 
156 	drm_rect_rotate(src, fb->width << 16, fb->height << 16, rotation);
157 
158 	/* Check scaling */
159 	hscale = drm_rect_calc_hscale(src, dst, min_scale, max_scale);
160 	vscale = drm_rect_calc_vscale(src, dst, min_scale, max_scale);
161 	if (hscale < 0 || vscale < 0) {
162 		DRM_DEBUG_KMS("Invalid scaling of plane\n");
163 		drm_rect_debug_print("src: ", &state->src, true);
164 		drm_rect_debug_print("dst: ", &state->dst, false);
165 		return -ERANGE;
166 	}
167 
168 	state->visible = drm_rect_clip_scaled(src, dst, clip, hscale, vscale);
169 
170 	drm_rect_rotate_inv(src, fb->width << 16, fb->height << 16, rotation);
171 
172 	if (!state->visible)
173 		/*
174 		 * Plane isn't visible; some drivers can handle this
175 		 * so we just return success here.  Drivers that can't
176 		 * (including those that use the primary plane helper's
177 		 * update function) will return an error from their
178 		 * update_plane handler.
179 		 */
180 		return 0;
181 
182 	if (!can_position && !drm_rect_equals(dst, clip)) {
183 		DRM_DEBUG_KMS("Plane must cover entire CRTC\n");
184 		drm_rect_debug_print("dst: ", dst, false);
185 		drm_rect_debug_print("clip: ", clip, false);
186 		return -EINVAL;
187 	}
188 
189 	return 0;
190 }
191 EXPORT_SYMBOL(drm_plane_helper_check_state);
192 
193 /**
194  * drm_plane_helper_check_update() - Check plane update for validity
195  * @plane: plane object to update
196  * @crtc: owning CRTC of owning plane
197  * @fb: framebuffer to flip onto plane
198  * @src: source coordinates in 16.16 fixed point
199  * @dst: integer destination coordinates
200  * @clip: integer clipping coordinates
201  * @rotation: plane rotation
202  * @min_scale: minimum @src:@dest scaling factor in 16.16 fixed point
203  * @max_scale: maximum @src:@dest scaling factor in 16.16 fixed point
204  * @can_position: is it legal to position the plane such that it
205  *                doesn't cover the entire crtc?  This will generally
206  *                only be false for primary planes.
207  * @can_update_disabled: can the plane be updated while the crtc
208  *                       is disabled?
209  * @visible: output parameter indicating whether plane is still visible after
210  *           clipping
211  *
212  * Checks that a desired plane update is valid.  Drivers that provide
213  * their own plane handling rather than helper-provided implementations may
214  * still wish to call this function to avoid duplication of error checking
215  * code.
216  *
217  * RETURNS:
218  * Zero if update appears valid, error code on failure
219  */
220 int drm_plane_helper_check_update(struct drm_plane *plane,
221 				  struct drm_crtc *crtc,
222 				  struct drm_framebuffer *fb,
223 				  struct drm_rect *src,
224 				  struct drm_rect *dst,
225 				  const struct drm_rect *clip,
226 				  unsigned int rotation,
227 				  int min_scale,
228 				  int max_scale,
229 				  bool can_position,
230 				  bool can_update_disabled,
231 				  bool *visible)
232 {
233 	struct drm_plane_state state = {
234 		.plane = plane,
235 		.crtc = crtc,
236 		.fb = fb,
237 		.src_x = src->x1,
238 		.src_y = src->y1,
239 		.src_w = drm_rect_width(src),
240 		.src_h = drm_rect_height(src),
241 		.crtc_x = dst->x1,
242 		.crtc_y = dst->y1,
243 		.crtc_w = drm_rect_width(dst),
244 		.crtc_h = drm_rect_height(dst),
245 		.rotation = rotation,
246 		.visible = *visible,
247 	};
248 	int ret;
249 
250 	ret = drm_plane_helper_check_state(&state, clip,
251 					   min_scale, max_scale,
252 					   can_position,
253 					   can_update_disabled);
254 	if (ret)
255 		return ret;
256 
257 	*src = state.src;
258 	*dst = state.dst;
259 	*visible = state.visible;
260 
261 	return 0;
262 }
263 EXPORT_SYMBOL(drm_plane_helper_check_update);
264 
265 /**
266  * drm_primary_helper_update() - Helper for primary plane update
267  * @plane: plane object to update
268  * @crtc: owning CRTC of owning plane
269  * @fb: framebuffer to flip onto plane
270  * @crtc_x: x offset of primary plane on crtc
271  * @crtc_y: y offset of primary plane on crtc
272  * @crtc_w: width of primary plane rectangle on crtc
273  * @crtc_h: height of primary plane rectangle on crtc
274  * @src_x: x offset of @fb for panning
275  * @src_y: y offset of @fb for panning
276  * @src_w: width of source rectangle in @fb
277  * @src_h: height of source rectangle in @fb
278  * @ctx: lock acquire context, not used here
279  *
280  * Provides a default plane update handler for primary planes.  This is handler
281  * is called in response to a userspace SetPlane operation on the plane with a
282  * non-NULL framebuffer.  We call the driver's modeset handler to update the
283  * framebuffer.
284  *
285  * SetPlane() on a primary plane of a disabled CRTC is not supported, and will
286  * return an error.
287  *
288  * Note that we make some assumptions about hardware limitations that may not be
289  * true for all hardware --
290  *
291  * 1. Primary plane cannot be repositioned.
292  * 2. Primary plane cannot be scaled.
293  * 3. Primary plane must cover the entire CRTC.
294  * 4. Subpixel positioning is not supported.
295  *
296  * Drivers for hardware that don't have these restrictions can provide their
297  * own implementation rather than using this helper.
298  *
299  * RETURNS:
300  * Zero on success, error code on failure
301  */
302 int drm_primary_helper_update(struct drm_plane *plane, struct drm_crtc *crtc,
303 			      struct drm_framebuffer *fb,
304 			      int crtc_x, int crtc_y,
305 			      unsigned int crtc_w, unsigned int crtc_h,
306 			      uint32_t src_x, uint32_t src_y,
307 			      uint32_t src_w, uint32_t src_h,
308 			      struct drm_modeset_acquire_ctx *ctx)
309 {
310 	struct drm_mode_set set = {
311 		.crtc = crtc,
312 		.fb = fb,
313 		.mode = &crtc->mode,
314 		.x = src_x >> 16,
315 		.y = src_y >> 16,
316 	};
317 	struct drm_rect src = {
318 		.x1 = src_x,
319 		.y1 = src_y,
320 		.x2 = src_x + src_w,
321 		.y2 = src_y + src_h,
322 	};
323 	struct drm_rect dest = {
324 		.x1 = crtc_x,
325 		.y1 = crtc_y,
326 		.x2 = crtc_x + crtc_w,
327 		.y2 = crtc_y + crtc_h,
328 	};
329 	const struct drm_rect clip = {
330 		.x2 = crtc->mode.hdisplay,
331 		.y2 = crtc->mode.vdisplay,
332 	};
333 	struct drm_connector **connector_list;
334 	int num_connectors, ret;
335 	bool visible;
336 
337 	ret = drm_plane_helper_check_update(plane, crtc, fb,
338 					    &src, &dest, &clip,
339 					    DRM_MODE_ROTATE_0,
340 					    DRM_PLANE_HELPER_NO_SCALING,
341 					    DRM_PLANE_HELPER_NO_SCALING,
342 					    false, false, &visible);
343 	if (ret)
344 		return ret;
345 
346 	if (!visible)
347 		/*
348 		 * Primary plane isn't visible.  Note that unless a driver
349 		 * provides their own disable function, this will just
350 		 * wind up returning -EINVAL to userspace.
351 		 */
352 		return plane->funcs->disable_plane(plane, ctx);
353 
354 	/* Find current connectors for CRTC */
355 	num_connectors = get_connectors_for_crtc(crtc, NULL, 0);
356 	BUG_ON(num_connectors == 0);
357 	connector_list = kzalloc(num_connectors * sizeof(*connector_list),
358 				 GFP_KERNEL);
359 	if (!connector_list)
360 		return -ENOMEM;
361 	get_connectors_for_crtc(crtc, connector_list, num_connectors);
362 
363 	set.connectors = connector_list;
364 	set.num_connectors = num_connectors;
365 
366 	/*
367 	 * We call set_config() directly here rather than using
368 	 * drm_mode_set_config_internal.  We're reprogramming the same
369 	 * connectors that were already in use, so we shouldn't need the extra
370 	 * cross-CRTC fb refcounting to accomodate stealing connectors.
371 	 * drm_mode_setplane() already handles the basic refcounting for the
372 	 * framebuffers involved in this operation.
373 	 */
374 	ret = crtc->funcs->set_config(&set, ctx);
375 
376 	kfree(connector_list);
377 	return ret;
378 }
379 EXPORT_SYMBOL(drm_primary_helper_update);
380 
381 /**
382  * drm_primary_helper_disable() - Helper for primary plane disable
383  * @plane: plane to disable
384  * @ctx: lock acquire context, not used here
385  *
386  * Provides a default plane disable handler for primary planes.  This is handler
387  * is called in response to a userspace SetPlane operation on the plane with a
388  * NULL framebuffer parameter.  It unconditionally fails the disable call with
389  * -EINVAL the only way to disable the primary plane without driver support is
390  * to disable the entire CRTC. Which does not match the plane
391  * &drm_plane_funcs.disable_plane hook.
392  *
393  * Note that some hardware may be able to disable the primary plane without
394  * disabling the whole CRTC.  Drivers for such hardware should provide their
395  * own disable handler that disables just the primary plane (and they'll likely
396  * need to provide their own update handler as well to properly re-enable a
397  * disabled primary plane).
398  *
399  * RETURNS:
400  * Unconditionally returns -EINVAL.
401  */
402 int drm_primary_helper_disable(struct drm_plane *plane,
403 			       struct drm_modeset_acquire_ctx *ctx)
404 {
405 	return -EINVAL;
406 }
407 EXPORT_SYMBOL(drm_primary_helper_disable);
408 
409 /**
410  * drm_primary_helper_destroy() - Helper for primary plane destruction
411  * @plane: plane to destroy
412  *
413  * Provides a default plane destroy handler for primary planes.  This handler
414  * is called during CRTC destruction.  We disable the primary plane, remove
415  * it from the DRM plane list, and deallocate the plane structure.
416  */
417 void drm_primary_helper_destroy(struct drm_plane *plane)
418 {
419 	drm_plane_cleanup(plane);
420 	kfree(plane);
421 }
422 EXPORT_SYMBOL(drm_primary_helper_destroy);
423 
424 const struct drm_plane_funcs drm_primary_helper_funcs = {
425 	.update_plane = drm_primary_helper_update,
426 	.disable_plane = drm_primary_helper_disable,
427 	.destroy = drm_primary_helper_destroy,
428 };
429 EXPORT_SYMBOL(drm_primary_helper_funcs);
430 
431 int drm_plane_helper_commit(struct drm_plane *plane,
432 			    struct drm_plane_state *plane_state,
433 			    struct drm_framebuffer *old_fb)
434 {
435 	const struct drm_plane_helper_funcs *plane_funcs;
436 	struct drm_crtc *crtc[2];
437 	const struct drm_crtc_helper_funcs *crtc_funcs[2];
438 	int i, ret = 0;
439 
440 	plane_funcs = plane->helper_private;
441 
442 	/* Since this is a transitional helper we can't assume that plane->state
443 	 * is always valid. Hence we need to use plane->crtc instead of
444 	 * plane->state->crtc as the old crtc. */
445 	crtc[0] = plane->crtc;
446 	crtc[1] = crtc[0] != plane_state->crtc ? plane_state->crtc : NULL;
447 
448 	for (i = 0; i < 2; i++)
449 		crtc_funcs[i] = crtc[i] ? crtc[i]->helper_private : NULL;
450 
451 	if (plane_funcs->atomic_check) {
452 		ret = plane_funcs->atomic_check(plane, plane_state);
453 		if (ret)
454 			goto out;
455 	}
456 
457 	if (plane_funcs->prepare_fb && plane_state->fb != old_fb) {
458 		ret = plane_funcs->prepare_fb(plane,
459 					      plane_state);
460 		if (ret)
461 			goto out;
462 	}
463 
464 	/* Point of no return, commit sw state. */
465 	swap(plane->state, plane_state);
466 
467 	for (i = 0; i < 2; i++) {
468 		if (crtc_funcs[i] && crtc_funcs[i]->atomic_begin)
469 			crtc_funcs[i]->atomic_begin(crtc[i], crtc[i]->state);
470 	}
471 
472 	/*
473 	 * Drivers may optionally implement the ->atomic_disable callback, so
474 	 * special-case that here.
475 	 */
476 	if (drm_atomic_plane_disabling(plane_state, plane->state) &&
477 	    plane_funcs->atomic_disable)
478 		plane_funcs->atomic_disable(plane, plane_state);
479 	else
480 		plane_funcs->atomic_update(plane, plane_state);
481 
482 	for (i = 0; i < 2; i++) {
483 		if (crtc_funcs[i] && crtc_funcs[i]->atomic_flush)
484 			crtc_funcs[i]->atomic_flush(crtc[i], crtc[i]->state);
485 	}
486 
487 	/*
488 	 * If we only moved the plane and didn't change fb's, there's no need to
489 	 * wait for vblank.
490 	 */
491 	if (plane->state->fb == old_fb)
492 		goto out;
493 
494 	for (i = 0; i < 2; i++) {
495 		if (!crtc[i])
496 			continue;
497 
498 		if (crtc[i]->cursor == plane)
499 			continue;
500 
501 		/* There's no other way to figure out whether the crtc is running. */
502 		ret = drm_crtc_vblank_get(crtc[i]);
503 		if (ret == 0) {
504 			drm_crtc_wait_one_vblank(crtc[i]);
505 			drm_crtc_vblank_put(crtc[i]);
506 		}
507 
508 		ret = 0;
509 	}
510 
511 	if (plane_funcs->cleanup_fb)
512 		plane_funcs->cleanup_fb(plane, plane_state);
513 out:
514 	if (plane->funcs->atomic_destroy_state)
515 		plane->funcs->atomic_destroy_state(plane, plane_state);
516 	else
517 		drm_atomic_helper_plane_destroy_state(plane, plane_state);
518 
519 	return ret;
520 }
521 
522 /**
523  * drm_plane_helper_update() - Transitional helper for plane update
524  * @plane: plane object to update
525  * @crtc: owning CRTC of owning plane
526  * @fb: framebuffer to flip onto plane
527  * @crtc_x: x offset of primary plane on crtc
528  * @crtc_y: y offset of primary plane on crtc
529  * @crtc_w: width of primary plane rectangle on crtc
530  * @crtc_h: height of primary plane rectangle on crtc
531  * @src_x: x offset of @fb for panning
532  * @src_y: y offset of @fb for panning
533  * @src_w: width of source rectangle in @fb
534  * @src_h: height of source rectangle in @fb
535  *
536  * Provides a default plane update handler using the atomic plane update
537  * functions. It is fully left to the driver to check plane constraints and
538  * handle corner-cases like a fully occluded or otherwise invisible plane.
539  *
540  * This is useful for piecewise transitioning of a driver to the atomic helpers.
541  *
542  * RETURNS:
543  * Zero on success, error code on failure
544  */
545 int drm_plane_helper_update(struct drm_plane *plane, struct drm_crtc *crtc,
546 			    struct drm_framebuffer *fb,
547 			    int crtc_x, int crtc_y,
548 			    unsigned int crtc_w, unsigned int crtc_h,
549 			    uint32_t src_x, uint32_t src_y,
550 			    uint32_t src_w, uint32_t src_h)
551 {
552 	struct drm_plane_state *plane_state;
553 
554 	if (plane->funcs->atomic_duplicate_state)
555 		plane_state = plane->funcs->atomic_duplicate_state(plane);
556 	else {
557 		if (!plane->state)
558 			drm_atomic_helper_plane_reset(plane);
559 
560 		plane_state = drm_atomic_helper_plane_duplicate_state(plane);
561 	}
562 	if (!plane_state)
563 		return -ENOMEM;
564 	plane_state->plane = plane;
565 
566 	plane_state->crtc = crtc;
567 	drm_atomic_set_fb_for_plane(plane_state, fb);
568 	plane_state->crtc_x = crtc_x;
569 	plane_state->crtc_y = crtc_y;
570 	plane_state->crtc_h = crtc_h;
571 	plane_state->crtc_w = crtc_w;
572 	plane_state->src_x = src_x;
573 	plane_state->src_y = src_y;
574 	plane_state->src_h = src_h;
575 	plane_state->src_w = src_w;
576 
577 	return drm_plane_helper_commit(plane, plane_state, plane->fb);
578 }
579 EXPORT_SYMBOL(drm_plane_helper_update);
580 
581 /**
582  * drm_plane_helper_disable() - Transitional helper for plane disable
583  * @plane: plane to disable
584  *
585  * Provides a default plane disable handler using the atomic plane update
586  * functions. It is fully left to the driver to check plane constraints and
587  * handle corner-cases like a fully occluded or otherwise invisible plane.
588  *
589  * This is useful for piecewise transitioning of a driver to the atomic helpers.
590  *
591  * RETURNS:
592  * Zero on success, error code on failure
593  */
594 int drm_plane_helper_disable(struct drm_plane *plane)
595 {
596 	struct drm_plane_state *plane_state;
597 
598 	/* crtc helpers love to call disable functions for already disabled hw
599 	 * functions. So cope with that. */
600 	if (!plane->crtc)
601 		return 0;
602 
603 	if (plane->funcs->atomic_duplicate_state)
604 		plane_state = plane->funcs->atomic_duplicate_state(plane);
605 	else {
606 		if (!plane->state)
607 			drm_atomic_helper_plane_reset(plane);
608 
609 		plane_state = drm_atomic_helper_plane_duplicate_state(plane);
610 	}
611 	if (!plane_state)
612 		return -ENOMEM;
613 	plane_state->plane = plane;
614 
615 	plane_state->crtc = NULL;
616 	drm_atomic_set_fb_for_plane(plane_state, NULL);
617 
618 	return drm_plane_helper_commit(plane, plane_state, plane->fb);
619 }
620 EXPORT_SYMBOL(drm_plane_helper_disable);
621