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_update() - Check plane update for validity
104  * @plane: plane object to update
105  * @crtc: owning CRTC of owning plane
106  * @fb: framebuffer to flip onto plane
107  * @src: source coordinates in 16.16 fixed point
108  * @dst: integer destination coordinates
109  * @rotation: plane rotation
110  * @min_scale: minimum @src:@dest scaling factor in 16.16 fixed point
111  * @max_scale: maximum @src:@dest scaling factor in 16.16 fixed point
112  * @can_position: is it legal to position the plane such that it
113  *                doesn't cover the entire crtc?  This will generally
114  *                only be false for primary planes.
115  * @can_update_disabled: can the plane be updated while the crtc
116  *                       is disabled?
117  * @visible: output parameter indicating whether plane is still visible after
118  *           clipping
119  *
120  * Checks that a desired plane update is valid.  Drivers that provide
121  * their own plane handling rather than helper-provided implementations may
122  * still wish to call this function to avoid duplication of error checking
123  * code.
124  *
125  * RETURNS:
126  * Zero if update appears valid, error code on failure
127  */
128 int drm_plane_helper_check_update(struct drm_plane *plane,
129 				  struct drm_crtc *crtc,
130 				  struct drm_framebuffer *fb,
131 				  struct drm_rect *src,
132 				  struct drm_rect *dst,
133 				  unsigned int rotation,
134 				  int min_scale,
135 				  int max_scale,
136 				  bool can_position,
137 				  bool can_update_disabled,
138 				  bool *visible)
139 {
140 	struct drm_plane_state plane_state = {
141 		.plane = plane,
142 		.crtc = crtc,
143 		.fb = fb,
144 		.src_x = src->x1,
145 		.src_y = src->y1,
146 		.src_w = drm_rect_width(src),
147 		.src_h = drm_rect_height(src),
148 		.crtc_x = dst->x1,
149 		.crtc_y = dst->y1,
150 		.crtc_w = drm_rect_width(dst),
151 		.crtc_h = drm_rect_height(dst),
152 		.rotation = rotation,
153 		.visible = *visible,
154 	};
155 	struct drm_crtc_state crtc_state = {
156 		.crtc = crtc,
157 		.enable = crtc->enabled,
158 		.mode = crtc->mode,
159 	};
160 	int ret;
161 
162 	ret = drm_atomic_helper_check_plane_state(&plane_state, &crtc_state,
163 						  min_scale, max_scale,
164 						  can_position,
165 						  can_update_disabled);
166 	if (ret)
167 		return ret;
168 
169 	*src = plane_state.src;
170 	*dst = plane_state.dst;
171 	*visible = plane_state.visible;
172 
173 	return 0;
174 }
175 EXPORT_SYMBOL(drm_plane_helper_check_update);
176 
177 /**
178  * drm_primary_helper_update() - Helper for primary plane update
179  * @plane: plane object to update
180  * @crtc: owning CRTC of owning plane
181  * @fb: framebuffer to flip onto plane
182  * @crtc_x: x offset of primary plane on crtc
183  * @crtc_y: y offset of primary plane on crtc
184  * @crtc_w: width of primary plane rectangle on crtc
185  * @crtc_h: height of primary plane rectangle on crtc
186  * @src_x: x offset of @fb for panning
187  * @src_y: y offset of @fb for panning
188  * @src_w: width of source rectangle in @fb
189  * @src_h: height of source rectangle in @fb
190  * @ctx: lock acquire context, not used here
191  *
192  * Provides a default plane update handler for primary planes.  This is handler
193  * is called in response to a userspace SetPlane operation on the plane with a
194  * non-NULL framebuffer.  We call the driver's modeset handler to update the
195  * framebuffer.
196  *
197  * SetPlane() on a primary plane of a disabled CRTC is not supported, and will
198  * return an error.
199  *
200  * Note that we make some assumptions about hardware limitations that may not be
201  * true for all hardware --
202  *
203  * 1. Primary plane cannot be repositioned.
204  * 2. Primary plane cannot be scaled.
205  * 3. Primary plane must cover the entire CRTC.
206  * 4. Subpixel positioning is not supported.
207  *
208  * Drivers for hardware that don't have these restrictions can provide their
209  * own implementation rather than using this helper.
210  *
211  * RETURNS:
212  * Zero on success, error code on failure
213  */
214 int drm_primary_helper_update(struct drm_plane *plane, struct drm_crtc *crtc,
215 			      struct drm_framebuffer *fb,
216 			      int crtc_x, int crtc_y,
217 			      unsigned int crtc_w, unsigned int crtc_h,
218 			      uint32_t src_x, uint32_t src_y,
219 			      uint32_t src_w, uint32_t src_h,
220 			      struct drm_modeset_acquire_ctx *ctx)
221 {
222 	struct drm_mode_set set = {
223 		.crtc = crtc,
224 		.fb = fb,
225 		.mode = &crtc->mode,
226 		.x = src_x >> 16,
227 		.y = src_y >> 16,
228 	};
229 	struct drm_rect src = {
230 		.x1 = src_x,
231 		.y1 = src_y,
232 		.x2 = src_x + src_w,
233 		.y2 = src_y + src_h,
234 	};
235 	struct drm_rect dest = {
236 		.x1 = crtc_x,
237 		.y1 = crtc_y,
238 		.x2 = crtc_x + crtc_w,
239 		.y2 = crtc_y + crtc_h,
240 	};
241 	struct drm_connector **connector_list;
242 	int num_connectors, ret;
243 	bool visible;
244 
245 	ret = drm_plane_helper_check_update(plane, crtc, fb,
246 					    &src, &dest,
247 					    DRM_MODE_ROTATE_0,
248 					    DRM_PLANE_HELPER_NO_SCALING,
249 					    DRM_PLANE_HELPER_NO_SCALING,
250 					    false, false, &visible);
251 	if (ret)
252 		return ret;
253 
254 	if (!visible)
255 		/*
256 		 * Primary plane isn't visible.  Note that unless a driver
257 		 * provides their own disable function, this will just
258 		 * wind up returning -EINVAL to userspace.
259 		 */
260 		return plane->funcs->disable_plane(plane, ctx);
261 
262 	/* Find current connectors for CRTC */
263 	num_connectors = get_connectors_for_crtc(crtc, NULL, 0);
264 	BUG_ON(num_connectors == 0);
265 	connector_list = kcalloc(num_connectors, sizeof(*connector_list),
266 				 GFP_KERNEL);
267 	if (!connector_list)
268 		return -ENOMEM;
269 	get_connectors_for_crtc(crtc, connector_list, num_connectors);
270 
271 	set.connectors = connector_list;
272 	set.num_connectors = num_connectors;
273 
274 	/*
275 	 * We call set_config() directly here rather than using
276 	 * drm_mode_set_config_internal.  We're reprogramming the same
277 	 * connectors that were already in use, so we shouldn't need the extra
278 	 * cross-CRTC fb refcounting to accomodate stealing connectors.
279 	 * drm_mode_setplane() already handles the basic refcounting for the
280 	 * framebuffers involved in this operation.
281 	 */
282 	ret = crtc->funcs->set_config(&set, ctx);
283 
284 	kfree(connector_list);
285 	return ret;
286 }
287 EXPORT_SYMBOL(drm_primary_helper_update);
288 
289 /**
290  * drm_primary_helper_disable() - Helper for primary plane disable
291  * @plane: plane to disable
292  * @ctx: lock acquire context, not used here
293  *
294  * Provides a default plane disable handler for primary planes.  This is handler
295  * is called in response to a userspace SetPlane operation on the plane with a
296  * NULL framebuffer parameter.  It unconditionally fails the disable call with
297  * -EINVAL the only way to disable the primary plane without driver support is
298  * to disable the entire CRTC. Which does not match the plane
299  * &drm_plane_funcs.disable_plane hook.
300  *
301  * Note that some hardware may be able to disable the primary plane without
302  * disabling the whole CRTC.  Drivers for such hardware should provide their
303  * own disable handler that disables just the primary plane (and they'll likely
304  * need to provide their own update handler as well to properly re-enable a
305  * disabled primary plane).
306  *
307  * RETURNS:
308  * Unconditionally returns -EINVAL.
309  */
310 int drm_primary_helper_disable(struct drm_plane *plane,
311 			       struct drm_modeset_acquire_ctx *ctx)
312 {
313 	return -EINVAL;
314 }
315 EXPORT_SYMBOL(drm_primary_helper_disable);
316 
317 /**
318  * drm_primary_helper_destroy() - Helper for primary plane destruction
319  * @plane: plane to destroy
320  *
321  * Provides a default plane destroy handler for primary planes.  This handler
322  * is called during CRTC destruction.  We disable the primary plane, remove
323  * it from the DRM plane list, and deallocate the plane structure.
324  */
325 void drm_primary_helper_destroy(struct drm_plane *plane)
326 {
327 	drm_plane_cleanup(plane);
328 	kfree(plane);
329 }
330 EXPORT_SYMBOL(drm_primary_helper_destroy);
331 
332 const struct drm_plane_funcs drm_primary_helper_funcs = {
333 	.update_plane = drm_primary_helper_update,
334 	.disable_plane = drm_primary_helper_disable,
335 	.destroy = drm_primary_helper_destroy,
336 };
337 EXPORT_SYMBOL(drm_primary_helper_funcs);
338 
339 int drm_plane_helper_commit(struct drm_plane *plane,
340 			    struct drm_plane_state *plane_state,
341 			    struct drm_framebuffer *old_fb)
342 {
343 	const struct drm_plane_helper_funcs *plane_funcs;
344 	struct drm_crtc *crtc[2];
345 	const struct drm_crtc_helper_funcs *crtc_funcs[2];
346 	int i, ret = 0;
347 
348 	plane_funcs = plane->helper_private;
349 
350 	/* Since this is a transitional helper we can't assume that plane->state
351 	 * is always valid. Hence we need to use plane->crtc instead of
352 	 * plane->state->crtc as the old crtc. */
353 	crtc[0] = plane->crtc;
354 	crtc[1] = crtc[0] != plane_state->crtc ? plane_state->crtc : NULL;
355 
356 	for (i = 0; i < 2; i++)
357 		crtc_funcs[i] = crtc[i] ? crtc[i]->helper_private : NULL;
358 
359 	if (plane_funcs->atomic_check) {
360 		ret = plane_funcs->atomic_check(plane, plane_state);
361 		if (ret)
362 			goto out;
363 	}
364 
365 	if (plane_funcs->prepare_fb && plane_state->fb != old_fb) {
366 		ret = plane_funcs->prepare_fb(plane,
367 					      plane_state);
368 		if (ret)
369 			goto out;
370 	}
371 
372 	/* Point of no return, commit sw state. */
373 	swap(plane->state, plane_state);
374 
375 	for (i = 0; i < 2; i++) {
376 		if (crtc_funcs[i] && crtc_funcs[i]->atomic_begin)
377 			crtc_funcs[i]->atomic_begin(crtc[i], crtc[i]->state);
378 	}
379 
380 	/*
381 	 * Drivers may optionally implement the ->atomic_disable callback, so
382 	 * special-case that here.
383 	 */
384 	if (drm_atomic_plane_disabling(plane_state, plane->state) &&
385 	    plane_funcs->atomic_disable)
386 		plane_funcs->atomic_disable(plane, plane_state);
387 	else
388 		plane_funcs->atomic_update(plane, plane_state);
389 
390 	for (i = 0; i < 2; i++) {
391 		if (crtc_funcs[i] && crtc_funcs[i]->atomic_flush)
392 			crtc_funcs[i]->atomic_flush(crtc[i], crtc[i]->state);
393 	}
394 
395 	/*
396 	 * If we only moved the plane and didn't change fb's, there's no need to
397 	 * wait for vblank.
398 	 */
399 	if (plane->state->fb == old_fb)
400 		goto out;
401 
402 	for (i = 0; i < 2; i++) {
403 		if (!crtc[i])
404 			continue;
405 
406 		if (crtc[i]->cursor == plane)
407 			continue;
408 
409 		/* There's no other way to figure out whether the crtc is running. */
410 		ret = drm_crtc_vblank_get(crtc[i]);
411 		if (ret == 0) {
412 			drm_crtc_wait_one_vblank(crtc[i]);
413 			drm_crtc_vblank_put(crtc[i]);
414 		}
415 
416 		ret = 0;
417 	}
418 
419 	if (plane_funcs->cleanup_fb)
420 		plane_funcs->cleanup_fb(plane, plane_state);
421 out:
422 	if (plane->funcs->atomic_destroy_state)
423 		plane->funcs->atomic_destroy_state(plane, plane_state);
424 	else
425 		drm_atomic_helper_plane_destroy_state(plane, plane_state);
426 
427 	return ret;
428 }
429 
430 /**
431  * drm_plane_helper_update() - Transitional helper for plane update
432  * @plane: plane object to update
433  * @crtc: owning CRTC of owning plane
434  * @fb: framebuffer to flip onto plane
435  * @crtc_x: x offset of primary plane on crtc
436  * @crtc_y: y offset of primary plane on crtc
437  * @crtc_w: width of primary plane rectangle on crtc
438  * @crtc_h: height of primary plane rectangle on crtc
439  * @src_x: x offset of @fb for panning
440  * @src_y: y offset of @fb for panning
441  * @src_w: width of source rectangle in @fb
442  * @src_h: height of source rectangle in @fb
443  *
444  * Provides a default plane update handler using the atomic plane update
445  * functions. It is fully left to the driver to check plane constraints and
446  * handle corner-cases like a fully occluded or otherwise invisible plane.
447  *
448  * This is useful for piecewise transitioning of a driver to the atomic helpers.
449  *
450  * RETURNS:
451  * Zero on success, error code on failure
452  */
453 int drm_plane_helper_update(struct drm_plane *plane, struct drm_crtc *crtc,
454 			    struct drm_framebuffer *fb,
455 			    int crtc_x, int crtc_y,
456 			    unsigned int crtc_w, unsigned int crtc_h,
457 			    uint32_t src_x, uint32_t src_y,
458 			    uint32_t src_w, uint32_t src_h)
459 {
460 	struct drm_plane_state *plane_state;
461 
462 	if (plane->funcs->atomic_duplicate_state)
463 		plane_state = plane->funcs->atomic_duplicate_state(plane);
464 	else {
465 		if (!plane->state)
466 			drm_atomic_helper_plane_reset(plane);
467 
468 		plane_state = drm_atomic_helper_plane_duplicate_state(plane);
469 	}
470 	if (!plane_state)
471 		return -ENOMEM;
472 	plane_state->plane = plane;
473 
474 	plane_state->crtc = crtc;
475 	drm_atomic_set_fb_for_plane(plane_state, fb);
476 	plane_state->crtc_x = crtc_x;
477 	plane_state->crtc_y = crtc_y;
478 	plane_state->crtc_h = crtc_h;
479 	plane_state->crtc_w = crtc_w;
480 	plane_state->src_x = src_x;
481 	plane_state->src_y = src_y;
482 	plane_state->src_h = src_h;
483 	plane_state->src_w = src_w;
484 
485 	return drm_plane_helper_commit(plane, plane_state, plane->fb);
486 }
487 EXPORT_SYMBOL(drm_plane_helper_update);
488 
489 /**
490  * drm_plane_helper_disable() - Transitional helper for plane disable
491  * @plane: plane to disable
492  *
493  * Provides a default plane disable handler using the atomic plane update
494  * functions. It is fully left to the driver to check plane constraints and
495  * handle corner-cases like a fully occluded or otherwise invisible plane.
496  *
497  * This is useful for piecewise transitioning of a driver to the atomic helpers.
498  *
499  * RETURNS:
500  * Zero on success, error code on failure
501  */
502 int drm_plane_helper_disable(struct drm_plane *plane)
503 {
504 	struct drm_plane_state *plane_state;
505 
506 	/* crtc helpers love to call disable functions for already disabled hw
507 	 * functions. So cope with that. */
508 	if (!plane->crtc)
509 		return 0;
510 
511 	if (plane->funcs->atomic_duplicate_state)
512 		plane_state = plane->funcs->atomic_duplicate_state(plane);
513 	else {
514 		if (!plane->state)
515 			drm_atomic_helper_plane_reset(plane);
516 
517 		plane_state = drm_atomic_helper_plane_duplicate_state(plane);
518 	}
519 	if (!plane_state)
520 		return -ENOMEM;
521 	plane_state->plane = plane;
522 
523 	plane_state->crtc = NULL;
524 	drm_atomic_set_fb_for_plane(plane_state, NULL);
525 
526 	return drm_plane_helper_commit(plane, plane_state, plane->fb);
527 }
528 EXPORT_SYMBOL(drm_plane_helper_disable);
529