1 /*
2  * Copyright (C) 2014 Red Hat
3  * Copyright (C) 2014 Intel Corp.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a
6  * copy of this software and associated documentation files (the "Software"),
7  * to deal in the Software without restriction, including without limitation
8  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9  * and/or sell copies of the Software, and to permit persons to whom the
10  * Software is furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
18  * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
19  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
20  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
21  * OTHER DEALINGS IN THE SOFTWARE.
22  *
23  * Authors:
24  * Rob Clark <robdclark@gmail.com>
25  * Daniel Vetter <daniel.vetter@ffwll.ch>
26  */
27 
28 #include <drm/drmP.h>
29 #include <drm/drm_atomic.h>
30 #include <drm/drm_atomic_uapi.h>
31 #include <drm/drm_plane_helper.h>
32 #include <drm/drm_atomic_helper.h>
33 #include <drm/drm_writeback.h>
34 #include <drm/drm_damage_helper.h>
35 #include <linux/dma-fence.h>
36 
37 #include "drm_crtc_helper_internal.h"
38 #include "drm_crtc_internal.h"
39 
40 /**
41  * DOC: overview
42  *
43  * This helper library provides implementations of check and commit functions on
44  * top of the CRTC modeset helper callbacks and the plane helper callbacks. It
45  * also provides convenience implementations for the atomic state handling
46  * callbacks for drivers which don't need to subclass the drm core structures to
47  * add their own additional internal state.
48  *
49  * This library also provides default implementations for the check callback in
50  * drm_atomic_helper_check() and for the commit callback with
51  * drm_atomic_helper_commit(). But the individual stages and callbacks are
52  * exposed to allow drivers to mix and match and e.g. use the plane helpers only
53  * together with a driver private modeset implementation.
54  *
55  * This library also provides implementations for all the legacy driver
56  * interfaces on top of the atomic interface. See drm_atomic_helper_set_config(),
57  * drm_atomic_helper_disable_plane(), drm_atomic_helper_disable_plane() and the
58  * various functions to implement set_property callbacks. New drivers must not
59  * implement these functions themselves but must use the provided helpers.
60  *
61  * The atomic helper uses the same function table structures as all other
62  * modesetting helpers. See the documentation for &struct drm_crtc_helper_funcs,
63  * struct &drm_encoder_helper_funcs and &struct drm_connector_helper_funcs. It
64  * also shares the &struct drm_plane_helper_funcs function table with the plane
65  * helpers.
66  */
67 static void
68 drm_atomic_helper_plane_changed(struct drm_atomic_state *state,
69 				struct drm_plane_state *old_plane_state,
70 				struct drm_plane_state *plane_state,
71 				struct drm_plane *plane)
72 {
73 	struct drm_crtc_state *crtc_state;
74 
75 	if (old_plane_state->crtc) {
76 		crtc_state = drm_atomic_get_new_crtc_state(state,
77 							   old_plane_state->crtc);
78 
79 		if (WARN_ON(!crtc_state))
80 			return;
81 
82 		crtc_state->planes_changed = true;
83 	}
84 
85 	if (plane_state->crtc) {
86 		crtc_state = drm_atomic_get_new_crtc_state(state, plane_state->crtc);
87 
88 		if (WARN_ON(!crtc_state))
89 			return;
90 
91 		crtc_state->planes_changed = true;
92 	}
93 }
94 
95 /*
96  * For connectors that support multiple encoders, either the
97  * .atomic_best_encoder() or .best_encoder() operation must be implemented.
98  */
99 static struct drm_encoder *
100 pick_single_encoder_for_connector(struct drm_connector *connector)
101 {
102 	WARN_ON(connector->encoder_ids[1]);
103 	return drm_encoder_find(connector->dev, NULL, connector->encoder_ids[0]);
104 }
105 
106 static int handle_conflicting_encoders(struct drm_atomic_state *state,
107 				       bool disable_conflicting_encoders)
108 {
109 	struct drm_connector_state *new_conn_state;
110 	struct drm_connector *connector;
111 	struct drm_connector_list_iter conn_iter;
112 	struct drm_encoder *encoder;
113 	unsigned encoder_mask = 0;
114 	int i, ret = 0;
115 
116 	/*
117 	 * First loop, find all newly assigned encoders from the connectors
118 	 * part of the state. If the same encoder is assigned to multiple
119 	 * connectors bail out.
120 	 */
121 	for_each_new_connector_in_state(state, connector, new_conn_state, i) {
122 		const struct drm_connector_helper_funcs *funcs = connector->helper_private;
123 		struct drm_encoder *new_encoder;
124 
125 		if (!new_conn_state->crtc)
126 			continue;
127 
128 		if (funcs->atomic_best_encoder)
129 			new_encoder = funcs->atomic_best_encoder(connector, new_conn_state);
130 		else if (funcs->best_encoder)
131 			new_encoder = funcs->best_encoder(connector);
132 		else
133 			new_encoder = pick_single_encoder_for_connector(connector);
134 
135 		if (new_encoder) {
136 			if (encoder_mask & drm_encoder_mask(new_encoder)) {
137 				DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] on [CONNECTOR:%d:%s] already assigned\n",
138 					new_encoder->base.id, new_encoder->name,
139 					connector->base.id, connector->name);
140 
141 				return -EINVAL;
142 			}
143 
144 			encoder_mask |= drm_encoder_mask(new_encoder);
145 		}
146 	}
147 
148 	if (!encoder_mask)
149 		return 0;
150 
151 	/*
152 	 * Second loop, iterate over all connectors not part of the state.
153 	 *
154 	 * If a conflicting encoder is found and disable_conflicting_encoders
155 	 * is not set, an error is returned. Userspace can provide a solution
156 	 * through the atomic ioctl.
157 	 *
158 	 * If the flag is set conflicting connectors are removed from the crtc
159 	 * and the crtc is disabled if no encoder is left. This preserves
160 	 * compatibility with the legacy set_config behavior.
161 	 */
162 	drm_connector_list_iter_begin(state->dev, &conn_iter);
163 	drm_for_each_connector_iter(connector, &conn_iter) {
164 		struct drm_crtc_state *crtc_state;
165 
166 		if (drm_atomic_get_new_connector_state(state, connector))
167 			continue;
168 
169 		encoder = connector->state->best_encoder;
170 		if (!encoder || !(encoder_mask & drm_encoder_mask(encoder)))
171 			continue;
172 
173 		if (!disable_conflicting_encoders) {
174 			DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] in use on [CRTC:%d:%s] by [CONNECTOR:%d:%s]\n",
175 					 encoder->base.id, encoder->name,
176 					 connector->state->crtc->base.id,
177 					 connector->state->crtc->name,
178 					 connector->base.id, connector->name);
179 			ret = -EINVAL;
180 			goto out;
181 		}
182 
183 		new_conn_state = drm_atomic_get_connector_state(state, connector);
184 		if (IS_ERR(new_conn_state)) {
185 			ret = PTR_ERR(new_conn_state);
186 			goto out;
187 		}
188 
189 		DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] in use on [CRTC:%d:%s], disabling [CONNECTOR:%d:%s]\n",
190 				 encoder->base.id, encoder->name,
191 				 new_conn_state->crtc->base.id, new_conn_state->crtc->name,
192 				 connector->base.id, connector->name);
193 
194 		crtc_state = drm_atomic_get_new_crtc_state(state, new_conn_state->crtc);
195 
196 		ret = drm_atomic_set_crtc_for_connector(new_conn_state, NULL);
197 		if (ret)
198 			goto out;
199 
200 		if (!crtc_state->connector_mask) {
201 			ret = drm_atomic_set_mode_prop_for_crtc(crtc_state,
202 								NULL);
203 			if (ret < 0)
204 				goto out;
205 
206 			crtc_state->active = false;
207 		}
208 	}
209 out:
210 	drm_connector_list_iter_end(&conn_iter);
211 
212 	return ret;
213 }
214 
215 static void
216 set_best_encoder(struct drm_atomic_state *state,
217 		 struct drm_connector_state *conn_state,
218 		 struct drm_encoder *encoder)
219 {
220 	struct drm_crtc_state *crtc_state;
221 	struct drm_crtc *crtc;
222 
223 	if (conn_state->best_encoder) {
224 		/* Unset the encoder_mask in the old crtc state. */
225 		crtc = conn_state->connector->state->crtc;
226 
227 		/* A NULL crtc is an error here because we should have
228 		 *  duplicated a NULL best_encoder when crtc was NULL.
229 		 * As an exception restoring duplicated atomic state
230 		 * during resume is allowed, so don't warn when
231 		 * best_encoder is equal to encoder we intend to set.
232 		 */
233 		WARN_ON(!crtc && encoder != conn_state->best_encoder);
234 		if (crtc) {
235 			crtc_state = drm_atomic_get_new_crtc_state(state, crtc);
236 
237 			crtc_state->encoder_mask &=
238 				~drm_encoder_mask(conn_state->best_encoder);
239 		}
240 	}
241 
242 	if (encoder) {
243 		crtc = conn_state->crtc;
244 		WARN_ON(!crtc);
245 		if (crtc) {
246 			crtc_state = drm_atomic_get_new_crtc_state(state, crtc);
247 
248 			crtc_state->encoder_mask |=
249 				drm_encoder_mask(encoder);
250 		}
251 	}
252 
253 	conn_state->best_encoder = encoder;
254 }
255 
256 static void
257 steal_encoder(struct drm_atomic_state *state,
258 	      struct drm_encoder *encoder)
259 {
260 	struct drm_crtc_state *crtc_state;
261 	struct drm_connector *connector;
262 	struct drm_connector_state *old_connector_state, *new_connector_state;
263 	int i;
264 
265 	for_each_oldnew_connector_in_state(state, connector, old_connector_state, new_connector_state, i) {
266 		struct drm_crtc *encoder_crtc;
267 
268 		if (new_connector_state->best_encoder != encoder)
269 			continue;
270 
271 		encoder_crtc = old_connector_state->crtc;
272 
273 		DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] in use on [CRTC:%d:%s], stealing it\n",
274 				 encoder->base.id, encoder->name,
275 				 encoder_crtc->base.id, encoder_crtc->name);
276 
277 		set_best_encoder(state, new_connector_state, NULL);
278 
279 		crtc_state = drm_atomic_get_new_crtc_state(state, encoder_crtc);
280 		crtc_state->connectors_changed = true;
281 
282 		return;
283 	}
284 }
285 
286 static int
287 update_connector_routing(struct drm_atomic_state *state,
288 			 struct drm_connector *connector,
289 			 struct drm_connector_state *old_connector_state,
290 			 struct drm_connector_state *new_connector_state)
291 {
292 	const struct drm_connector_helper_funcs *funcs;
293 	struct drm_encoder *new_encoder;
294 	struct drm_crtc_state *crtc_state;
295 
296 	DRM_DEBUG_ATOMIC("Updating routing for [CONNECTOR:%d:%s]\n",
297 			 connector->base.id,
298 			 connector->name);
299 
300 	if (old_connector_state->crtc != new_connector_state->crtc) {
301 		if (old_connector_state->crtc) {
302 			crtc_state = drm_atomic_get_new_crtc_state(state, old_connector_state->crtc);
303 			crtc_state->connectors_changed = true;
304 		}
305 
306 		if (new_connector_state->crtc) {
307 			crtc_state = drm_atomic_get_new_crtc_state(state, new_connector_state->crtc);
308 			crtc_state->connectors_changed = true;
309 		}
310 	}
311 
312 	if (!new_connector_state->crtc) {
313 		DRM_DEBUG_ATOMIC("Disabling [CONNECTOR:%d:%s]\n",
314 				connector->base.id,
315 				connector->name);
316 
317 		set_best_encoder(state, new_connector_state, NULL);
318 
319 		return 0;
320 	}
321 
322 	crtc_state = drm_atomic_get_new_crtc_state(state,
323 						   new_connector_state->crtc);
324 	/*
325 	 * For compatibility with legacy users, we want to make sure that
326 	 * we allow DPMS On->Off modesets on unregistered connectors. Modesets
327 	 * which would result in anything else must be considered invalid, to
328 	 * avoid turning on new displays on dead connectors.
329 	 *
330 	 * Since the connector can be unregistered at any point during an
331 	 * atomic check or commit, this is racy. But that's OK: all we care
332 	 * about is ensuring that userspace can't do anything but shut off the
333 	 * display on a connector that was destroyed after it's been notified,
334 	 * not before.
335 	 *
336 	 * Additionally, we also want to ignore connector registration when
337 	 * we're trying to restore an atomic state during system resume since
338 	 * there's a chance the connector may have been destroyed during the
339 	 * process, but it's better to ignore that then cause
340 	 * drm_atomic_helper_resume() to fail.
341 	 */
342 	if (!state->duplicated && drm_connector_is_unregistered(connector) &&
343 	    crtc_state->active) {
344 		DRM_DEBUG_ATOMIC("[CONNECTOR:%d:%s] is not registered\n",
345 				 connector->base.id, connector->name);
346 		return -EINVAL;
347 	}
348 
349 	funcs = connector->helper_private;
350 
351 	if (funcs->atomic_best_encoder)
352 		new_encoder = funcs->atomic_best_encoder(connector,
353 							 new_connector_state);
354 	else if (funcs->best_encoder)
355 		new_encoder = funcs->best_encoder(connector);
356 	else
357 		new_encoder = pick_single_encoder_for_connector(connector);
358 
359 	if (!new_encoder) {
360 		DRM_DEBUG_ATOMIC("No suitable encoder found for [CONNECTOR:%d:%s]\n",
361 				 connector->base.id,
362 				 connector->name);
363 		return -EINVAL;
364 	}
365 
366 	if (!drm_encoder_crtc_ok(new_encoder, new_connector_state->crtc)) {
367 		DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] incompatible with [CRTC:%d:%s]\n",
368 				 new_encoder->base.id,
369 				 new_encoder->name,
370 				 new_connector_state->crtc->base.id,
371 				 new_connector_state->crtc->name);
372 		return -EINVAL;
373 	}
374 
375 	if (new_encoder == new_connector_state->best_encoder) {
376 		set_best_encoder(state, new_connector_state, new_encoder);
377 
378 		DRM_DEBUG_ATOMIC("[CONNECTOR:%d:%s] keeps [ENCODER:%d:%s], now on [CRTC:%d:%s]\n",
379 				 connector->base.id,
380 				 connector->name,
381 				 new_encoder->base.id,
382 				 new_encoder->name,
383 				 new_connector_state->crtc->base.id,
384 				 new_connector_state->crtc->name);
385 
386 		return 0;
387 	}
388 
389 	steal_encoder(state, new_encoder);
390 
391 	set_best_encoder(state, new_connector_state, new_encoder);
392 
393 	crtc_state->connectors_changed = true;
394 
395 	DRM_DEBUG_ATOMIC("[CONNECTOR:%d:%s] using [ENCODER:%d:%s] on [CRTC:%d:%s]\n",
396 			 connector->base.id,
397 			 connector->name,
398 			 new_encoder->base.id,
399 			 new_encoder->name,
400 			 new_connector_state->crtc->base.id,
401 			 new_connector_state->crtc->name);
402 
403 	return 0;
404 }
405 
406 static int
407 mode_fixup(struct drm_atomic_state *state)
408 {
409 	struct drm_crtc *crtc;
410 	struct drm_crtc_state *new_crtc_state;
411 	struct drm_connector *connector;
412 	struct drm_connector_state *new_conn_state;
413 	int i;
414 	int ret;
415 
416 	for_each_new_crtc_in_state(state, crtc, new_crtc_state, i) {
417 		if (!new_crtc_state->mode_changed &&
418 		    !new_crtc_state->connectors_changed)
419 			continue;
420 
421 		drm_mode_copy(&new_crtc_state->adjusted_mode, &new_crtc_state->mode);
422 	}
423 
424 	for_each_new_connector_in_state(state, connector, new_conn_state, i) {
425 		const struct drm_encoder_helper_funcs *funcs;
426 		struct drm_encoder *encoder;
427 
428 		WARN_ON(!!new_conn_state->best_encoder != !!new_conn_state->crtc);
429 
430 		if (!new_conn_state->crtc || !new_conn_state->best_encoder)
431 			continue;
432 
433 		new_crtc_state =
434 			drm_atomic_get_new_crtc_state(state, new_conn_state->crtc);
435 
436 		/*
437 		 * Each encoder has at most one connector (since we always steal
438 		 * it away), so we won't call ->mode_fixup twice.
439 		 */
440 		encoder = new_conn_state->best_encoder;
441 		funcs = encoder->helper_private;
442 
443 		ret = drm_bridge_mode_fixup(encoder->bridge, &new_crtc_state->mode,
444 				&new_crtc_state->adjusted_mode);
445 		if (!ret) {
446 			DRM_DEBUG_ATOMIC("Bridge fixup failed\n");
447 			return -EINVAL;
448 		}
449 
450 		if (funcs && funcs->atomic_check) {
451 			ret = funcs->atomic_check(encoder, new_crtc_state,
452 						  new_conn_state);
453 			if (ret) {
454 				DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] check failed\n",
455 						 encoder->base.id, encoder->name);
456 				return ret;
457 			}
458 		} else if (funcs && funcs->mode_fixup) {
459 			ret = funcs->mode_fixup(encoder, &new_crtc_state->mode,
460 						&new_crtc_state->adjusted_mode);
461 			if (!ret) {
462 				DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] fixup failed\n",
463 						 encoder->base.id, encoder->name);
464 				return -EINVAL;
465 			}
466 		}
467 	}
468 
469 	for_each_new_crtc_in_state(state, crtc, new_crtc_state, i) {
470 		const struct drm_crtc_helper_funcs *funcs;
471 
472 		if (!new_crtc_state->enable)
473 			continue;
474 
475 		if (!new_crtc_state->mode_changed &&
476 		    !new_crtc_state->connectors_changed)
477 			continue;
478 
479 		funcs = crtc->helper_private;
480 		if (!funcs->mode_fixup)
481 			continue;
482 
483 		ret = funcs->mode_fixup(crtc, &new_crtc_state->mode,
484 					&new_crtc_state->adjusted_mode);
485 		if (!ret) {
486 			DRM_DEBUG_ATOMIC("[CRTC:%d:%s] fixup failed\n",
487 					 crtc->base.id, crtc->name);
488 			return -EINVAL;
489 		}
490 	}
491 
492 	return 0;
493 }
494 
495 static enum drm_mode_status mode_valid_path(struct drm_connector *connector,
496 					    struct drm_encoder *encoder,
497 					    struct drm_crtc *crtc,
498 					    struct drm_display_mode *mode)
499 {
500 	enum drm_mode_status ret;
501 
502 	ret = drm_encoder_mode_valid(encoder, mode);
503 	if (ret != MODE_OK) {
504 		DRM_DEBUG_ATOMIC("[ENCODER:%d:%s] mode_valid() failed\n",
505 				encoder->base.id, encoder->name);
506 		return ret;
507 	}
508 
509 	ret = drm_bridge_mode_valid(encoder->bridge, mode);
510 	if (ret != MODE_OK) {
511 		DRM_DEBUG_ATOMIC("[BRIDGE] mode_valid() failed\n");
512 		return ret;
513 	}
514 
515 	ret = drm_crtc_mode_valid(crtc, mode);
516 	if (ret != MODE_OK) {
517 		DRM_DEBUG_ATOMIC("[CRTC:%d:%s] mode_valid() failed\n",
518 				crtc->base.id, crtc->name);
519 		return ret;
520 	}
521 
522 	return ret;
523 }
524 
525 static int
526 mode_valid(struct drm_atomic_state *state)
527 {
528 	struct drm_connector_state *conn_state;
529 	struct drm_connector *connector;
530 	int i;
531 
532 	for_each_new_connector_in_state(state, connector, conn_state, i) {
533 		struct drm_encoder *encoder = conn_state->best_encoder;
534 		struct drm_crtc *crtc = conn_state->crtc;
535 		struct drm_crtc_state *crtc_state;
536 		enum drm_mode_status mode_status;
537 		struct drm_display_mode *mode;
538 
539 		if (!crtc || !encoder)
540 			continue;
541 
542 		crtc_state = drm_atomic_get_new_crtc_state(state, crtc);
543 		if (!crtc_state)
544 			continue;
545 		if (!crtc_state->mode_changed && !crtc_state->connectors_changed)
546 			continue;
547 
548 		mode = &crtc_state->mode;
549 
550 		mode_status = mode_valid_path(connector, encoder, crtc, mode);
551 		if (mode_status != MODE_OK)
552 			return -EINVAL;
553 	}
554 
555 	return 0;
556 }
557 
558 /**
559  * drm_atomic_helper_check_modeset - validate state object for modeset changes
560  * @dev: DRM device
561  * @state: the driver state object
562  *
563  * Check the state object to see if the requested state is physically possible.
564  * This does all the crtc and connector related computations for an atomic
565  * update and adds any additional connectors needed for full modesets. It calls
566  * the various per-object callbacks in the follow order:
567  *
568  * 1. &drm_connector_helper_funcs.atomic_best_encoder for determining the new encoder.
569  * 2. &drm_connector_helper_funcs.atomic_check to validate the connector state.
570  * 3. If it's determined a modeset is needed then all connectors on the affected crtc
571  *    crtc are added and &drm_connector_helper_funcs.atomic_check is run on them.
572  * 4. &drm_encoder_helper_funcs.mode_valid, &drm_bridge_funcs.mode_valid and
573  *    &drm_crtc_helper_funcs.mode_valid are called on the affected components.
574  * 5. &drm_bridge_funcs.mode_fixup is called on all encoder bridges.
575  * 6. &drm_encoder_helper_funcs.atomic_check is called to validate any encoder state.
576  *    This function is only called when the encoder will be part of a configured crtc,
577  *    it must not be used for implementing connector property validation.
578  *    If this function is NULL, &drm_atomic_encoder_helper_funcs.mode_fixup is called
579  *    instead.
580  * 7. &drm_crtc_helper_funcs.mode_fixup is called last, to fix up the mode with crtc constraints.
581  *
582  * &drm_crtc_state.mode_changed is set when the input mode is changed.
583  * &drm_crtc_state.connectors_changed is set when a connector is added or
584  * removed from the crtc.  &drm_crtc_state.active_changed is set when
585  * &drm_crtc_state.active changes, which is used for DPMS.
586  * See also: drm_atomic_crtc_needs_modeset()
587  *
588  * IMPORTANT:
589  *
590  * Drivers which set &drm_crtc_state.mode_changed (e.g. in their
591  * &drm_plane_helper_funcs.atomic_check hooks if a plane update can't be done
592  * without a full modeset) _must_ call this function afterwards after that
593  * change. It is permitted to call this function multiple times for the same
594  * update, e.g. when the &drm_crtc_helper_funcs.atomic_check functions depend
595  * upon the adjusted dotclock for fifo space allocation and watermark
596  * computation.
597  *
598  * RETURNS:
599  * Zero for success or -errno
600  */
601 int
602 drm_atomic_helper_check_modeset(struct drm_device *dev,
603 				struct drm_atomic_state *state)
604 {
605 	struct drm_crtc *crtc;
606 	struct drm_crtc_state *old_crtc_state, *new_crtc_state;
607 	struct drm_connector *connector;
608 	struct drm_connector_state *old_connector_state, *new_connector_state;
609 	int i, ret;
610 	unsigned connectors_mask = 0;
611 
612 	for_each_oldnew_crtc_in_state(state, crtc, old_crtc_state, new_crtc_state, i) {
613 		bool has_connectors =
614 			!!new_crtc_state->connector_mask;
615 
616 		WARN_ON(!drm_modeset_is_locked(&crtc->mutex));
617 
618 		if (!drm_mode_equal(&old_crtc_state->mode, &new_crtc_state->mode)) {
619 			DRM_DEBUG_ATOMIC("[CRTC:%d:%s] mode changed\n",
620 					 crtc->base.id, crtc->name);
621 			new_crtc_state->mode_changed = true;
622 		}
623 
624 		if (old_crtc_state->enable != new_crtc_state->enable) {
625 			DRM_DEBUG_ATOMIC("[CRTC:%d:%s] enable changed\n",
626 					 crtc->base.id, crtc->name);
627 
628 			/*
629 			 * For clarity this assignment is done here, but
630 			 * enable == 0 is only true when there are no
631 			 * connectors and a NULL mode.
632 			 *
633 			 * The other way around is true as well. enable != 0
634 			 * iff connectors are attached and a mode is set.
635 			 */
636 			new_crtc_state->mode_changed = true;
637 			new_crtc_state->connectors_changed = true;
638 		}
639 
640 		if (old_crtc_state->active != new_crtc_state->active) {
641 			DRM_DEBUG_ATOMIC("[CRTC:%d:%s] active changed\n",
642 					 crtc->base.id, crtc->name);
643 			new_crtc_state->active_changed = true;
644 		}
645 
646 		if (new_crtc_state->enable != has_connectors) {
647 			DRM_DEBUG_ATOMIC("[CRTC:%d:%s] enabled/connectors mismatch\n",
648 					 crtc->base.id, crtc->name);
649 
650 			return -EINVAL;
651 		}
652 	}
653 
654 	ret = handle_conflicting_encoders(state, false);
655 	if (ret)
656 		return ret;
657 
658 	for_each_oldnew_connector_in_state(state, connector, old_connector_state, new_connector_state, i) {
659 		const struct drm_connector_helper_funcs *funcs = connector->helper_private;
660 
661 		WARN_ON(!drm_modeset_is_locked(&dev->mode_config.connection_mutex));
662 
663 		/*
664 		 * This only sets crtc->connectors_changed for routing changes,
665 		 * drivers must set crtc->connectors_changed themselves when
666 		 * connector properties need to be updated.
667 		 */
668 		ret = update_connector_routing(state, connector,
669 					       old_connector_state,
670 					       new_connector_state);
671 		if (ret)
672 			return ret;
673 		if (old_connector_state->crtc) {
674 			new_crtc_state = drm_atomic_get_new_crtc_state(state,
675 								       old_connector_state->crtc);
676 			if (old_connector_state->link_status !=
677 			    new_connector_state->link_status)
678 				new_crtc_state->connectors_changed = true;
679 
680 			if (old_connector_state->max_requested_bpc !=
681 			    new_connector_state->max_requested_bpc)
682 				new_crtc_state->connectors_changed = true;
683 		}
684 
685 		if (funcs->atomic_check)
686 			ret = funcs->atomic_check(connector, new_connector_state);
687 		if (ret)
688 			return ret;
689 
690 		connectors_mask |= BIT(i);
691 	}
692 
693 	/*
694 	 * After all the routing has been prepared we need to add in any
695 	 * connector which is itself unchanged, but whose crtc changes its
696 	 * configuration. This must be done before calling mode_fixup in case a
697 	 * crtc only changed its mode but has the same set of connectors.
698 	 */
699 	for_each_oldnew_crtc_in_state(state, crtc, old_crtc_state, new_crtc_state, i) {
700 		if (!drm_atomic_crtc_needs_modeset(new_crtc_state))
701 			continue;
702 
703 		DRM_DEBUG_ATOMIC("[CRTC:%d:%s] needs all connectors, enable: %c, active: %c\n",
704 				 crtc->base.id, crtc->name,
705 				 new_crtc_state->enable ? 'y' : 'n',
706 				 new_crtc_state->active ? 'y' : 'n');
707 
708 		ret = drm_atomic_add_affected_connectors(state, crtc);
709 		if (ret != 0)
710 			return ret;
711 
712 		ret = drm_atomic_add_affected_planes(state, crtc);
713 		if (ret != 0)
714 			return ret;
715 	}
716 
717 	/*
718 	 * Iterate over all connectors again, to make sure atomic_check()
719 	 * has been called on them when a modeset is forced.
720 	 */
721 	for_each_oldnew_connector_in_state(state, connector, old_connector_state, new_connector_state, i) {
722 		const struct drm_connector_helper_funcs *funcs = connector->helper_private;
723 
724 		if (connectors_mask & BIT(i))
725 			continue;
726 
727 		if (funcs->atomic_check)
728 			ret = funcs->atomic_check(connector, new_connector_state);
729 		if (ret)
730 			return ret;
731 	}
732 
733 	ret = mode_valid(state);
734 	if (ret)
735 		return ret;
736 
737 	return mode_fixup(state);
738 }
739 EXPORT_SYMBOL(drm_atomic_helper_check_modeset);
740 
741 /**
742  * drm_atomic_helper_check_plane_state() - Check plane state for validity
743  * @plane_state: plane state to check
744  * @crtc_state: crtc state to check
745  * @min_scale: minimum @src:@dest scaling factor in 16.16 fixed point
746  * @max_scale: maximum @src:@dest scaling factor in 16.16 fixed point
747  * @can_position: is it legal to position the plane such that it
748  *                doesn't cover the entire crtc?  This will generally
749  *                only be false for primary planes.
750  * @can_update_disabled: can the plane be updated while the crtc
751  *                       is disabled?
752  *
753  * Checks that a desired plane update is valid, and updates various
754  * bits of derived state (clipped coordinates etc.). Drivers that provide
755  * their own plane handling rather than helper-provided implementations may
756  * still wish to call this function to avoid duplication of error checking
757  * code.
758  *
759  * RETURNS:
760  * Zero if update appears valid, error code on failure
761  */
762 int drm_atomic_helper_check_plane_state(struct drm_plane_state *plane_state,
763 					const struct drm_crtc_state *crtc_state,
764 					int min_scale,
765 					int max_scale,
766 					bool can_position,
767 					bool can_update_disabled)
768 {
769 	struct drm_framebuffer *fb = plane_state->fb;
770 	struct drm_rect *src = &plane_state->src;
771 	struct drm_rect *dst = &plane_state->dst;
772 	unsigned int rotation = plane_state->rotation;
773 	struct drm_rect clip = {};
774 	int hscale, vscale;
775 
776 	WARN_ON(plane_state->crtc && plane_state->crtc != crtc_state->crtc);
777 
778 	*src = drm_plane_state_src(plane_state);
779 	*dst = drm_plane_state_dest(plane_state);
780 
781 	if (!fb) {
782 		plane_state->visible = false;
783 		return 0;
784 	}
785 
786 	/* crtc should only be NULL when disabling (i.e., !fb) */
787 	if (WARN_ON(!plane_state->crtc)) {
788 		plane_state->visible = false;
789 		return 0;
790 	}
791 
792 	if (!crtc_state->enable && !can_update_disabled) {
793 		DRM_DEBUG_KMS("Cannot update plane of a disabled CRTC.\n");
794 		return -EINVAL;
795 	}
796 
797 	drm_rect_rotate(src, fb->width << 16, fb->height << 16, rotation);
798 
799 	/* Check scaling */
800 	hscale = drm_rect_calc_hscale(src, dst, min_scale, max_scale);
801 	vscale = drm_rect_calc_vscale(src, dst, min_scale, max_scale);
802 	if (hscale < 0 || vscale < 0) {
803 		DRM_DEBUG_KMS("Invalid scaling of plane\n");
804 		drm_rect_debug_print("src: ", &plane_state->src, true);
805 		drm_rect_debug_print("dst: ", &plane_state->dst, false);
806 		return -ERANGE;
807 	}
808 
809 	if (crtc_state->enable)
810 		drm_mode_get_hv_timing(&crtc_state->mode, &clip.x2, &clip.y2);
811 
812 	plane_state->visible = drm_rect_clip_scaled(src, dst, &clip);
813 
814 	drm_rect_rotate_inv(src, fb->width << 16, fb->height << 16, rotation);
815 
816 	if (!plane_state->visible)
817 		/*
818 		 * Plane isn't visible; some drivers can handle this
819 		 * so we just return success here.  Drivers that can't
820 		 * (including those that use the primary plane helper's
821 		 * update function) will return an error from their
822 		 * update_plane handler.
823 		 */
824 		return 0;
825 
826 	if (!can_position && !drm_rect_equals(dst, &clip)) {
827 		DRM_DEBUG_KMS("Plane must cover entire CRTC\n");
828 		drm_rect_debug_print("dst: ", dst, false);
829 		drm_rect_debug_print("clip: ", &clip, false);
830 		return -EINVAL;
831 	}
832 
833 	return 0;
834 }
835 EXPORT_SYMBOL(drm_atomic_helper_check_plane_state);
836 
837 /**
838  * drm_atomic_helper_check_planes - validate state object for planes changes
839  * @dev: DRM device
840  * @state: the driver state object
841  *
842  * Check the state object to see if the requested state is physically possible.
843  * This does all the plane update related checks using by calling into the
844  * &drm_crtc_helper_funcs.atomic_check and &drm_plane_helper_funcs.atomic_check
845  * hooks provided by the driver.
846  *
847  * It also sets &drm_crtc_state.planes_changed to indicate that a crtc has
848  * updated planes.
849  *
850  * RETURNS:
851  * Zero for success or -errno
852  */
853 int
854 drm_atomic_helper_check_planes(struct drm_device *dev,
855 			       struct drm_atomic_state *state)
856 {
857 	struct drm_crtc *crtc;
858 	struct drm_crtc_state *new_crtc_state;
859 	struct drm_plane *plane;
860 	struct drm_plane_state *new_plane_state, *old_plane_state;
861 	int i, ret = 0;
862 
863 	for_each_oldnew_plane_in_state(state, plane, old_plane_state, new_plane_state, i) {
864 		const struct drm_plane_helper_funcs *funcs;
865 
866 		WARN_ON(!drm_modeset_is_locked(&plane->mutex));
867 
868 		funcs = plane->helper_private;
869 
870 		drm_atomic_helper_plane_changed(state, old_plane_state, new_plane_state, plane);
871 
872 		drm_atomic_helper_check_plane_damage(state, new_plane_state);
873 
874 		if (!funcs || !funcs->atomic_check)
875 			continue;
876 
877 		ret = funcs->atomic_check(plane, new_plane_state);
878 		if (ret) {
879 			DRM_DEBUG_ATOMIC("[PLANE:%d:%s] atomic driver check failed\n",
880 					 plane->base.id, plane->name);
881 			return ret;
882 		}
883 	}
884 
885 	for_each_new_crtc_in_state(state, crtc, new_crtc_state, i) {
886 		const struct drm_crtc_helper_funcs *funcs;
887 
888 		funcs = crtc->helper_private;
889 
890 		if (!funcs || !funcs->atomic_check)
891 			continue;
892 
893 		ret = funcs->atomic_check(crtc, new_crtc_state);
894 		if (ret) {
895 			DRM_DEBUG_ATOMIC("[CRTC:%d:%s] atomic driver check failed\n",
896 					 crtc->base.id, crtc->name);
897 			return ret;
898 		}
899 	}
900 
901 	return ret;
902 }
903 EXPORT_SYMBOL(drm_atomic_helper_check_planes);
904 
905 /**
906  * drm_atomic_helper_check - validate state object
907  * @dev: DRM device
908  * @state: the driver state object
909  *
910  * Check the state object to see if the requested state is physically possible.
911  * Only crtcs and planes have check callbacks, so for any additional (global)
912  * checking that a driver needs it can simply wrap that around this function.
913  * Drivers without such needs can directly use this as their
914  * &drm_mode_config_funcs.atomic_check callback.
915  *
916  * This just wraps the two parts of the state checking for planes and modeset
917  * state in the default order: First it calls drm_atomic_helper_check_modeset()
918  * and then drm_atomic_helper_check_planes(). The assumption is that the
919  * @drm_plane_helper_funcs.atomic_check and @drm_crtc_helper_funcs.atomic_check
920  * functions depend upon an updated adjusted_mode.clock to e.g. properly compute
921  * watermarks.
922  *
923  * Note that zpos normalization will add all enable planes to the state which
924  * might not desired for some drivers.
925  * For example enable/disable of a cursor plane which have fixed zpos value
926  * would trigger all other enabled planes to be forced to the state change.
927  *
928  * RETURNS:
929  * Zero for success or -errno
930  */
931 int drm_atomic_helper_check(struct drm_device *dev,
932 			    struct drm_atomic_state *state)
933 {
934 	int ret;
935 
936 	ret = drm_atomic_helper_check_modeset(dev, state);
937 	if (ret)
938 		return ret;
939 
940 	if (dev->mode_config.normalize_zpos) {
941 		ret = drm_atomic_normalize_zpos(dev, state);
942 		if (ret)
943 			return ret;
944 	}
945 
946 	ret = drm_atomic_helper_check_planes(dev, state);
947 	if (ret)
948 		return ret;
949 
950 	if (state->legacy_cursor_update)
951 		state->async_update = !drm_atomic_helper_async_check(dev, state);
952 
953 	return ret;
954 }
955 EXPORT_SYMBOL(drm_atomic_helper_check);
956 
957 static void
958 disable_outputs(struct drm_device *dev, struct drm_atomic_state *old_state)
959 {
960 	struct drm_connector *connector;
961 	struct drm_connector_state *old_conn_state, *new_conn_state;
962 	struct drm_crtc *crtc;
963 	struct drm_crtc_state *old_crtc_state, *new_crtc_state;
964 	int i;
965 
966 	for_each_oldnew_connector_in_state(old_state, connector, old_conn_state, new_conn_state, i) {
967 		const struct drm_encoder_helper_funcs *funcs;
968 		struct drm_encoder *encoder;
969 
970 		/* Shut down everything that's in the changeset and currently
971 		 * still on. So need to check the old, saved state. */
972 		if (!old_conn_state->crtc)
973 			continue;
974 
975 		old_crtc_state = drm_atomic_get_old_crtc_state(old_state, old_conn_state->crtc);
976 
977 		if (!old_crtc_state->active ||
978 		    !drm_atomic_crtc_needs_modeset(old_conn_state->crtc->state))
979 			continue;
980 
981 		encoder = old_conn_state->best_encoder;
982 
983 		/* We shouldn't get this far if we didn't previously have
984 		 * an encoder.. but WARN_ON() rather than explode.
985 		 */
986 		if (WARN_ON(!encoder))
987 			continue;
988 
989 		funcs = encoder->helper_private;
990 
991 		DRM_DEBUG_ATOMIC("disabling [ENCODER:%d:%s]\n",
992 				 encoder->base.id, encoder->name);
993 
994 		/*
995 		 * Each encoder has at most one connector (since we always steal
996 		 * it away), so we won't call disable hooks twice.
997 		 */
998 		drm_bridge_disable(encoder->bridge);
999 
1000 		/* Right function depends upon target state. */
1001 		if (funcs) {
1002 			if (new_conn_state->crtc && funcs->prepare)
1003 				funcs->prepare(encoder);
1004 			else if (funcs->disable)
1005 				funcs->disable(encoder);
1006 			else if (funcs->dpms)
1007 				funcs->dpms(encoder, DRM_MODE_DPMS_OFF);
1008 		}
1009 
1010 		drm_bridge_post_disable(encoder->bridge);
1011 	}
1012 
1013 	for_each_oldnew_crtc_in_state(old_state, crtc, old_crtc_state, new_crtc_state, i) {
1014 		const struct drm_crtc_helper_funcs *funcs;
1015 		int ret;
1016 
1017 		/* Shut down everything that needs a full modeset. */
1018 		if (!drm_atomic_crtc_needs_modeset(new_crtc_state))
1019 			continue;
1020 
1021 		if (!old_crtc_state->active)
1022 			continue;
1023 
1024 		funcs = crtc->helper_private;
1025 
1026 		DRM_DEBUG_ATOMIC("disabling [CRTC:%d:%s]\n",
1027 				 crtc->base.id, crtc->name);
1028 
1029 
1030 		/* Right function depends upon target state. */
1031 		if (new_crtc_state->enable && funcs->prepare)
1032 			funcs->prepare(crtc);
1033 		else if (funcs->atomic_disable)
1034 			funcs->atomic_disable(crtc, old_crtc_state);
1035 		else if (funcs->disable)
1036 			funcs->disable(crtc);
1037 		else
1038 			funcs->dpms(crtc, DRM_MODE_DPMS_OFF);
1039 
1040 		if (!(dev->irq_enabled && dev->num_crtcs))
1041 			continue;
1042 
1043 		ret = drm_crtc_vblank_get(crtc);
1044 		WARN_ONCE(ret != -EINVAL, "driver forgot to call drm_crtc_vblank_off()\n");
1045 		if (ret == 0)
1046 			drm_crtc_vblank_put(crtc);
1047 	}
1048 }
1049 
1050 /**
1051  * drm_atomic_helper_update_legacy_modeset_state - update legacy modeset state
1052  * @dev: DRM device
1053  * @old_state: atomic state object with old state structures
1054  *
1055  * This function updates all the various legacy modeset state pointers in
1056  * connectors, encoders and crtcs. It also updates the timestamping constants
1057  * used for precise vblank timestamps by calling
1058  * drm_calc_timestamping_constants().
1059  *
1060  * Drivers can use this for building their own atomic commit if they don't have
1061  * a pure helper-based modeset implementation.
1062  *
1063  * Since these updates are not synchronized with lockings, only code paths
1064  * called from &drm_mode_config_helper_funcs.atomic_commit_tail can look at the
1065  * legacy state filled out by this helper. Defacto this means this helper and
1066  * the legacy state pointers are only really useful for transitioning an
1067  * existing driver to the atomic world.
1068  */
1069 void
1070 drm_atomic_helper_update_legacy_modeset_state(struct drm_device *dev,
1071 					      struct drm_atomic_state *old_state)
1072 {
1073 	struct drm_connector *connector;
1074 	struct drm_connector_state *old_conn_state, *new_conn_state;
1075 	struct drm_crtc *crtc;
1076 	struct drm_crtc_state *new_crtc_state;
1077 	int i;
1078 
1079 	/* clear out existing links and update dpms */
1080 	for_each_oldnew_connector_in_state(old_state, connector, old_conn_state, new_conn_state, i) {
1081 		if (connector->encoder) {
1082 			WARN_ON(!connector->encoder->crtc);
1083 
1084 			connector->encoder->crtc = NULL;
1085 			connector->encoder = NULL;
1086 		}
1087 
1088 		crtc = new_conn_state->crtc;
1089 		if ((!crtc && old_conn_state->crtc) ||
1090 		    (crtc && drm_atomic_crtc_needs_modeset(crtc->state))) {
1091 			int mode = DRM_MODE_DPMS_OFF;
1092 
1093 			if (crtc && crtc->state->active)
1094 				mode = DRM_MODE_DPMS_ON;
1095 
1096 			connector->dpms = mode;
1097 		}
1098 	}
1099 
1100 	/* set new links */
1101 	for_each_new_connector_in_state(old_state, connector, new_conn_state, i) {
1102 		if (!new_conn_state->crtc)
1103 			continue;
1104 
1105 		if (WARN_ON(!new_conn_state->best_encoder))
1106 			continue;
1107 
1108 		connector->encoder = new_conn_state->best_encoder;
1109 		connector->encoder->crtc = new_conn_state->crtc;
1110 	}
1111 
1112 	/* set legacy state in the crtc structure */
1113 	for_each_new_crtc_in_state(old_state, crtc, new_crtc_state, i) {
1114 		struct drm_plane *primary = crtc->primary;
1115 		struct drm_plane_state *new_plane_state;
1116 
1117 		crtc->mode = new_crtc_state->mode;
1118 		crtc->enabled = new_crtc_state->enable;
1119 
1120 		new_plane_state =
1121 			drm_atomic_get_new_plane_state(old_state, primary);
1122 
1123 		if (new_plane_state && new_plane_state->crtc == crtc) {
1124 			crtc->x = new_plane_state->src_x >> 16;
1125 			crtc->y = new_plane_state->src_y >> 16;
1126 		}
1127 
1128 		if (new_crtc_state->enable)
1129 			drm_calc_timestamping_constants(crtc,
1130 							&new_crtc_state->adjusted_mode);
1131 	}
1132 }
1133 EXPORT_SYMBOL(drm_atomic_helper_update_legacy_modeset_state);
1134 
1135 static void
1136 crtc_set_mode(struct drm_device *dev, struct drm_atomic_state *old_state)
1137 {
1138 	struct drm_crtc *crtc;
1139 	struct drm_crtc_state *new_crtc_state;
1140 	struct drm_connector *connector;
1141 	struct drm_connector_state *new_conn_state;
1142 	int i;
1143 
1144 	for_each_new_crtc_in_state(old_state, crtc, new_crtc_state, i) {
1145 		const struct drm_crtc_helper_funcs *funcs;
1146 
1147 		if (!new_crtc_state->mode_changed)
1148 			continue;
1149 
1150 		funcs = crtc->helper_private;
1151 
1152 		if (new_crtc_state->enable && funcs->mode_set_nofb) {
1153 			DRM_DEBUG_ATOMIC("modeset on [CRTC:%d:%s]\n",
1154 					 crtc->base.id, crtc->name);
1155 
1156 			funcs->mode_set_nofb(crtc);
1157 		}
1158 	}
1159 
1160 	for_each_new_connector_in_state(old_state, connector, new_conn_state, i) {
1161 		const struct drm_encoder_helper_funcs *funcs;
1162 		struct drm_encoder *encoder;
1163 		struct drm_display_mode *mode, *adjusted_mode;
1164 
1165 		if (!new_conn_state->best_encoder)
1166 			continue;
1167 
1168 		encoder = new_conn_state->best_encoder;
1169 		funcs = encoder->helper_private;
1170 		new_crtc_state = new_conn_state->crtc->state;
1171 		mode = &new_crtc_state->mode;
1172 		adjusted_mode = &new_crtc_state->adjusted_mode;
1173 
1174 		if (!new_crtc_state->mode_changed)
1175 			continue;
1176 
1177 		DRM_DEBUG_ATOMIC("modeset on [ENCODER:%d:%s]\n",
1178 				 encoder->base.id, encoder->name);
1179 
1180 		/*
1181 		 * Each encoder has at most one connector (since we always steal
1182 		 * it away), so we won't call mode_set hooks twice.
1183 		 */
1184 		if (funcs && funcs->atomic_mode_set) {
1185 			funcs->atomic_mode_set(encoder, new_crtc_state,
1186 					       new_conn_state);
1187 		} else if (funcs && funcs->mode_set) {
1188 			funcs->mode_set(encoder, mode, adjusted_mode);
1189 		}
1190 
1191 		drm_bridge_mode_set(encoder->bridge, mode, adjusted_mode);
1192 	}
1193 }
1194 
1195 /**
1196  * drm_atomic_helper_commit_modeset_disables - modeset commit to disable outputs
1197  * @dev: DRM device
1198  * @old_state: atomic state object with old state structures
1199  *
1200  * This function shuts down all the outputs that need to be shut down and
1201  * prepares them (if required) with the new mode.
1202  *
1203  * For compatibility with legacy crtc helpers this should be called before
1204  * drm_atomic_helper_commit_planes(), which is what the default commit function
1205  * does. But drivers with different needs can group the modeset commits together
1206  * and do the plane commits at the end. This is useful for drivers doing runtime
1207  * PM since planes updates then only happen when the CRTC is actually enabled.
1208  */
1209 void drm_atomic_helper_commit_modeset_disables(struct drm_device *dev,
1210 					       struct drm_atomic_state *old_state)
1211 {
1212 	disable_outputs(dev, old_state);
1213 
1214 	drm_atomic_helper_update_legacy_modeset_state(dev, old_state);
1215 
1216 	crtc_set_mode(dev, old_state);
1217 }
1218 EXPORT_SYMBOL(drm_atomic_helper_commit_modeset_disables);
1219 
1220 static void drm_atomic_helper_commit_writebacks(struct drm_device *dev,
1221 						struct drm_atomic_state *old_state)
1222 {
1223 	struct drm_connector *connector;
1224 	struct drm_connector_state *new_conn_state;
1225 	int i;
1226 
1227 	for_each_new_connector_in_state(old_state, connector, new_conn_state, i) {
1228 		const struct drm_connector_helper_funcs *funcs;
1229 
1230 		funcs = connector->helper_private;
1231 		if (!funcs->atomic_commit)
1232 			continue;
1233 
1234 		if (new_conn_state->writeback_job && new_conn_state->writeback_job->fb) {
1235 			WARN_ON(connector->connector_type != DRM_MODE_CONNECTOR_WRITEBACK);
1236 			funcs->atomic_commit(connector, new_conn_state);
1237 		}
1238 	}
1239 }
1240 
1241 /**
1242  * drm_atomic_helper_commit_modeset_enables - modeset commit to enable outputs
1243  * @dev: DRM device
1244  * @old_state: atomic state object with old state structures
1245  *
1246  * This function enables all the outputs with the new configuration which had to
1247  * be turned off for the update.
1248  *
1249  * For compatibility with legacy crtc helpers this should be called after
1250  * drm_atomic_helper_commit_planes(), which is what the default commit function
1251  * does. But drivers with different needs can group the modeset commits together
1252  * and do the plane commits at the end. This is useful for drivers doing runtime
1253  * PM since planes updates then only happen when the CRTC is actually enabled.
1254  */
1255 void drm_atomic_helper_commit_modeset_enables(struct drm_device *dev,
1256 					      struct drm_atomic_state *old_state)
1257 {
1258 	struct drm_crtc *crtc;
1259 	struct drm_crtc_state *old_crtc_state;
1260 	struct drm_crtc_state *new_crtc_state;
1261 	struct drm_connector *connector;
1262 	struct drm_connector_state *new_conn_state;
1263 	int i;
1264 
1265 	for_each_oldnew_crtc_in_state(old_state, crtc, old_crtc_state, new_crtc_state, i) {
1266 		const struct drm_crtc_helper_funcs *funcs;
1267 
1268 		/* Need to filter out CRTCs where only planes change. */
1269 		if (!drm_atomic_crtc_needs_modeset(new_crtc_state))
1270 			continue;
1271 
1272 		if (!new_crtc_state->active)
1273 			continue;
1274 
1275 		funcs = crtc->helper_private;
1276 
1277 		if (new_crtc_state->enable) {
1278 			DRM_DEBUG_ATOMIC("enabling [CRTC:%d:%s]\n",
1279 					 crtc->base.id, crtc->name);
1280 
1281 			if (funcs->atomic_enable)
1282 				funcs->atomic_enable(crtc, old_crtc_state);
1283 			else
1284 				funcs->commit(crtc);
1285 		}
1286 	}
1287 
1288 	for_each_new_connector_in_state(old_state, connector, new_conn_state, i) {
1289 		const struct drm_encoder_helper_funcs *funcs;
1290 		struct drm_encoder *encoder;
1291 
1292 		if (!new_conn_state->best_encoder)
1293 			continue;
1294 
1295 		if (!new_conn_state->crtc->state->active ||
1296 		    !drm_atomic_crtc_needs_modeset(new_conn_state->crtc->state))
1297 			continue;
1298 
1299 		encoder = new_conn_state->best_encoder;
1300 		funcs = encoder->helper_private;
1301 
1302 		DRM_DEBUG_ATOMIC("enabling [ENCODER:%d:%s]\n",
1303 				 encoder->base.id, encoder->name);
1304 
1305 		/*
1306 		 * Each encoder has at most one connector (since we always steal
1307 		 * it away), so we won't call enable hooks twice.
1308 		 */
1309 		drm_bridge_pre_enable(encoder->bridge);
1310 
1311 		if (funcs) {
1312 			if (funcs->enable)
1313 				funcs->enable(encoder);
1314 			else if (funcs->commit)
1315 				funcs->commit(encoder);
1316 		}
1317 
1318 		drm_bridge_enable(encoder->bridge);
1319 	}
1320 
1321 	drm_atomic_helper_commit_writebacks(dev, old_state);
1322 }
1323 EXPORT_SYMBOL(drm_atomic_helper_commit_modeset_enables);
1324 
1325 /**
1326  * drm_atomic_helper_wait_for_fences - wait for fences stashed in plane state
1327  * @dev: DRM device
1328  * @state: atomic state object with old state structures
1329  * @pre_swap: If true, do an interruptible wait, and @state is the new state.
1330  * 	Otherwise @state is the old state.
1331  *
1332  * For implicit sync, driver should fish the exclusive fence out from the
1333  * incoming fb's and stash it in the drm_plane_state.  This is called after
1334  * drm_atomic_helper_swap_state() so it uses the current plane state (and
1335  * just uses the atomic state to find the changed planes)
1336  *
1337  * Note that @pre_swap is needed since the point where we block for fences moves
1338  * around depending upon whether an atomic commit is blocking or
1339  * non-blocking. For non-blocking commit all waiting needs to happen after
1340  * drm_atomic_helper_swap_state() is called, but for blocking commits we want
1341  * to wait **before** we do anything that can't be easily rolled back. That is
1342  * before we call drm_atomic_helper_swap_state().
1343  *
1344  * Returns zero if success or < 0 if dma_fence_wait() fails.
1345  */
1346 int drm_atomic_helper_wait_for_fences(struct drm_device *dev,
1347 				      struct drm_atomic_state *state,
1348 				      bool pre_swap)
1349 {
1350 	struct drm_plane *plane;
1351 	struct drm_plane_state *new_plane_state;
1352 	int i, ret;
1353 
1354 	for_each_new_plane_in_state(state, plane, new_plane_state, i) {
1355 		if (!new_plane_state->fence)
1356 			continue;
1357 
1358 		WARN_ON(!new_plane_state->fb);
1359 
1360 		/*
1361 		 * If waiting for fences pre-swap (ie: nonblock), userspace can
1362 		 * still interrupt the operation. Instead of blocking until the
1363 		 * timer expires, make the wait interruptible.
1364 		 */
1365 		ret = dma_fence_wait(new_plane_state->fence, pre_swap);
1366 		if (ret)
1367 			return ret;
1368 
1369 		dma_fence_put(new_plane_state->fence);
1370 		new_plane_state->fence = NULL;
1371 	}
1372 
1373 	return 0;
1374 }
1375 EXPORT_SYMBOL(drm_atomic_helper_wait_for_fences);
1376 
1377 /**
1378  * drm_atomic_helper_wait_for_vblanks - wait for vblank on crtcs
1379  * @dev: DRM device
1380  * @old_state: atomic state object with old state structures
1381  *
1382  * Helper to, after atomic commit, wait for vblanks on all effected
1383  * crtcs (ie. before cleaning up old framebuffers using
1384  * drm_atomic_helper_cleanup_planes()). It will only wait on CRTCs where the
1385  * framebuffers have actually changed to optimize for the legacy cursor and
1386  * plane update use-case.
1387  *
1388  * Drivers using the nonblocking commit tracking support initialized by calling
1389  * drm_atomic_helper_setup_commit() should look at
1390  * drm_atomic_helper_wait_for_flip_done() as an alternative.
1391  */
1392 void
1393 drm_atomic_helper_wait_for_vblanks(struct drm_device *dev,
1394 		struct drm_atomic_state *old_state)
1395 {
1396 	struct drm_crtc *crtc;
1397 	struct drm_crtc_state *old_crtc_state, *new_crtc_state;
1398 	int i, ret;
1399 	unsigned crtc_mask = 0;
1400 
1401 	 /*
1402 	  * Legacy cursor ioctls are completely unsynced, and userspace
1403 	  * relies on that (by doing tons of cursor updates).
1404 	  */
1405 	if (old_state->legacy_cursor_update)
1406 		return;
1407 
1408 	for_each_oldnew_crtc_in_state(old_state, crtc, old_crtc_state, new_crtc_state, i) {
1409 		if (!new_crtc_state->active)
1410 			continue;
1411 
1412 		ret = drm_crtc_vblank_get(crtc);
1413 		if (ret != 0)
1414 			continue;
1415 
1416 		crtc_mask |= drm_crtc_mask(crtc);
1417 		old_state->crtcs[i].last_vblank_count = drm_crtc_vblank_count(crtc);
1418 	}
1419 
1420 	for_each_old_crtc_in_state(old_state, crtc, old_crtc_state, i) {
1421 		if (!(crtc_mask & drm_crtc_mask(crtc)))
1422 			continue;
1423 
1424 		ret = wait_event_timeout(dev->vblank[i].queue,
1425 				old_state->crtcs[i].last_vblank_count !=
1426 					drm_crtc_vblank_count(crtc),
1427 				msecs_to_jiffies(50));
1428 
1429 		WARN(!ret, "[CRTC:%d:%s] vblank wait timed out\n",
1430 		     crtc->base.id, crtc->name);
1431 
1432 		drm_crtc_vblank_put(crtc);
1433 	}
1434 }
1435 EXPORT_SYMBOL(drm_atomic_helper_wait_for_vblanks);
1436 
1437 /**
1438  * drm_atomic_helper_wait_for_flip_done - wait for all page flips to be done
1439  * @dev: DRM device
1440  * @old_state: atomic state object with old state structures
1441  *
1442  * Helper to, after atomic commit, wait for page flips on all effected
1443  * crtcs (ie. before cleaning up old framebuffers using
1444  * drm_atomic_helper_cleanup_planes()). Compared to
1445  * drm_atomic_helper_wait_for_vblanks() this waits for the completion of on all
1446  * CRTCs, assuming that cursors-only updates are signalling their completion
1447  * immediately (or using a different path).
1448  *
1449  * This requires that drivers use the nonblocking commit tracking support
1450  * initialized using drm_atomic_helper_setup_commit().
1451  */
1452 void drm_atomic_helper_wait_for_flip_done(struct drm_device *dev,
1453 					  struct drm_atomic_state *old_state)
1454 {
1455 	struct drm_crtc *crtc;
1456 	int i;
1457 
1458 	for (i = 0; i < dev->mode_config.num_crtc; i++) {
1459 		struct drm_crtc_commit *commit = old_state->crtcs[i].commit;
1460 		int ret;
1461 
1462 		crtc = old_state->crtcs[i].ptr;
1463 
1464 		if (!crtc || !commit)
1465 			continue;
1466 
1467 		ret = wait_for_completion_timeout(&commit->flip_done, 10 * HZ);
1468 		if (ret == 0)
1469 			DRM_ERROR("[CRTC:%d:%s] flip_done timed out\n",
1470 				  crtc->base.id, crtc->name);
1471 	}
1472 
1473 	if (old_state->fake_commit)
1474 		complete_all(&old_state->fake_commit->flip_done);
1475 }
1476 EXPORT_SYMBOL(drm_atomic_helper_wait_for_flip_done);
1477 
1478 /**
1479  * drm_atomic_helper_commit_tail - commit atomic update to hardware
1480  * @old_state: atomic state object with old state structures
1481  *
1482  * This is the default implementation for the
1483  * &drm_mode_config_helper_funcs.atomic_commit_tail hook, for drivers
1484  * that do not support runtime_pm or do not need the CRTC to be
1485  * enabled to perform a commit. Otherwise, see
1486  * drm_atomic_helper_commit_tail_rpm().
1487  *
1488  * Note that the default ordering of how the various stages are called is to
1489  * match the legacy modeset helper library closest.
1490  */
1491 void drm_atomic_helper_commit_tail(struct drm_atomic_state *old_state)
1492 {
1493 	struct drm_device *dev = old_state->dev;
1494 
1495 	drm_atomic_helper_commit_modeset_disables(dev, old_state);
1496 
1497 	drm_atomic_helper_commit_planes(dev, old_state, 0);
1498 
1499 	drm_atomic_helper_commit_modeset_enables(dev, old_state);
1500 
1501 	drm_atomic_helper_fake_vblank(old_state);
1502 
1503 	drm_atomic_helper_commit_hw_done(old_state);
1504 
1505 	drm_atomic_helper_wait_for_vblanks(dev, old_state);
1506 
1507 	drm_atomic_helper_cleanup_planes(dev, old_state);
1508 }
1509 EXPORT_SYMBOL(drm_atomic_helper_commit_tail);
1510 
1511 /**
1512  * drm_atomic_helper_commit_tail_rpm - commit atomic update to hardware
1513  * @old_state: new modeset state to be committed
1514  *
1515  * This is an alternative implementation for the
1516  * &drm_mode_config_helper_funcs.atomic_commit_tail hook, for drivers
1517  * that support runtime_pm or need the CRTC to be enabled to perform a
1518  * commit. Otherwise, one should use the default implementation
1519  * drm_atomic_helper_commit_tail().
1520  */
1521 void drm_atomic_helper_commit_tail_rpm(struct drm_atomic_state *old_state)
1522 {
1523 	struct drm_device *dev = old_state->dev;
1524 
1525 	drm_atomic_helper_commit_modeset_disables(dev, old_state);
1526 
1527 	drm_atomic_helper_commit_modeset_enables(dev, old_state);
1528 
1529 	drm_atomic_helper_commit_planes(dev, old_state,
1530 					DRM_PLANE_COMMIT_ACTIVE_ONLY);
1531 
1532 	drm_atomic_helper_fake_vblank(old_state);
1533 
1534 	drm_atomic_helper_commit_hw_done(old_state);
1535 
1536 	drm_atomic_helper_wait_for_vblanks(dev, old_state);
1537 
1538 	drm_atomic_helper_cleanup_planes(dev, old_state);
1539 }
1540 EXPORT_SYMBOL(drm_atomic_helper_commit_tail_rpm);
1541 
1542 static void commit_tail(struct drm_atomic_state *old_state)
1543 {
1544 	struct drm_device *dev = old_state->dev;
1545 	const struct drm_mode_config_helper_funcs *funcs;
1546 
1547 	funcs = dev->mode_config.helper_private;
1548 
1549 	drm_atomic_helper_wait_for_fences(dev, old_state, false);
1550 
1551 	drm_atomic_helper_wait_for_dependencies(old_state);
1552 
1553 	if (funcs && funcs->atomic_commit_tail)
1554 		funcs->atomic_commit_tail(old_state);
1555 	else
1556 		drm_atomic_helper_commit_tail(old_state);
1557 
1558 	drm_atomic_helper_commit_cleanup_done(old_state);
1559 
1560 	drm_atomic_state_put(old_state);
1561 }
1562 
1563 static void commit_work(struct work_struct *work)
1564 {
1565 	struct drm_atomic_state *state = container_of(work,
1566 						      struct drm_atomic_state,
1567 						      commit_work);
1568 	commit_tail(state);
1569 }
1570 
1571 /**
1572  * drm_atomic_helper_async_check - check if state can be commited asynchronously
1573  * @dev: DRM device
1574  * @state: the driver state object
1575  *
1576  * This helper will check if it is possible to commit the state asynchronously.
1577  * Async commits are not supposed to swap the states like normal sync commits
1578  * but just do in-place changes on the current state.
1579  *
1580  * It will return 0 if the commit can happen in an asynchronous fashion or error
1581  * if not. Note that error just mean it can't be commited asynchronously, if it
1582  * fails the commit should be treated like a normal synchronous commit.
1583  */
1584 int drm_atomic_helper_async_check(struct drm_device *dev,
1585 				   struct drm_atomic_state *state)
1586 {
1587 	struct drm_crtc *crtc;
1588 	struct drm_crtc_state *crtc_state;
1589 	struct drm_plane *plane = NULL;
1590 	struct drm_plane_state *old_plane_state = NULL;
1591 	struct drm_plane_state *new_plane_state = NULL;
1592 	const struct drm_plane_helper_funcs *funcs;
1593 	int i, n_planes = 0;
1594 
1595 	for_each_new_crtc_in_state(state, crtc, crtc_state, i) {
1596 		if (drm_atomic_crtc_needs_modeset(crtc_state))
1597 			return -EINVAL;
1598 	}
1599 
1600 	for_each_oldnew_plane_in_state(state, plane, old_plane_state, new_plane_state, i)
1601 		n_planes++;
1602 
1603 	/* FIXME: we support only single plane updates for now */
1604 	if (n_planes != 1)
1605 		return -EINVAL;
1606 
1607 	if (!new_plane_state->crtc ||
1608 	    old_plane_state->crtc != new_plane_state->crtc)
1609 		return -EINVAL;
1610 
1611 	/*
1612 	 * FIXME: Since prepare_fb and cleanup_fb are always called on
1613 	 * the new_plane_state for async updates we need to block framebuffer
1614 	 * changes. This prevents use of a fb that's been cleaned up and
1615 	 * double cleanups from occuring.
1616 	 */
1617 	if (old_plane_state->fb != new_plane_state->fb)
1618 		return -EINVAL;
1619 
1620 	funcs = plane->helper_private;
1621 	if (!funcs->atomic_async_update)
1622 		return -EINVAL;
1623 
1624 	if (new_plane_state->fence)
1625 		return -EINVAL;
1626 
1627 	/*
1628 	 * Don't do an async update if there is an outstanding commit modifying
1629 	 * the plane.  This prevents our async update's changes from getting
1630 	 * overridden by a previous synchronous update's state.
1631 	 */
1632 	if (old_plane_state->commit &&
1633 	    !try_wait_for_completion(&old_plane_state->commit->hw_done))
1634 		return -EBUSY;
1635 
1636 	return funcs->atomic_async_check(plane, new_plane_state);
1637 }
1638 EXPORT_SYMBOL(drm_atomic_helper_async_check);
1639 
1640 /**
1641  * drm_atomic_helper_async_commit - commit state asynchronously
1642  * @dev: DRM device
1643  * @state: the driver state object
1644  *
1645  * This function commits a state asynchronously, i.e., not vblank
1646  * synchronized. It should be used on a state only when
1647  * drm_atomic_async_check() succeeds. Async commits are not supposed to swap
1648  * the states like normal sync commits, but just do in-place changes on the
1649  * current state.
1650  */
1651 void drm_atomic_helper_async_commit(struct drm_device *dev,
1652 				    struct drm_atomic_state *state)
1653 {
1654 	struct drm_plane *plane;
1655 	struct drm_plane_state *plane_state;
1656 	const struct drm_plane_helper_funcs *funcs;
1657 	int i;
1658 
1659 	for_each_new_plane_in_state(state, plane, plane_state, i) {
1660 		funcs = plane->helper_private;
1661 		funcs->atomic_async_update(plane, plane_state);
1662 
1663 		/*
1664 		 * ->atomic_async_update() is supposed to update the
1665 		 * plane->state in-place, make sure at least common
1666 		 * properties have been properly updated.
1667 		 */
1668 		WARN_ON_ONCE(plane->state->fb != plane_state->fb);
1669 		WARN_ON_ONCE(plane->state->crtc_x != plane_state->crtc_x);
1670 		WARN_ON_ONCE(plane->state->crtc_y != plane_state->crtc_y);
1671 		WARN_ON_ONCE(plane->state->src_x != plane_state->src_x);
1672 		WARN_ON_ONCE(plane->state->src_y != plane_state->src_y);
1673 	}
1674 }
1675 EXPORT_SYMBOL(drm_atomic_helper_async_commit);
1676 
1677 /**
1678  * drm_atomic_helper_commit - commit validated state object
1679  * @dev: DRM device
1680  * @state: the driver state object
1681  * @nonblock: whether nonblocking behavior is requested.
1682  *
1683  * This function commits a with drm_atomic_helper_check() pre-validated state
1684  * object. This can still fail when e.g. the framebuffer reservation fails. This
1685  * function implements nonblocking commits, using
1686  * drm_atomic_helper_setup_commit() and related functions.
1687  *
1688  * Committing the actual hardware state is done through the
1689  * &drm_mode_config_helper_funcs.atomic_commit_tail callback, or its default
1690  * implementation drm_atomic_helper_commit_tail().
1691  *
1692  * RETURNS:
1693  * Zero for success or -errno.
1694  */
1695 int drm_atomic_helper_commit(struct drm_device *dev,
1696 			     struct drm_atomic_state *state,
1697 			     bool nonblock)
1698 {
1699 	int ret;
1700 
1701 	if (state->async_update) {
1702 		ret = drm_atomic_helper_prepare_planes(dev, state);
1703 		if (ret)
1704 			return ret;
1705 
1706 		drm_atomic_helper_async_commit(dev, state);
1707 		drm_atomic_helper_cleanup_planes(dev, state);
1708 
1709 		return 0;
1710 	}
1711 
1712 	ret = drm_atomic_helper_setup_commit(state, nonblock);
1713 	if (ret)
1714 		return ret;
1715 
1716 	INIT_WORK(&state->commit_work, commit_work);
1717 
1718 	ret = drm_atomic_helper_prepare_planes(dev, state);
1719 	if (ret)
1720 		return ret;
1721 
1722 	if (!nonblock) {
1723 		ret = drm_atomic_helper_wait_for_fences(dev, state, true);
1724 		if (ret)
1725 			goto err;
1726 	}
1727 
1728 	/*
1729 	 * This is the point of no return - everything below never fails except
1730 	 * when the hw goes bonghits. Which means we can commit the new state on
1731 	 * the software side now.
1732 	 */
1733 
1734 	ret = drm_atomic_helper_swap_state(state, true);
1735 	if (ret)
1736 		goto err;
1737 
1738 	/*
1739 	 * Everything below can be run asynchronously without the need to grab
1740 	 * any modeset locks at all under one condition: It must be guaranteed
1741 	 * that the asynchronous work has either been cancelled (if the driver
1742 	 * supports it, which at least requires that the framebuffers get
1743 	 * cleaned up with drm_atomic_helper_cleanup_planes()) or completed
1744 	 * before the new state gets committed on the software side with
1745 	 * drm_atomic_helper_swap_state().
1746 	 *
1747 	 * This scheme allows new atomic state updates to be prepared and
1748 	 * checked in parallel to the asynchronous completion of the previous
1749 	 * update. Which is important since compositors need to figure out the
1750 	 * composition of the next frame right after having submitted the
1751 	 * current layout.
1752 	 *
1753 	 * NOTE: Commit work has multiple phases, first hardware commit, then
1754 	 * cleanup. We want them to overlap, hence need system_unbound_wq to
1755 	 * make sure work items don't artifically stall on each another.
1756 	 */
1757 
1758 	drm_atomic_state_get(state);
1759 	if (nonblock)
1760 		queue_work(system_unbound_wq, &state->commit_work);
1761 	else
1762 		commit_tail(state);
1763 
1764 	return 0;
1765 
1766 err:
1767 	drm_atomic_helper_cleanup_planes(dev, state);
1768 	return ret;
1769 }
1770 EXPORT_SYMBOL(drm_atomic_helper_commit);
1771 
1772 /**
1773  * DOC: implementing nonblocking commit
1774  *
1775  * Nonblocking atomic commits have to be implemented in the following sequence:
1776  *
1777  * 1. Run drm_atomic_helper_prepare_planes() first. This is the only function
1778  * which commit needs to call which can fail, so we want to run it first and
1779  * synchronously.
1780  *
1781  * 2. Synchronize with any outstanding nonblocking commit worker threads which
1782  * might be affected the new state update. This can be done by either cancelling
1783  * or flushing the work items, depending upon whether the driver can deal with
1784  * cancelled updates. Note that it is important to ensure that the framebuffer
1785  * cleanup is still done when cancelling.
1786  *
1787  * Asynchronous workers need to have sufficient parallelism to be able to run
1788  * different atomic commits on different CRTCs in parallel. The simplest way to
1789  * achive this is by running them on the &system_unbound_wq work queue. Note
1790  * that drivers are not required to split up atomic commits and run an
1791  * individual commit in parallel - userspace is supposed to do that if it cares.
1792  * But it might be beneficial to do that for modesets, since those necessarily
1793  * must be done as one global operation, and enabling or disabling a CRTC can
1794  * take a long time. But even that is not required.
1795  *
1796  * 3. The software state is updated synchronously with
1797  * drm_atomic_helper_swap_state(). Doing this under the protection of all modeset
1798  * locks means concurrent callers never see inconsistent state. And doing this
1799  * while it's guaranteed that no relevant nonblocking worker runs means that
1800  * nonblocking workers do not need grab any locks. Actually they must not grab
1801  * locks, for otherwise the work flushing will deadlock.
1802  *
1803  * 4. Schedule a work item to do all subsequent steps, using the split-out
1804  * commit helpers: a) pre-plane commit b) plane commit c) post-plane commit and
1805  * then cleaning up the framebuffers after the old framebuffer is no longer
1806  * being displayed.
1807  *
1808  * The above scheme is implemented in the atomic helper libraries in
1809  * drm_atomic_helper_commit() using a bunch of helper functions. See
1810  * drm_atomic_helper_setup_commit() for a starting point.
1811  */
1812 
1813 static int stall_checks(struct drm_crtc *crtc, bool nonblock)
1814 {
1815 	struct drm_crtc_commit *commit, *stall_commit = NULL;
1816 	bool completed = true;
1817 	int i;
1818 	long ret = 0;
1819 
1820 	spin_lock(&crtc->commit_lock);
1821 	i = 0;
1822 	list_for_each_entry(commit, &crtc->commit_list, commit_entry) {
1823 		if (i == 0) {
1824 			completed = try_wait_for_completion(&commit->flip_done);
1825 			/* Userspace is not allowed to get ahead of the previous
1826 			 * commit with nonblocking ones. */
1827 			if (!completed && nonblock) {
1828 				spin_unlock(&crtc->commit_lock);
1829 				return -EBUSY;
1830 			}
1831 		} else if (i == 1) {
1832 			stall_commit = drm_crtc_commit_get(commit);
1833 			break;
1834 		}
1835 
1836 		i++;
1837 	}
1838 	spin_unlock(&crtc->commit_lock);
1839 
1840 	if (!stall_commit)
1841 		return 0;
1842 
1843 	/* We don't want to let commits get ahead of cleanup work too much,
1844 	 * stalling on 2nd previous commit means triple-buffer won't ever stall.
1845 	 */
1846 	ret = wait_for_completion_interruptible_timeout(&stall_commit->cleanup_done,
1847 							10*HZ);
1848 	if (ret == 0)
1849 		DRM_ERROR("[CRTC:%d:%s] cleanup_done timed out\n",
1850 			  crtc->base.id, crtc->name);
1851 
1852 	drm_crtc_commit_put(stall_commit);
1853 
1854 	return ret < 0 ? ret : 0;
1855 }
1856 
1857 static void release_crtc_commit(struct completion *completion)
1858 {
1859 	struct drm_crtc_commit *commit = container_of(completion,
1860 						      typeof(*commit),
1861 						      flip_done);
1862 
1863 	drm_crtc_commit_put(commit);
1864 }
1865 
1866 static void init_commit(struct drm_crtc_commit *commit, struct drm_crtc *crtc)
1867 {
1868 	init_completion(&commit->flip_done);
1869 	init_completion(&commit->hw_done);
1870 	init_completion(&commit->cleanup_done);
1871 	INIT_LIST_HEAD(&commit->commit_entry);
1872 	kref_init(&commit->ref);
1873 	commit->crtc = crtc;
1874 }
1875 
1876 static struct drm_crtc_commit *
1877 crtc_or_fake_commit(struct drm_atomic_state *state, struct drm_crtc *crtc)
1878 {
1879 	if (crtc) {
1880 		struct drm_crtc_state *new_crtc_state;
1881 
1882 		new_crtc_state = drm_atomic_get_new_crtc_state(state, crtc);
1883 
1884 		return new_crtc_state->commit;
1885 	}
1886 
1887 	if (!state->fake_commit) {
1888 		state->fake_commit = kzalloc(sizeof(*state->fake_commit), GFP_KERNEL);
1889 		if (!state->fake_commit)
1890 			return NULL;
1891 
1892 		init_commit(state->fake_commit, NULL);
1893 	}
1894 
1895 	return state->fake_commit;
1896 }
1897 
1898 /**
1899  * drm_atomic_helper_setup_commit - setup possibly nonblocking commit
1900  * @state: new modeset state to be committed
1901  * @nonblock: whether nonblocking behavior is requested.
1902  *
1903  * This function prepares @state to be used by the atomic helper's support for
1904  * nonblocking commits. Drivers using the nonblocking commit infrastructure
1905  * should always call this function from their
1906  * &drm_mode_config_funcs.atomic_commit hook.
1907  *
1908  * To be able to use this support drivers need to use a few more helper
1909  * functions. drm_atomic_helper_wait_for_dependencies() must be called before
1910  * actually committing the hardware state, and for nonblocking commits this call
1911  * must be placed in the async worker. See also drm_atomic_helper_swap_state()
1912  * and its stall parameter, for when a driver's commit hooks look at the
1913  * &drm_crtc.state, &drm_plane.state or &drm_connector.state pointer directly.
1914  *
1915  * Completion of the hardware commit step must be signalled using
1916  * drm_atomic_helper_commit_hw_done(). After this step the driver is not allowed
1917  * to read or change any permanent software or hardware modeset state. The only
1918  * exception is state protected by other means than &drm_modeset_lock locks.
1919  * Only the free standing @state with pointers to the old state structures can
1920  * be inspected, e.g. to clean up old buffers using
1921  * drm_atomic_helper_cleanup_planes().
1922  *
1923  * At the very end, before cleaning up @state drivers must call
1924  * drm_atomic_helper_commit_cleanup_done().
1925  *
1926  * This is all implemented by in drm_atomic_helper_commit(), giving drivers a
1927  * complete and easy-to-use default implementation of the atomic_commit() hook.
1928  *
1929  * The tracking of asynchronously executed and still pending commits is done
1930  * using the core structure &drm_crtc_commit.
1931  *
1932  * By default there's no need to clean up resources allocated by this function
1933  * explicitly: drm_atomic_state_default_clear() will take care of that
1934  * automatically.
1935  *
1936  * Returns:
1937  *
1938  * 0 on success. -EBUSY when userspace schedules nonblocking commits too fast,
1939  * -ENOMEM on allocation failures and -EINTR when a signal is pending.
1940  */
1941 int drm_atomic_helper_setup_commit(struct drm_atomic_state *state,
1942 				   bool nonblock)
1943 {
1944 	struct drm_crtc *crtc;
1945 	struct drm_crtc_state *old_crtc_state, *new_crtc_state;
1946 	struct drm_connector *conn;
1947 	struct drm_connector_state *old_conn_state, *new_conn_state;
1948 	struct drm_plane *plane;
1949 	struct drm_plane_state *old_plane_state, *new_plane_state;
1950 	struct drm_crtc_commit *commit;
1951 	int i, ret;
1952 
1953 	for_each_oldnew_crtc_in_state(state, crtc, old_crtc_state, new_crtc_state, i) {
1954 		commit = kzalloc(sizeof(*commit), GFP_KERNEL);
1955 		if (!commit)
1956 			return -ENOMEM;
1957 
1958 		init_commit(commit, crtc);
1959 
1960 		new_crtc_state->commit = commit;
1961 
1962 		ret = stall_checks(crtc, nonblock);
1963 		if (ret)
1964 			return ret;
1965 
1966 		/* Drivers only send out events when at least either current or
1967 		 * new CRTC state is active. Complete right away if everything
1968 		 * stays off. */
1969 		if (!old_crtc_state->active && !new_crtc_state->active) {
1970 			complete_all(&commit->flip_done);
1971 			continue;
1972 		}
1973 
1974 		/* Legacy cursor updates are fully unsynced. */
1975 		if (state->legacy_cursor_update) {
1976 			complete_all(&commit->flip_done);
1977 			continue;
1978 		}
1979 
1980 		if (!new_crtc_state->event) {
1981 			commit->event = kzalloc(sizeof(*commit->event),
1982 						GFP_KERNEL);
1983 			if (!commit->event)
1984 				return -ENOMEM;
1985 
1986 			new_crtc_state->event = commit->event;
1987 		}
1988 
1989 		new_crtc_state->event->base.completion = &commit->flip_done;
1990 		new_crtc_state->event->base.completion_release = release_crtc_commit;
1991 		drm_crtc_commit_get(commit);
1992 
1993 		commit->abort_completion = true;
1994 
1995 		state->crtcs[i].commit = commit;
1996 		drm_crtc_commit_get(commit);
1997 	}
1998 
1999 	for_each_oldnew_connector_in_state(state, conn, old_conn_state, new_conn_state, i) {
2000 		/* Userspace is not allowed to get ahead of the previous
2001 		 * commit with nonblocking ones. */
2002 		if (nonblock && old_conn_state->commit &&
2003 		    !try_wait_for_completion(&old_conn_state->commit->flip_done))
2004 			return -EBUSY;
2005 
2006 		/* Always track connectors explicitly for e.g. link retraining. */
2007 		commit = crtc_or_fake_commit(state, new_conn_state->crtc ?: old_conn_state->crtc);
2008 		if (!commit)
2009 			return -ENOMEM;
2010 
2011 		new_conn_state->commit = drm_crtc_commit_get(commit);
2012 	}
2013 
2014 	for_each_oldnew_plane_in_state(state, plane, old_plane_state, new_plane_state, i) {
2015 		/* Userspace is not allowed to get ahead of the previous
2016 		 * commit with nonblocking ones. */
2017 		if (nonblock && old_plane_state->commit &&
2018 		    !try_wait_for_completion(&old_plane_state->commit->flip_done))
2019 			return -EBUSY;
2020 
2021 		/* Always track planes explicitly for async pageflip support. */
2022 		commit = crtc_or_fake_commit(state, new_plane_state->crtc ?: old_plane_state->crtc);
2023 		if (!commit)
2024 			return -ENOMEM;
2025 
2026 		new_plane_state->commit = drm_crtc_commit_get(commit);
2027 	}
2028 
2029 	return 0;
2030 }
2031 EXPORT_SYMBOL(drm_atomic_helper_setup_commit);
2032 
2033 /**
2034  * drm_atomic_helper_wait_for_dependencies - wait for required preceeding commits
2035  * @old_state: atomic state object with old state structures
2036  *
2037  * This function waits for all preceeding commits that touch the same CRTC as
2038  * @old_state to both be committed to the hardware (as signalled by
2039  * drm_atomic_helper_commit_hw_done) and executed by the hardware (as signalled
2040  * by calling drm_crtc_send_vblank_event() on the &drm_crtc_state.event).
2041  *
2042  * This is part of the atomic helper support for nonblocking commits, see
2043  * drm_atomic_helper_setup_commit() for an overview.
2044  */
2045 void drm_atomic_helper_wait_for_dependencies(struct drm_atomic_state *old_state)
2046 {
2047 	struct drm_crtc *crtc;
2048 	struct drm_crtc_state *old_crtc_state;
2049 	struct drm_plane *plane;
2050 	struct drm_plane_state *old_plane_state;
2051 	struct drm_connector *conn;
2052 	struct drm_connector_state *old_conn_state;
2053 	struct drm_crtc_commit *commit;
2054 	int i;
2055 	long ret;
2056 
2057 	for_each_old_crtc_in_state(old_state, crtc, old_crtc_state, i) {
2058 		commit = old_crtc_state->commit;
2059 
2060 		if (!commit)
2061 			continue;
2062 
2063 		ret = wait_for_completion_timeout(&commit->hw_done,
2064 						  10*HZ);
2065 		if (ret == 0)
2066 			DRM_ERROR("[CRTC:%d:%s] hw_done timed out\n",
2067 				  crtc->base.id, crtc->name);
2068 
2069 		/* Currently no support for overwriting flips, hence
2070 		 * stall for previous one to execute completely. */
2071 		ret = wait_for_completion_timeout(&commit->flip_done,
2072 						  10*HZ);
2073 		if (ret == 0)
2074 			DRM_ERROR("[CRTC:%d:%s] flip_done timed out\n",
2075 				  crtc->base.id, crtc->name);
2076 	}
2077 
2078 	for_each_old_connector_in_state(old_state, conn, old_conn_state, i) {
2079 		commit = old_conn_state->commit;
2080 
2081 		if (!commit)
2082 			continue;
2083 
2084 		ret = wait_for_completion_timeout(&commit->hw_done,
2085 						  10*HZ);
2086 		if (ret == 0)
2087 			DRM_ERROR("[CONNECTOR:%d:%s] hw_done timed out\n",
2088 				  conn->base.id, conn->name);
2089 
2090 		/* Currently no support for overwriting flips, hence
2091 		 * stall for previous one to execute completely. */
2092 		ret = wait_for_completion_timeout(&commit->flip_done,
2093 						  10*HZ);
2094 		if (ret == 0)
2095 			DRM_ERROR("[CONNECTOR:%d:%s] flip_done timed out\n",
2096 				  conn->base.id, conn->name);
2097 	}
2098 
2099 	for_each_old_plane_in_state(old_state, plane, old_plane_state, i) {
2100 		commit = old_plane_state->commit;
2101 
2102 		if (!commit)
2103 			continue;
2104 
2105 		ret = wait_for_completion_timeout(&commit->hw_done,
2106 						  10*HZ);
2107 		if (ret == 0)
2108 			DRM_ERROR("[PLANE:%d:%s] hw_done timed out\n",
2109 				  plane->base.id, plane->name);
2110 
2111 		/* Currently no support for overwriting flips, hence
2112 		 * stall for previous one to execute completely. */
2113 		ret = wait_for_completion_timeout(&commit->flip_done,
2114 						  10*HZ);
2115 		if (ret == 0)
2116 			DRM_ERROR("[PLANE:%d:%s] flip_done timed out\n",
2117 				  plane->base.id, plane->name);
2118 	}
2119 }
2120 EXPORT_SYMBOL(drm_atomic_helper_wait_for_dependencies);
2121 
2122 /**
2123  * drm_atomic_helper_fake_vblank - fake VBLANK events if needed
2124  * @old_state: atomic state object with old state structures
2125  *
2126  * This function walks all CRTCs and fake VBLANK events on those with
2127  * &drm_crtc_state.no_vblank set to true and &drm_crtc_state.event != NULL.
2128  * The primary use of this function is writeback connectors working in oneshot
2129  * mode and faking VBLANK events. In this case they only fake the VBLANK event
2130  * when a job is queued, and any change to the pipeline that does not touch the
2131  * connector is leading to timeouts when calling
2132  * drm_atomic_helper_wait_for_vblanks() or
2133  * drm_atomic_helper_wait_for_flip_done().
2134  *
2135  * This is part of the atomic helper support for nonblocking commits, see
2136  * drm_atomic_helper_setup_commit() for an overview.
2137  */
2138 void drm_atomic_helper_fake_vblank(struct drm_atomic_state *old_state)
2139 {
2140 	struct drm_crtc_state *new_crtc_state;
2141 	struct drm_crtc *crtc;
2142 	int i;
2143 
2144 	for_each_new_crtc_in_state(old_state, crtc, new_crtc_state, i) {
2145 		unsigned long flags;
2146 
2147 		if (!new_crtc_state->no_vblank)
2148 			continue;
2149 
2150 		spin_lock_irqsave(&old_state->dev->event_lock, flags);
2151 		if (new_crtc_state->event) {
2152 			drm_crtc_send_vblank_event(crtc,
2153 						   new_crtc_state->event);
2154 			new_crtc_state->event = NULL;
2155 		}
2156 		spin_unlock_irqrestore(&old_state->dev->event_lock, flags);
2157 	}
2158 }
2159 EXPORT_SYMBOL(drm_atomic_helper_fake_vblank);
2160 
2161 /**
2162  * drm_atomic_helper_commit_hw_done - setup possible nonblocking commit
2163  * @old_state: atomic state object with old state structures
2164  *
2165  * This function is used to signal completion of the hardware commit step. After
2166  * this step the driver is not allowed to read or change any permanent software
2167  * or hardware modeset state. The only exception is state protected by other
2168  * means than &drm_modeset_lock locks.
2169  *
2170  * Drivers should try to postpone any expensive or delayed cleanup work after
2171  * this function is called.
2172  *
2173  * This is part of the atomic helper support for nonblocking commits, see
2174  * drm_atomic_helper_setup_commit() for an overview.
2175  */
2176 void drm_atomic_helper_commit_hw_done(struct drm_atomic_state *old_state)
2177 {
2178 	struct drm_crtc *crtc;
2179 	struct drm_crtc_state *old_crtc_state, *new_crtc_state;
2180 	struct drm_crtc_commit *commit;
2181 	int i;
2182 
2183 	for_each_oldnew_crtc_in_state(old_state, crtc, old_crtc_state, new_crtc_state, i) {
2184 		commit = new_crtc_state->commit;
2185 		if (!commit)
2186 			continue;
2187 
2188 		/*
2189 		 * copy new_crtc_state->commit to old_crtc_state->commit,
2190 		 * it's unsafe to touch new_crtc_state after hw_done,
2191 		 * but we still need to do so in cleanup_done().
2192 		 */
2193 		if (old_crtc_state->commit)
2194 			drm_crtc_commit_put(old_crtc_state->commit);
2195 
2196 		old_crtc_state->commit = drm_crtc_commit_get(commit);
2197 
2198 		/* backend must have consumed any event by now */
2199 		WARN_ON(new_crtc_state->event);
2200 		complete_all(&commit->hw_done);
2201 	}
2202 
2203 	if (old_state->fake_commit) {
2204 		complete_all(&old_state->fake_commit->hw_done);
2205 		complete_all(&old_state->fake_commit->flip_done);
2206 	}
2207 }
2208 EXPORT_SYMBOL(drm_atomic_helper_commit_hw_done);
2209 
2210 /**
2211  * drm_atomic_helper_commit_cleanup_done - signal completion of commit
2212  * @old_state: atomic state object with old state structures
2213  *
2214  * This signals completion of the atomic update @old_state, including any
2215  * cleanup work. If used, it must be called right before calling
2216  * drm_atomic_state_put().
2217  *
2218  * This is part of the atomic helper support for nonblocking commits, see
2219  * drm_atomic_helper_setup_commit() for an overview.
2220  */
2221 void drm_atomic_helper_commit_cleanup_done(struct drm_atomic_state *old_state)
2222 {
2223 	struct drm_crtc *crtc;
2224 	struct drm_crtc_state *old_crtc_state;
2225 	struct drm_crtc_commit *commit;
2226 	int i;
2227 
2228 	for_each_old_crtc_in_state(old_state, crtc, old_crtc_state, i) {
2229 		commit = old_crtc_state->commit;
2230 		if (WARN_ON(!commit))
2231 			continue;
2232 
2233 		complete_all(&commit->cleanup_done);
2234 		WARN_ON(!try_wait_for_completion(&commit->hw_done));
2235 
2236 		spin_lock(&crtc->commit_lock);
2237 		list_del(&commit->commit_entry);
2238 		spin_unlock(&crtc->commit_lock);
2239 	}
2240 
2241 	if (old_state->fake_commit) {
2242 		complete_all(&old_state->fake_commit->cleanup_done);
2243 		WARN_ON(!try_wait_for_completion(&old_state->fake_commit->hw_done));
2244 	}
2245 }
2246 EXPORT_SYMBOL(drm_atomic_helper_commit_cleanup_done);
2247 
2248 /**
2249  * drm_atomic_helper_prepare_planes - prepare plane resources before commit
2250  * @dev: DRM device
2251  * @state: atomic state object with new state structures
2252  *
2253  * This function prepares plane state, specifically framebuffers, for the new
2254  * configuration, by calling &drm_plane_helper_funcs.prepare_fb. If any failure
2255  * is encountered this function will call &drm_plane_helper_funcs.cleanup_fb on
2256  * any already successfully prepared framebuffer.
2257  *
2258  * Returns:
2259  * 0 on success, negative error code on failure.
2260  */
2261 int drm_atomic_helper_prepare_planes(struct drm_device *dev,
2262 				     struct drm_atomic_state *state)
2263 {
2264 	struct drm_plane *plane;
2265 	struct drm_plane_state *new_plane_state;
2266 	int ret, i, j;
2267 
2268 	for_each_new_plane_in_state(state, plane, new_plane_state, i) {
2269 		const struct drm_plane_helper_funcs *funcs;
2270 
2271 		funcs = plane->helper_private;
2272 
2273 		if (funcs->prepare_fb) {
2274 			ret = funcs->prepare_fb(plane, new_plane_state);
2275 			if (ret)
2276 				goto fail;
2277 		}
2278 	}
2279 
2280 	return 0;
2281 
2282 fail:
2283 	for_each_new_plane_in_state(state, plane, new_plane_state, j) {
2284 		const struct drm_plane_helper_funcs *funcs;
2285 
2286 		if (j >= i)
2287 			continue;
2288 
2289 		funcs = plane->helper_private;
2290 
2291 		if (funcs->cleanup_fb)
2292 			funcs->cleanup_fb(plane, new_plane_state);
2293 	}
2294 
2295 	return ret;
2296 }
2297 EXPORT_SYMBOL(drm_atomic_helper_prepare_planes);
2298 
2299 static bool plane_crtc_active(const struct drm_plane_state *state)
2300 {
2301 	return state->crtc && state->crtc->state->active;
2302 }
2303 
2304 /**
2305  * drm_atomic_helper_commit_planes - commit plane state
2306  * @dev: DRM device
2307  * @old_state: atomic state object with old state structures
2308  * @flags: flags for committing plane state
2309  *
2310  * This function commits the new plane state using the plane and atomic helper
2311  * functions for planes and crtcs. It assumes that the atomic state has already
2312  * been pushed into the relevant object state pointers, since this step can no
2313  * longer fail.
2314  *
2315  * It still requires the global state object @old_state to know which planes and
2316  * crtcs need to be updated though.
2317  *
2318  * Note that this function does all plane updates across all CRTCs in one step.
2319  * If the hardware can't support this approach look at
2320  * drm_atomic_helper_commit_planes_on_crtc() instead.
2321  *
2322  * Plane parameters can be updated by applications while the associated CRTC is
2323  * disabled. The DRM/KMS core will store the parameters in the plane state,
2324  * which will be available to the driver when the CRTC is turned on. As a result
2325  * most drivers don't need to be immediately notified of plane updates for a
2326  * disabled CRTC.
2327  *
2328  * Unless otherwise needed, drivers are advised to set the ACTIVE_ONLY flag in
2329  * @flags in order not to receive plane update notifications related to a
2330  * disabled CRTC. This avoids the need to manually ignore plane updates in
2331  * driver code when the driver and/or hardware can't or just don't need to deal
2332  * with updates on disabled CRTCs, for example when supporting runtime PM.
2333  *
2334  * Drivers may set the NO_DISABLE_AFTER_MODESET flag in @flags if the relevant
2335  * display controllers require to disable a CRTC's planes when the CRTC is
2336  * disabled. This function would skip the &drm_plane_helper_funcs.atomic_disable
2337  * call for a plane if the CRTC of the old plane state needs a modesetting
2338  * operation. Of course, the drivers need to disable the planes in their CRTC
2339  * disable callbacks since no one else would do that.
2340  *
2341  * The drm_atomic_helper_commit() default implementation doesn't set the
2342  * ACTIVE_ONLY flag to most closely match the behaviour of the legacy helpers.
2343  * This should not be copied blindly by drivers.
2344  */
2345 void drm_atomic_helper_commit_planes(struct drm_device *dev,
2346 				     struct drm_atomic_state *old_state,
2347 				     uint32_t flags)
2348 {
2349 	struct drm_crtc *crtc;
2350 	struct drm_crtc_state *old_crtc_state, *new_crtc_state;
2351 	struct drm_plane *plane;
2352 	struct drm_plane_state *old_plane_state, *new_plane_state;
2353 	int i;
2354 	bool active_only = flags & DRM_PLANE_COMMIT_ACTIVE_ONLY;
2355 	bool no_disable = flags & DRM_PLANE_COMMIT_NO_DISABLE_AFTER_MODESET;
2356 
2357 	for_each_oldnew_crtc_in_state(old_state, crtc, old_crtc_state, new_crtc_state, i) {
2358 		const struct drm_crtc_helper_funcs *funcs;
2359 
2360 		funcs = crtc->helper_private;
2361 
2362 		if (!funcs || !funcs->atomic_begin)
2363 			continue;
2364 
2365 		if (active_only && !new_crtc_state->active)
2366 			continue;
2367 
2368 		funcs->atomic_begin(crtc, old_crtc_state);
2369 	}
2370 
2371 	for_each_oldnew_plane_in_state(old_state, plane, old_plane_state, new_plane_state, i) {
2372 		const struct drm_plane_helper_funcs *funcs;
2373 		bool disabling;
2374 
2375 		funcs = plane->helper_private;
2376 
2377 		if (!funcs)
2378 			continue;
2379 
2380 		disabling = drm_atomic_plane_disabling(old_plane_state,
2381 						       new_plane_state);
2382 
2383 		if (active_only) {
2384 			/*
2385 			 * Skip planes related to inactive CRTCs. If the plane
2386 			 * is enabled use the state of the current CRTC. If the
2387 			 * plane is being disabled use the state of the old
2388 			 * CRTC to avoid skipping planes being disabled on an
2389 			 * active CRTC.
2390 			 */
2391 			if (!disabling && !plane_crtc_active(new_plane_state))
2392 				continue;
2393 			if (disabling && !plane_crtc_active(old_plane_state))
2394 				continue;
2395 		}
2396 
2397 		/*
2398 		 * Special-case disabling the plane if drivers support it.
2399 		 */
2400 		if (disabling && funcs->atomic_disable) {
2401 			struct drm_crtc_state *crtc_state;
2402 
2403 			crtc_state = old_plane_state->crtc->state;
2404 
2405 			if (drm_atomic_crtc_needs_modeset(crtc_state) &&
2406 			    no_disable)
2407 				continue;
2408 
2409 			funcs->atomic_disable(plane, old_plane_state);
2410 		} else if (new_plane_state->crtc || disabling) {
2411 			funcs->atomic_update(plane, old_plane_state);
2412 		}
2413 	}
2414 
2415 	for_each_oldnew_crtc_in_state(old_state, crtc, old_crtc_state, new_crtc_state, i) {
2416 		const struct drm_crtc_helper_funcs *funcs;
2417 
2418 		funcs = crtc->helper_private;
2419 
2420 		if (!funcs || !funcs->atomic_flush)
2421 			continue;
2422 
2423 		if (active_only && !new_crtc_state->active)
2424 			continue;
2425 
2426 		funcs->atomic_flush(crtc, old_crtc_state);
2427 	}
2428 }
2429 EXPORT_SYMBOL(drm_atomic_helper_commit_planes);
2430 
2431 /**
2432  * drm_atomic_helper_commit_planes_on_crtc - commit plane state for a crtc
2433  * @old_crtc_state: atomic state object with the old crtc state
2434  *
2435  * This function commits the new plane state using the plane and atomic helper
2436  * functions for planes on the specific crtc. It assumes that the atomic state
2437  * has already been pushed into the relevant object state pointers, since this
2438  * step can no longer fail.
2439  *
2440  * This function is useful when plane updates should be done crtc-by-crtc
2441  * instead of one global step like drm_atomic_helper_commit_planes() does.
2442  *
2443  * This function can only be savely used when planes are not allowed to move
2444  * between different CRTCs because this function doesn't handle inter-CRTC
2445  * depencies. Callers need to ensure that either no such depencies exist,
2446  * resolve them through ordering of commit calls or through some other means.
2447  */
2448 void
2449 drm_atomic_helper_commit_planes_on_crtc(struct drm_crtc_state *old_crtc_state)
2450 {
2451 	const struct drm_crtc_helper_funcs *crtc_funcs;
2452 	struct drm_crtc *crtc = old_crtc_state->crtc;
2453 	struct drm_atomic_state *old_state = old_crtc_state->state;
2454 	struct drm_crtc_state *new_crtc_state =
2455 		drm_atomic_get_new_crtc_state(old_state, crtc);
2456 	struct drm_plane *plane;
2457 	unsigned plane_mask;
2458 
2459 	plane_mask = old_crtc_state->plane_mask;
2460 	plane_mask |= new_crtc_state->plane_mask;
2461 
2462 	crtc_funcs = crtc->helper_private;
2463 	if (crtc_funcs && crtc_funcs->atomic_begin)
2464 		crtc_funcs->atomic_begin(crtc, old_crtc_state);
2465 
2466 	drm_for_each_plane_mask(plane, crtc->dev, plane_mask) {
2467 		struct drm_plane_state *old_plane_state =
2468 			drm_atomic_get_old_plane_state(old_state, plane);
2469 		struct drm_plane_state *new_plane_state =
2470 			drm_atomic_get_new_plane_state(old_state, plane);
2471 		const struct drm_plane_helper_funcs *plane_funcs;
2472 
2473 		plane_funcs = plane->helper_private;
2474 
2475 		if (!old_plane_state || !plane_funcs)
2476 			continue;
2477 
2478 		WARN_ON(new_plane_state->crtc &&
2479 			new_plane_state->crtc != crtc);
2480 
2481 		if (drm_atomic_plane_disabling(old_plane_state, new_plane_state) &&
2482 		    plane_funcs->atomic_disable)
2483 			plane_funcs->atomic_disable(plane, old_plane_state);
2484 		else if (new_plane_state->crtc ||
2485 			 drm_atomic_plane_disabling(old_plane_state, new_plane_state))
2486 			plane_funcs->atomic_update(plane, old_plane_state);
2487 	}
2488 
2489 	if (crtc_funcs && crtc_funcs->atomic_flush)
2490 		crtc_funcs->atomic_flush(crtc, old_crtc_state);
2491 }
2492 EXPORT_SYMBOL(drm_atomic_helper_commit_planes_on_crtc);
2493 
2494 /**
2495  * drm_atomic_helper_disable_planes_on_crtc - helper to disable CRTC's planes
2496  * @old_crtc_state: atomic state object with the old CRTC state
2497  * @atomic: if set, synchronize with CRTC's atomic_begin/flush hooks
2498  *
2499  * Disables all planes associated with the given CRTC. This can be
2500  * used for instance in the CRTC helper atomic_disable callback to disable
2501  * all planes.
2502  *
2503  * If the atomic-parameter is set the function calls the CRTC's
2504  * atomic_begin hook before and atomic_flush hook after disabling the
2505  * planes.
2506  *
2507  * It is a bug to call this function without having implemented the
2508  * &drm_plane_helper_funcs.atomic_disable plane hook.
2509  */
2510 void
2511 drm_atomic_helper_disable_planes_on_crtc(struct drm_crtc_state *old_crtc_state,
2512 					 bool atomic)
2513 {
2514 	struct drm_crtc *crtc = old_crtc_state->crtc;
2515 	const struct drm_crtc_helper_funcs *crtc_funcs =
2516 		crtc->helper_private;
2517 	struct drm_plane *plane;
2518 
2519 	if (atomic && crtc_funcs && crtc_funcs->atomic_begin)
2520 		crtc_funcs->atomic_begin(crtc, NULL);
2521 
2522 	drm_atomic_crtc_state_for_each_plane(plane, old_crtc_state) {
2523 		const struct drm_plane_helper_funcs *plane_funcs =
2524 			plane->helper_private;
2525 
2526 		if (!plane_funcs)
2527 			continue;
2528 
2529 		WARN_ON(!plane_funcs->atomic_disable);
2530 		if (plane_funcs->atomic_disable)
2531 			plane_funcs->atomic_disable(plane, NULL);
2532 	}
2533 
2534 	if (atomic && crtc_funcs && crtc_funcs->atomic_flush)
2535 		crtc_funcs->atomic_flush(crtc, NULL);
2536 }
2537 EXPORT_SYMBOL(drm_atomic_helper_disable_planes_on_crtc);
2538 
2539 /**
2540  * drm_atomic_helper_cleanup_planes - cleanup plane resources after commit
2541  * @dev: DRM device
2542  * @old_state: atomic state object with old state structures
2543  *
2544  * This function cleans up plane state, specifically framebuffers, from the old
2545  * configuration. Hence the old configuration must be perserved in @old_state to
2546  * be able to call this function.
2547  *
2548  * This function must also be called on the new state when the atomic update
2549  * fails at any point after calling drm_atomic_helper_prepare_planes().
2550  */
2551 void drm_atomic_helper_cleanup_planes(struct drm_device *dev,
2552 				      struct drm_atomic_state *old_state)
2553 {
2554 	struct drm_plane *plane;
2555 	struct drm_plane_state *old_plane_state, *new_plane_state;
2556 	int i;
2557 
2558 	for_each_oldnew_plane_in_state(old_state, plane, old_plane_state, new_plane_state, i) {
2559 		const struct drm_plane_helper_funcs *funcs;
2560 		struct drm_plane_state *plane_state;
2561 
2562 		/*
2563 		 * This might be called before swapping when commit is aborted,
2564 		 * in which case we have to cleanup the new state.
2565 		 */
2566 		if (old_plane_state == plane->state)
2567 			plane_state = new_plane_state;
2568 		else
2569 			plane_state = old_plane_state;
2570 
2571 		funcs = plane->helper_private;
2572 
2573 		if (funcs->cleanup_fb)
2574 			funcs->cleanup_fb(plane, plane_state);
2575 	}
2576 }
2577 EXPORT_SYMBOL(drm_atomic_helper_cleanup_planes);
2578 
2579 /**
2580  * drm_atomic_helper_swap_state - store atomic state into current sw state
2581  * @state: atomic state
2582  * @stall: stall for preceeding commits
2583  *
2584  * This function stores the atomic state into the current state pointers in all
2585  * driver objects. It should be called after all failing steps have been done
2586  * and succeeded, but before the actual hardware state is committed.
2587  *
2588  * For cleanup and error recovery the current state for all changed objects will
2589  * be swapped into @state.
2590  *
2591  * With that sequence it fits perfectly into the plane prepare/cleanup sequence:
2592  *
2593  * 1. Call drm_atomic_helper_prepare_planes() with the staged atomic state.
2594  *
2595  * 2. Do any other steps that might fail.
2596  *
2597  * 3. Put the staged state into the current state pointers with this function.
2598  *
2599  * 4. Actually commit the hardware state.
2600  *
2601  * 5. Call drm_atomic_helper_cleanup_planes() with @state, which since step 3
2602  * contains the old state. Also do any other cleanup required with that state.
2603  *
2604  * @stall must be set when nonblocking commits for this driver directly access
2605  * the &drm_plane.state, &drm_crtc.state or &drm_connector.state pointer. With
2606  * the current atomic helpers this is almost always the case, since the helpers
2607  * don't pass the right state structures to the callbacks.
2608  *
2609  * Returns:
2610  *
2611  * Returns 0 on success. Can return -ERESTARTSYS when @stall is true and the
2612  * waiting for the previous commits has been interrupted.
2613  */
2614 int drm_atomic_helper_swap_state(struct drm_atomic_state *state,
2615 				  bool stall)
2616 {
2617 	int i, ret;
2618 	struct drm_connector *connector;
2619 	struct drm_connector_state *old_conn_state, *new_conn_state;
2620 	struct drm_crtc *crtc;
2621 	struct drm_crtc_state *old_crtc_state, *new_crtc_state;
2622 	struct drm_plane *plane;
2623 	struct drm_plane_state *old_plane_state, *new_plane_state;
2624 	struct drm_crtc_commit *commit;
2625 	struct drm_private_obj *obj;
2626 	struct drm_private_state *old_obj_state, *new_obj_state;
2627 
2628 	if (stall) {
2629 		/*
2630 		 * We have to stall for hw_done here before
2631 		 * drm_atomic_helper_wait_for_dependencies() because flip
2632 		 * depth > 1 is not yet supported by all drivers. As long as
2633 		 * obj->state is directly dereferenced anywhere in the drivers
2634 		 * atomic_commit_tail function, then it's unsafe to swap state
2635 		 * before drm_atomic_helper_commit_hw_done() is called.
2636 		 */
2637 
2638 		for_each_old_crtc_in_state(state, crtc, old_crtc_state, i) {
2639 			commit = old_crtc_state->commit;
2640 
2641 			if (!commit)
2642 				continue;
2643 
2644 			ret = wait_for_completion_interruptible(&commit->hw_done);
2645 			if (ret)
2646 				return ret;
2647 		}
2648 
2649 		for_each_old_connector_in_state(state, connector, old_conn_state, i) {
2650 			commit = old_conn_state->commit;
2651 
2652 			if (!commit)
2653 				continue;
2654 
2655 			ret = wait_for_completion_interruptible(&commit->hw_done);
2656 			if (ret)
2657 				return ret;
2658 		}
2659 
2660 		for_each_old_plane_in_state(state, plane, old_plane_state, i) {
2661 			commit = old_plane_state->commit;
2662 
2663 			if (!commit)
2664 				continue;
2665 
2666 			ret = wait_for_completion_interruptible(&commit->hw_done);
2667 			if (ret)
2668 				return ret;
2669 		}
2670 	}
2671 
2672 	for_each_oldnew_connector_in_state(state, connector, old_conn_state, new_conn_state, i) {
2673 		WARN_ON(connector->state != old_conn_state);
2674 
2675 		old_conn_state->state = state;
2676 		new_conn_state->state = NULL;
2677 
2678 		state->connectors[i].state = old_conn_state;
2679 		connector->state = new_conn_state;
2680 	}
2681 
2682 	for_each_oldnew_crtc_in_state(state, crtc, old_crtc_state, new_crtc_state, i) {
2683 		WARN_ON(crtc->state != old_crtc_state);
2684 
2685 		old_crtc_state->state = state;
2686 		new_crtc_state->state = NULL;
2687 
2688 		state->crtcs[i].state = old_crtc_state;
2689 		crtc->state = new_crtc_state;
2690 
2691 		if (new_crtc_state->commit) {
2692 			spin_lock(&crtc->commit_lock);
2693 			list_add(&new_crtc_state->commit->commit_entry,
2694 				 &crtc->commit_list);
2695 			spin_unlock(&crtc->commit_lock);
2696 
2697 			new_crtc_state->commit->event = NULL;
2698 		}
2699 	}
2700 
2701 	for_each_oldnew_plane_in_state(state, plane, old_plane_state, new_plane_state, i) {
2702 		WARN_ON(plane->state != old_plane_state);
2703 
2704 		old_plane_state->state = state;
2705 		new_plane_state->state = NULL;
2706 
2707 		state->planes[i].state = old_plane_state;
2708 		plane->state = new_plane_state;
2709 	}
2710 
2711 	for_each_oldnew_private_obj_in_state(state, obj, old_obj_state, new_obj_state, i) {
2712 		WARN_ON(obj->state != old_obj_state);
2713 
2714 		old_obj_state->state = state;
2715 		new_obj_state->state = NULL;
2716 
2717 		state->private_objs[i].state = old_obj_state;
2718 		obj->state = new_obj_state;
2719 	}
2720 
2721 	return 0;
2722 }
2723 EXPORT_SYMBOL(drm_atomic_helper_swap_state);
2724 
2725 /**
2726  * drm_atomic_helper_update_plane - Helper for primary plane update using atomic
2727  * @plane: plane object to update
2728  * @crtc: owning CRTC of owning plane
2729  * @fb: framebuffer to flip onto plane
2730  * @crtc_x: x offset of primary plane on crtc
2731  * @crtc_y: y offset of primary plane on crtc
2732  * @crtc_w: width of primary plane rectangle on crtc
2733  * @crtc_h: height of primary plane rectangle on crtc
2734  * @src_x: x offset of @fb for panning
2735  * @src_y: y offset of @fb for panning
2736  * @src_w: width of source rectangle in @fb
2737  * @src_h: height of source rectangle in @fb
2738  * @ctx: lock acquire context
2739  *
2740  * Provides a default plane update handler using the atomic driver interface.
2741  *
2742  * RETURNS:
2743  * Zero on success, error code on failure
2744  */
2745 int drm_atomic_helper_update_plane(struct drm_plane *plane,
2746 				   struct drm_crtc *crtc,
2747 				   struct drm_framebuffer *fb,
2748 				   int crtc_x, int crtc_y,
2749 				   unsigned int crtc_w, unsigned int crtc_h,
2750 				   uint32_t src_x, uint32_t src_y,
2751 				   uint32_t src_w, uint32_t src_h,
2752 				   struct drm_modeset_acquire_ctx *ctx)
2753 {
2754 	struct drm_atomic_state *state;
2755 	struct drm_plane_state *plane_state;
2756 	int ret = 0;
2757 
2758 	state = drm_atomic_state_alloc(plane->dev);
2759 	if (!state)
2760 		return -ENOMEM;
2761 
2762 	state->acquire_ctx = ctx;
2763 	plane_state = drm_atomic_get_plane_state(state, plane);
2764 	if (IS_ERR(plane_state)) {
2765 		ret = PTR_ERR(plane_state);
2766 		goto fail;
2767 	}
2768 
2769 	ret = drm_atomic_set_crtc_for_plane(plane_state, crtc);
2770 	if (ret != 0)
2771 		goto fail;
2772 	drm_atomic_set_fb_for_plane(plane_state, fb);
2773 	plane_state->crtc_x = crtc_x;
2774 	plane_state->crtc_y = crtc_y;
2775 	plane_state->crtc_w = crtc_w;
2776 	plane_state->crtc_h = crtc_h;
2777 	plane_state->src_x = src_x;
2778 	plane_state->src_y = src_y;
2779 	plane_state->src_w = src_w;
2780 	plane_state->src_h = src_h;
2781 
2782 	if (plane == crtc->cursor)
2783 		state->legacy_cursor_update = true;
2784 
2785 	ret = drm_atomic_commit(state);
2786 fail:
2787 	drm_atomic_state_put(state);
2788 	return ret;
2789 }
2790 EXPORT_SYMBOL(drm_atomic_helper_update_plane);
2791 
2792 /**
2793  * drm_atomic_helper_disable_plane - Helper for primary plane disable using * atomic
2794  * @plane: plane to disable
2795  * @ctx: lock acquire context
2796  *
2797  * Provides a default plane disable handler using the atomic driver interface.
2798  *
2799  * RETURNS:
2800  * Zero on success, error code on failure
2801  */
2802 int drm_atomic_helper_disable_plane(struct drm_plane *plane,
2803 				    struct drm_modeset_acquire_ctx *ctx)
2804 {
2805 	struct drm_atomic_state *state;
2806 	struct drm_plane_state *plane_state;
2807 	int ret = 0;
2808 
2809 	state = drm_atomic_state_alloc(plane->dev);
2810 	if (!state)
2811 		return -ENOMEM;
2812 
2813 	state->acquire_ctx = ctx;
2814 	plane_state = drm_atomic_get_plane_state(state, plane);
2815 	if (IS_ERR(plane_state)) {
2816 		ret = PTR_ERR(plane_state);
2817 		goto fail;
2818 	}
2819 
2820 	if (plane_state->crtc && plane_state->crtc->cursor == plane)
2821 		plane_state->state->legacy_cursor_update = true;
2822 
2823 	ret = __drm_atomic_helper_disable_plane(plane, plane_state);
2824 	if (ret != 0)
2825 		goto fail;
2826 
2827 	ret = drm_atomic_commit(state);
2828 fail:
2829 	drm_atomic_state_put(state);
2830 	return ret;
2831 }
2832 EXPORT_SYMBOL(drm_atomic_helper_disable_plane);
2833 
2834 /* just used from fb-helper and atomic-helper: */
2835 int __drm_atomic_helper_disable_plane(struct drm_plane *plane,
2836 		struct drm_plane_state *plane_state)
2837 {
2838 	int ret;
2839 
2840 	ret = drm_atomic_set_crtc_for_plane(plane_state, NULL);
2841 	if (ret != 0)
2842 		return ret;
2843 
2844 	drm_atomic_set_fb_for_plane(plane_state, NULL);
2845 	plane_state->crtc_x = 0;
2846 	plane_state->crtc_y = 0;
2847 	plane_state->crtc_w = 0;
2848 	plane_state->crtc_h = 0;
2849 	plane_state->src_x = 0;
2850 	plane_state->src_y = 0;
2851 	plane_state->src_w = 0;
2852 	plane_state->src_h = 0;
2853 
2854 	return 0;
2855 }
2856 
2857 static int update_output_state(struct drm_atomic_state *state,
2858 			       struct drm_mode_set *set)
2859 {
2860 	struct drm_device *dev = set->crtc->dev;
2861 	struct drm_crtc *crtc;
2862 	struct drm_crtc_state *new_crtc_state;
2863 	struct drm_connector *connector;
2864 	struct drm_connector_state *new_conn_state;
2865 	int ret, i;
2866 
2867 	ret = drm_modeset_lock(&dev->mode_config.connection_mutex,
2868 			       state->acquire_ctx);
2869 	if (ret)
2870 		return ret;
2871 
2872 	/* First disable all connectors on the target crtc. */
2873 	ret = drm_atomic_add_affected_connectors(state, set->crtc);
2874 	if (ret)
2875 		return ret;
2876 
2877 	for_each_new_connector_in_state(state, connector, new_conn_state, i) {
2878 		if (new_conn_state->crtc == set->crtc) {
2879 			ret = drm_atomic_set_crtc_for_connector(new_conn_state,
2880 								NULL);
2881 			if (ret)
2882 				return ret;
2883 
2884 			/* Make sure legacy setCrtc always re-trains */
2885 			new_conn_state->link_status = DRM_LINK_STATUS_GOOD;
2886 		}
2887 	}
2888 
2889 	/* Then set all connectors from set->connectors on the target crtc */
2890 	for (i = 0; i < set->num_connectors; i++) {
2891 		new_conn_state = drm_atomic_get_connector_state(state,
2892 							    set->connectors[i]);
2893 		if (IS_ERR(new_conn_state))
2894 			return PTR_ERR(new_conn_state);
2895 
2896 		ret = drm_atomic_set_crtc_for_connector(new_conn_state,
2897 							set->crtc);
2898 		if (ret)
2899 			return ret;
2900 	}
2901 
2902 	for_each_new_crtc_in_state(state, crtc, new_crtc_state, i) {
2903 		/* Don't update ->enable for the CRTC in the set_config request,
2904 		 * since a mismatch would indicate a bug in the upper layers.
2905 		 * The actual modeset code later on will catch any
2906 		 * inconsistencies here. */
2907 		if (crtc == set->crtc)
2908 			continue;
2909 
2910 		if (!new_crtc_state->connector_mask) {
2911 			ret = drm_atomic_set_mode_prop_for_crtc(new_crtc_state,
2912 								NULL);
2913 			if (ret < 0)
2914 				return ret;
2915 
2916 			new_crtc_state->active = false;
2917 		}
2918 	}
2919 
2920 	return 0;
2921 }
2922 
2923 /**
2924  * drm_atomic_helper_set_config - set a new config from userspace
2925  * @set: mode set configuration
2926  * @ctx: lock acquisition context
2927  *
2928  * Provides a default crtc set_config handler using the atomic driver interface.
2929  *
2930  * NOTE: For backwards compatibility with old userspace this automatically
2931  * resets the "link-status" property to GOOD, to force any link
2932  * re-training. The SETCRTC ioctl does not define whether an update does
2933  * need a full modeset or just a plane update, hence we're allowed to do
2934  * that. See also drm_connector_set_link_status_property().
2935  *
2936  * Returns:
2937  * Returns 0 on success, negative errno numbers on failure.
2938  */
2939 int drm_atomic_helper_set_config(struct drm_mode_set *set,
2940 				 struct drm_modeset_acquire_ctx *ctx)
2941 {
2942 	struct drm_atomic_state *state;
2943 	struct drm_crtc *crtc = set->crtc;
2944 	int ret = 0;
2945 
2946 	state = drm_atomic_state_alloc(crtc->dev);
2947 	if (!state)
2948 		return -ENOMEM;
2949 
2950 	state->acquire_ctx = ctx;
2951 	ret = __drm_atomic_helper_set_config(set, state);
2952 	if (ret != 0)
2953 		goto fail;
2954 
2955 	ret = handle_conflicting_encoders(state, true);
2956 	if (ret)
2957 		return ret;
2958 
2959 	ret = drm_atomic_commit(state);
2960 
2961 fail:
2962 	drm_atomic_state_put(state);
2963 	return ret;
2964 }
2965 EXPORT_SYMBOL(drm_atomic_helper_set_config);
2966 
2967 /* just used from fb-helper and atomic-helper: */
2968 int __drm_atomic_helper_set_config(struct drm_mode_set *set,
2969 		struct drm_atomic_state *state)
2970 {
2971 	struct drm_crtc_state *crtc_state;
2972 	struct drm_plane_state *primary_state;
2973 	struct drm_crtc *crtc = set->crtc;
2974 	int hdisplay, vdisplay;
2975 	int ret;
2976 
2977 	crtc_state = drm_atomic_get_crtc_state(state, crtc);
2978 	if (IS_ERR(crtc_state))
2979 		return PTR_ERR(crtc_state);
2980 
2981 	primary_state = drm_atomic_get_plane_state(state, crtc->primary);
2982 	if (IS_ERR(primary_state))
2983 		return PTR_ERR(primary_state);
2984 
2985 	if (!set->mode) {
2986 		WARN_ON(set->fb);
2987 		WARN_ON(set->num_connectors);
2988 
2989 		ret = drm_atomic_set_mode_for_crtc(crtc_state, NULL);
2990 		if (ret != 0)
2991 			return ret;
2992 
2993 		crtc_state->active = false;
2994 
2995 		ret = drm_atomic_set_crtc_for_plane(primary_state, NULL);
2996 		if (ret != 0)
2997 			return ret;
2998 
2999 		drm_atomic_set_fb_for_plane(primary_state, NULL);
3000 
3001 		goto commit;
3002 	}
3003 
3004 	WARN_ON(!set->fb);
3005 	WARN_ON(!set->num_connectors);
3006 
3007 	ret = drm_atomic_set_mode_for_crtc(crtc_state, set->mode);
3008 	if (ret != 0)
3009 		return ret;
3010 
3011 	crtc_state->active = true;
3012 
3013 	ret = drm_atomic_set_crtc_for_plane(primary_state, crtc);
3014 	if (ret != 0)
3015 		return ret;
3016 
3017 	drm_mode_get_hv_timing(set->mode, &hdisplay, &vdisplay);
3018 
3019 	drm_atomic_set_fb_for_plane(primary_state, set->fb);
3020 	primary_state->crtc_x = 0;
3021 	primary_state->crtc_y = 0;
3022 	primary_state->crtc_w = hdisplay;
3023 	primary_state->crtc_h = vdisplay;
3024 	primary_state->src_x = set->x << 16;
3025 	primary_state->src_y = set->y << 16;
3026 	if (drm_rotation_90_or_270(primary_state->rotation)) {
3027 		primary_state->src_w = vdisplay << 16;
3028 		primary_state->src_h = hdisplay << 16;
3029 	} else {
3030 		primary_state->src_w = hdisplay << 16;
3031 		primary_state->src_h = vdisplay << 16;
3032 	}
3033 
3034 commit:
3035 	ret = update_output_state(state, set);
3036 	if (ret)
3037 		return ret;
3038 
3039 	return 0;
3040 }
3041 
3042 /**
3043  * drm_atomic_helper_disable_all - disable all currently active outputs
3044  * @dev: DRM device
3045  * @ctx: lock acquisition context
3046  *
3047  * Loops through all connectors, finding those that aren't turned off and then
3048  * turns them off by setting their DPMS mode to OFF and deactivating the CRTC
3049  * that they are connected to.
3050  *
3051  * This is used for example in suspend/resume to disable all currently active
3052  * functions when suspending. If you just want to shut down everything at e.g.
3053  * driver unload, look at drm_atomic_helper_shutdown().
3054  *
3055  * Note that if callers haven't already acquired all modeset locks this might
3056  * return -EDEADLK, which must be handled by calling drm_modeset_backoff().
3057  *
3058  * Returns:
3059  * 0 on success or a negative error code on failure.
3060  *
3061  * See also:
3062  * drm_atomic_helper_suspend(), drm_atomic_helper_resume() and
3063  * drm_atomic_helper_shutdown().
3064  */
3065 int drm_atomic_helper_disable_all(struct drm_device *dev,
3066 				  struct drm_modeset_acquire_ctx *ctx)
3067 {
3068 	struct drm_atomic_state *state;
3069 	struct drm_connector_state *conn_state;
3070 	struct drm_connector *conn;
3071 	struct drm_plane_state *plane_state;
3072 	struct drm_plane *plane;
3073 	struct drm_crtc_state *crtc_state;
3074 	struct drm_crtc *crtc;
3075 	int ret, i;
3076 
3077 	state = drm_atomic_state_alloc(dev);
3078 	if (!state)
3079 		return -ENOMEM;
3080 
3081 	state->acquire_ctx = ctx;
3082 
3083 	drm_for_each_crtc(crtc, dev) {
3084 		crtc_state = drm_atomic_get_crtc_state(state, crtc);
3085 		if (IS_ERR(crtc_state)) {
3086 			ret = PTR_ERR(crtc_state);
3087 			goto free;
3088 		}
3089 
3090 		crtc_state->active = false;
3091 
3092 		ret = drm_atomic_set_mode_prop_for_crtc(crtc_state, NULL);
3093 		if (ret < 0)
3094 			goto free;
3095 
3096 		ret = drm_atomic_add_affected_planes(state, crtc);
3097 		if (ret < 0)
3098 			goto free;
3099 
3100 		ret = drm_atomic_add_affected_connectors(state, crtc);
3101 		if (ret < 0)
3102 			goto free;
3103 	}
3104 
3105 	for_each_new_connector_in_state(state, conn, conn_state, i) {
3106 		ret = drm_atomic_set_crtc_for_connector(conn_state, NULL);
3107 		if (ret < 0)
3108 			goto free;
3109 	}
3110 
3111 	for_each_new_plane_in_state(state, plane, plane_state, i) {
3112 		ret = drm_atomic_set_crtc_for_plane(plane_state, NULL);
3113 		if (ret < 0)
3114 			goto free;
3115 
3116 		drm_atomic_set_fb_for_plane(plane_state, NULL);
3117 	}
3118 
3119 	ret = drm_atomic_commit(state);
3120 free:
3121 	drm_atomic_state_put(state);
3122 	return ret;
3123 }
3124 EXPORT_SYMBOL(drm_atomic_helper_disable_all);
3125 
3126 /**
3127  * drm_atomic_helper_shutdown - shutdown all CRTC
3128  * @dev: DRM device
3129  *
3130  * This shuts down all CRTC, which is useful for driver unloading. Shutdown on
3131  * suspend should instead be handled with drm_atomic_helper_suspend(), since
3132  * that also takes a snapshot of the modeset state to be restored on resume.
3133  *
3134  * This is just a convenience wrapper around drm_atomic_helper_disable_all(),
3135  * and it is the atomic version of drm_crtc_force_disable_all().
3136  */
3137 void drm_atomic_helper_shutdown(struct drm_device *dev)
3138 {
3139 	struct drm_modeset_acquire_ctx ctx;
3140 	int ret;
3141 
3142 	DRM_MODESET_LOCK_ALL_BEGIN(dev, ctx, 0, ret);
3143 
3144 	ret = drm_atomic_helper_disable_all(dev, &ctx);
3145 	if (ret)
3146 		DRM_ERROR("Disabling all crtc's during unload failed with %i\n", ret);
3147 
3148 	DRM_MODESET_LOCK_ALL_END(ctx, ret);
3149 }
3150 EXPORT_SYMBOL(drm_atomic_helper_shutdown);
3151 
3152 /**
3153  * drm_atomic_helper_duplicate_state - duplicate an atomic state object
3154  * @dev: DRM device
3155  * @ctx: lock acquisition context
3156  *
3157  * Makes a copy of the current atomic state by looping over all objects and
3158  * duplicating their respective states. This is used for example by suspend/
3159  * resume support code to save the state prior to suspend such that it can
3160  * be restored upon resume.
3161  *
3162  * Note that this treats atomic state as persistent between save and restore.
3163  * Drivers must make sure that this is possible and won't result in confusion
3164  * or erroneous behaviour.
3165  *
3166  * Note that if callers haven't already acquired all modeset locks this might
3167  * return -EDEADLK, which must be handled by calling drm_modeset_backoff().
3168  *
3169  * Returns:
3170  * A pointer to the copy of the atomic state object on success or an
3171  * ERR_PTR()-encoded error code on failure.
3172  *
3173  * See also:
3174  * drm_atomic_helper_suspend(), drm_atomic_helper_resume()
3175  */
3176 struct drm_atomic_state *
3177 drm_atomic_helper_duplicate_state(struct drm_device *dev,
3178 				  struct drm_modeset_acquire_ctx *ctx)
3179 {
3180 	struct drm_atomic_state *state;
3181 	struct drm_connector *conn;
3182 	struct drm_connector_list_iter conn_iter;
3183 	struct drm_plane *plane;
3184 	struct drm_crtc *crtc;
3185 	int err = 0;
3186 
3187 	state = drm_atomic_state_alloc(dev);
3188 	if (!state)
3189 		return ERR_PTR(-ENOMEM);
3190 
3191 	state->acquire_ctx = ctx;
3192 	state->duplicated = true;
3193 
3194 	drm_for_each_crtc(crtc, dev) {
3195 		struct drm_crtc_state *crtc_state;
3196 
3197 		crtc_state = drm_atomic_get_crtc_state(state, crtc);
3198 		if (IS_ERR(crtc_state)) {
3199 			err = PTR_ERR(crtc_state);
3200 			goto free;
3201 		}
3202 	}
3203 
3204 	drm_for_each_plane(plane, dev) {
3205 		struct drm_plane_state *plane_state;
3206 
3207 		plane_state = drm_atomic_get_plane_state(state, plane);
3208 		if (IS_ERR(plane_state)) {
3209 			err = PTR_ERR(plane_state);
3210 			goto free;
3211 		}
3212 	}
3213 
3214 	drm_connector_list_iter_begin(dev, &conn_iter);
3215 	drm_for_each_connector_iter(conn, &conn_iter) {
3216 		struct drm_connector_state *conn_state;
3217 
3218 		conn_state = drm_atomic_get_connector_state(state, conn);
3219 		if (IS_ERR(conn_state)) {
3220 			err = PTR_ERR(conn_state);
3221 			drm_connector_list_iter_end(&conn_iter);
3222 			goto free;
3223 		}
3224 	}
3225 	drm_connector_list_iter_end(&conn_iter);
3226 
3227 	/* clear the acquire context so that it isn't accidentally reused */
3228 	state->acquire_ctx = NULL;
3229 
3230 free:
3231 	if (err < 0) {
3232 		drm_atomic_state_put(state);
3233 		state = ERR_PTR(err);
3234 	}
3235 
3236 	return state;
3237 }
3238 EXPORT_SYMBOL(drm_atomic_helper_duplicate_state);
3239 
3240 /**
3241  * drm_atomic_helper_suspend - subsystem-level suspend helper
3242  * @dev: DRM device
3243  *
3244  * Duplicates the current atomic state, disables all active outputs and then
3245  * returns a pointer to the original atomic state to the caller. Drivers can
3246  * pass this pointer to the drm_atomic_helper_resume() helper upon resume to
3247  * restore the output configuration that was active at the time the system
3248  * entered suspend.
3249  *
3250  * Note that it is potentially unsafe to use this. The atomic state object
3251  * returned by this function is assumed to be persistent. Drivers must ensure
3252  * that this holds true. Before calling this function, drivers must make sure
3253  * to suspend fbdev emulation so that nothing can be using the device.
3254  *
3255  * Returns:
3256  * A pointer to a copy of the state before suspend on success or an ERR_PTR()-
3257  * encoded error code on failure. Drivers should store the returned atomic
3258  * state object and pass it to the drm_atomic_helper_resume() helper upon
3259  * resume.
3260  *
3261  * See also:
3262  * drm_atomic_helper_duplicate_state(), drm_atomic_helper_disable_all(),
3263  * drm_atomic_helper_resume(), drm_atomic_helper_commit_duplicated_state()
3264  */
3265 struct drm_atomic_state *drm_atomic_helper_suspend(struct drm_device *dev)
3266 {
3267 	struct drm_modeset_acquire_ctx ctx;
3268 	struct drm_atomic_state *state;
3269 	int err;
3270 
3271 	/* This can never be returned, but it makes the compiler happy */
3272 	state = ERR_PTR(-EINVAL);
3273 
3274 	DRM_MODESET_LOCK_ALL_BEGIN(dev, ctx, 0, err);
3275 
3276 	state = drm_atomic_helper_duplicate_state(dev, &ctx);
3277 	if (IS_ERR(state))
3278 		goto unlock;
3279 
3280 	err = drm_atomic_helper_disable_all(dev, &ctx);
3281 	if (err < 0) {
3282 		drm_atomic_state_put(state);
3283 		state = ERR_PTR(err);
3284 		goto unlock;
3285 	}
3286 
3287 unlock:
3288 	DRM_MODESET_LOCK_ALL_END(ctx, err);
3289 	if (err)
3290 		return ERR_PTR(err);
3291 
3292 	return state;
3293 }
3294 EXPORT_SYMBOL(drm_atomic_helper_suspend);
3295 
3296 /**
3297  * drm_atomic_helper_commit_duplicated_state - commit duplicated state
3298  * @state: duplicated atomic state to commit
3299  * @ctx: pointer to acquire_ctx to use for commit.
3300  *
3301  * The state returned by drm_atomic_helper_duplicate_state() and
3302  * drm_atomic_helper_suspend() is partially invalid, and needs to
3303  * be fixed up before commit.
3304  *
3305  * Returns:
3306  * 0 on success or a negative error code on failure.
3307  *
3308  * See also:
3309  * drm_atomic_helper_suspend()
3310  */
3311 int drm_atomic_helper_commit_duplicated_state(struct drm_atomic_state *state,
3312 					      struct drm_modeset_acquire_ctx *ctx)
3313 {
3314 	int i, ret;
3315 	struct drm_plane *plane;
3316 	struct drm_plane_state *new_plane_state;
3317 	struct drm_connector *connector;
3318 	struct drm_connector_state *new_conn_state;
3319 	struct drm_crtc *crtc;
3320 	struct drm_crtc_state *new_crtc_state;
3321 
3322 	state->acquire_ctx = ctx;
3323 
3324 	for_each_new_plane_in_state(state, plane, new_plane_state, i)
3325 		state->planes[i].old_state = plane->state;
3326 
3327 	for_each_new_crtc_in_state(state, crtc, new_crtc_state, i)
3328 		state->crtcs[i].old_state = crtc->state;
3329 
3330 	for_each_new_connector_in_state(state, connector, new_conn_state, i)
3331 		state->connectors[i].old_state = connector->state;
3332 
3333 	ret = drm_atomic_commit(state);
3334 
3335 	state->acquire_ctx = NULL;
3336 
3337 	return ret;
3338 }
3339 EXPORT_SYMBOL(drm_atomic_helper_commit_duplicated_state);
3340 
3341 /**
3342  * drm_atomic_helper_resume - subsystem-level resume helper
3343  * @dev: DRM device
3344  * @state: atomic state to resume to
3345  *
3346  * Calls drm_mode_config_reset() to synchronize hardware and software states,
3347  * grabs all modeset locks and commits the atomic state object. This can be
3348  * used in conjunction with the drm_atomic_helper_suspend() helper to
3349  * implement suspend/resume for drivers that support atomic mode-setting.
3350  *
3351  * Returns:
3352  * 0 on success or a negative error code on failure.
3353  *
3354  * See also:
3355  * drm_atomic_helper_suspend()
3356  */
3357 int drm_atomic_helper_resume(struct drm_device *dev,
3358 			     struct drm_atomic_state *state)
3359 {
3360 	struct drm_modeset_acquire_ctx ctx;
3361 	int err;
3362 
3363 	drm_mode_config_reset(dev);
3364 
3365 	DRM_MODESET_LOCK_ALL_BEGIN(dev, ctx, 0, err);
3366 
3367 	err = drm_atomic_helper_commit_duplicated_state(state, &ctx);
3368 
3369 	DRM_MODESET_LOCK_ALL_END(ctx, err);
3370 	drm_atomic_state_put(state);
3371 
3372 	return err;
3373 }
3374 EXPORT_SYMBOL(drm_atomic_helper_resume);
3375 
3376 static int page_flip_common(struct drm_atomic_state *state,
3377 			    struct drm_crtc *crtc,
3378 			    struct drm_framebuffer *fb,
3379 			    struct drm_pending_vblank_event *event,
3380 			    uint32_t flags)
3381 {
3382 	struct drm_plane *plane = crtc->primary;
3383 	struct drm_plane_state *plane_state;
3384 	struct drm_crtc_state *crtc_state;
3385 	int ret = 0;
3386 
3387 	crtc_state = drm_atomic_get_crtc_state(state, crtc);
3388 	if (IS_ERR(crtc_state))
3389 		return PTR_ERR(crtc_state);
3390 
3391 	crtc_state->event = event;
3392 	crtc_state->pageflip_flags = flags;
3393 
3394 	plane_state = drm_atomic_get_plane_state(state, plane);
3395 	if (IS_ERR(plane_state))
3396 		return PTR_ERR(plane_state);
3397 
3398 	ret = drm_atomic_set_crtc_for_plane(plane_state, crtc);
3399 	if (ret != 0)
3400 		return ret;
3401 	drm_atomic_set_fb_for_plane(plane_state, fb);
3402 
3403 	/* Make sure we don't accidentally do a full modeset. */
3404 	state->allow_modeset = false;
3405 	if (!crtc_state->active) {
3406 		DRM_DEBUG_ATOMIC("[CRTC:%d:%s] disabled, rejecting legacy flip\n",
3407 				 crtc->base.id, crtc->name);
3408 		return -EINVAL;
3409 	}
3410 
3411 	return ret;
3412 }
3413 
3414 /**
3415  * drm_atomic_helper_page_flip - execute a legacy page flip
3416  * @crtc: DRM crtc
3417  * @fb: DRM framebuffer
3418  * @event: optional DRM event to signal upon completion
3419  * @flags: flip flags for non-vblank sync'ed updates
3420  * @ctx: lock acquisition context
3421  *
3422  * Provides a default &drm_crtc_funcs.page_flip implementation
3423  * using the atomic driver interface.
3424  *
3425  * Returns:
3426  * Returns 0 on success, negative errno numbers on failure.
3427  *
3428  * See also:
3429  * drm_atomic_helper_page_flip_target()
3430  */
3431 int drm_atomic_helper_page_flip(struct drm_crtc *crtc,
3432 				struct drm_framebuffer *fb,
3433 				struct drm_pending_vblank_event *event,
3434 				uint32_t flags,
3435 				struct drm_modeset_acquire_ctx *ctx)
3436 {
3437 	struct drm_plane *plane = crtc->primary;
3438 	struct drm_atomic_state *state;
3439 	int ret = 0;
3440 
3441 	state = drm_atomic_state_alloc(plane->dev);
3442 	if (!state)
3443 		return -ENOMEM;
3444 
3445 	state->acquire_ctx = ctx;
3446 
3447 	ret = page_flip_common(state, crtc, fb, event, flags);
3448 	if (ret != 0)
3449 		goto fail;
3450 
3451 	ret = drm_atomic_nonblocking_commit(state);
3452 fail:
3453 	drm_atomic_state_put(state);
3454 	return ret;
3455 }
3456 EXPORT_SYMBOL(drm_atomic_helper_page_flip);
3457 
3458 /**
3459  * drm_atomic_helper_page_flip_target - do page flip on target vblank period.
3460  * @crtc: DRM crtc
3461  * @fb: DRM framebuffer
3462  * @event: optional DRM event to signal upon completion
3463  * @flags: flip flags for non-vblank sync'ed updates
3464  * @target: specifying the target vblank period when the flip to take effect
3465  * @ctx: lock acquisition context
3466  *
3467  * Provides a default &drm_crtc_funcs.page_flip_target implementation.
3468  * Similar to drm_atomic_helper_page_flip() with extra parameter to specify
3469  * target vblank period to flip.
3470  *
3471  * Returns:
3472  * Returns 0 on success, negative errno numbers on failure.
3473  */
3474 int drm_atomic_helper_page_flip_target(struct drm_crtc *crtc,
3475 				       struct drm_framebuffer *fb,
3476 				       struct drm_pending_vblank_event *event,
3477 				       uint32_t flags,
3478 				       uint32_t target,
3479 				       struct drm_modeset_acquire_ctx *ctx)
3480 {
3481 	struct drm_plane *plane = crtc->primary;
3482 	struct drm_atomic_state *state;
3483 	struct drm_crtc_state *crtc_state;
3484 	int ret = 0;
3485 
3486 	state = drm_atomic_state_alloc(plane->dev);
3487 	if (!state)
3488 		return -ENOMEM;
3489 
3490 	state->acquire_ctx = ctx;
3491 
3492 	ret = page_flip_common(state, crtc, fb, event, flags);
3493 	if (ret != 0)
3494 		goto fail;
3495 
3496 	crtc_state = drm_atomic_get_new_crtc_state(state, crtc);
3497 	if (WARN_ON(!crtc_state)) {
3498 		ret = -EINVAL;
3499 		goto fail;
3500 	}
3501 	crtc_state->target_vblank = target;
3502 
3503 	ret = drm_atomic_nonblocking_commit(state);
3504 fail:
3505 	drm_atomic_state_put(state);
3506 	return ret;
3507 }
3508 EXPORT_SYMBOL(drm_atomic_helper_page_flip_target);
3509 
3510 /**
3511  * drm_atomic_helper_legacy_gamma_set - set the legacy gamma correction table
3512  * @crtc: CRTC object
3513  * @red: red correction table
3514  * @green: green correction table
3515  * @blue: green correction table
3516  * @size: size of the tables
3517  * @ctx: lock acquire context
3518  *
3519  * Implements support for legacy gamma correction table for drivers
3520  * that support color management through the DEGAMMA_LUT/GAMMA_LUT
3521  * properties. See drm_crtc_enable_color_mgmt() and the containing chapter for
3522  * how the atomic color management and gamma tables work.
3523  */
3524 int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
3525 				       u16 *red, u16 *green, u16 *blue,
3526 				       uint32_t size,
3527 				       struct drm_modeset_acquire_ctx *ctx)
3528 {
3529 	struct drm_device *dev = crtc->dev;
3530 	struct drm_atomic_state *state;
3531 	struct drm_crtc_state *crtc_state;
3532 	struct drm_property_blob *blob = NULL;
3533 	struct drm_color_lut *blob_data;
3534 	int i, ret = 0;
3535 	bool replaced;
3536 
3537 	state = drm_atomic_state_alloc(crtc->dev);
3538 	if (!state)
3539 		return -ENOMEM;
3540 
3541 	blob = drm_property_create_blob(dev,
3542 					sizeof(struct drm_color_lut) * size,
3543 					NULL);
3544 	if (IS_ERR(blob)) {
3545 		ret = PTR_ERR(blob);
3546 		blob = NULL;
3547 		goto fail;
3548 	}
3549 
3550 	/* Prepare GAMMA_LUT with the legacy values. */
3551 	blob_data = blob->data;
3552 	for (i = 0; i < size; i++) {
3553 		blob_data[i].red = red[i];
3554 		blob_data[i].green = green[i];
3555 		blob_data[i].blue = blue[i];
3556 	}
3557 
3558 	state->acquire_ctx = ctx;
3559 	crtc_state = drm_atomic_get_crtc_state(state, crtc);
3560 	if (IS_ERR(crtc_state)) {
3561 		ret = PTR_ERR(crtc_state);
3562 		goto fail;
3563 	}
3564 
3565 	/* Reset DEGAMMA_LUT and CTM properties. */
3566 	replaced  = drm_property_replace_blob(&crtc_state->degamma_lut, NULL);
3567 	replaced |= drm_property_replace_blob(&crtc_state->ctm, NULL);
3568 	replaced |= drm_property_replace_blob(&crtc_state->gamma_lut, blob);
3569 	crtc_state->color_mgmt_changed |= replaced;
3570 
3571 	ret = drm_atomic_commit(state);
3572 
3573 fail:
3574 	drm_atomic_state_put(state);
3575 	drm_property_blob_put(blob);
3576 	return ret;
3577 }
3578 EXPORT_SYMBOL(drm_atomic_helper_legacy_gamma_set);
3579