drm_atomic.h

   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#ifndef DRM_ATOMIC_H_
  29#define DRM_ATOMIC_H_
  30
  31#include <drm/drm_crtc.h>
  32#include <drm/drm_util.h>
  33
  34/**
  35 * struct drm_crtc_commit - track modeset commits on a CRTC
  36 *
  37 * This structure is used to track pending modeset changes and atomic commit on
  38 * a per-CRTC basis. Since updating the list should never block, this structure
  39 * is reference counted to allow waiters to safely wait on an event to complete,
  40 * without holding any locks.
  41 *
  42 * It has 3 different events in total to allow a fine-grained synchronization
  43 * between outstanding updates::
  44 *
  45 *	atomic commit thread			hardware
  46 *
  47 * 	write new state into hardware	---->	...
  48 * 	signal hw_done
  49 * 						switch to new state on next
  50 * 	...					v/hblank
  51 *
  52 *	wait for buffers to show up		...
  53 *
  54 *	...					send completion irq
  55 *						irq handler signals flip_done
  56 *	cleanup old buffers
  57 *
  58 * 	signal cleanup_done
  59 *
  60 * 	wait for flip_done		<----
  61 * 	clean up atomic state
  62 *
  63 * The important bit to know is that &cleanup_done is the terminal event, but the
  64 * ordering between &flip_done and &hw_done is entirely up to the specific driver
  65 * and modeset state change.
  66 *
  67 * For an implementation of how to use this look at
  68 * drm_atomic_helper_setup_commit() from the atomic helper library.
  69 *
  70 * See also drm_crtc_commit_wait().
  71 */
  72struct drm_crtc_commit {
  73	/**
  74	 * @crtc:
  75	 *
  76	 * DRM CRTC for this commit.
  77	 */
  78	struct drm_crtc *crtc;
  79
  80	/**
  81	 * @ref:
  82	 *
  83	 * Reference count for this structure. Needed to allow blocking on
  84	 * completions without the risk of the completion disappearing
  85	 * meanwhile.
  86	 */
  87	struct kref ref;
  88
  89	/**
  90	 * @flip_done:
  91	 *
  92	 * Will be signaled when the hardware has flipped to the new set of
  93	 * buffers. Signals at the same time as when the drm event for this
  94	 * commit is sent to userspace, or when an out-fence is singalled. Note
  95	 * that for most hardware, in most cases this happens after @hw_done is
  96	 * signalled.
  97	 *
  98	 * Completion of this stage is signalled implicitly by calling
  99	 * drm_crtc_send_vblank_event() on &drm_crtc_state.event.
 100	 */
 101	struct completion flip_done;
 102
 103	/**
 104	 * @hw_done:
 105	 *
 106	 * Will be signalled when all hw register changes for this commit have
 107	 * been written out. Especially when disabling a pipe this can be much
 108	 * later than @flip_done, since that can signal already when the
 109	 * screen goes black, whereas to fully shut down a pipe more register
 110	 * I/O is required.
 111	 *
 112	 * Note that this does not need to include separately reference-counted
 113	 * resources like backing storage buffer pinning, or runtime pm
 114	 * management.
 115	 *
 116	 * Drivers should call drm_atomic_helper_commit_hw_done() to signal
 117	 * completion of this stage.
 118	 */
 119	struct completion hw_done;
 120
 121	/**
 122	 * @cleanup_done:
 123	 *
 124	 * Will be signalled after old buffers have been cleaned up by calling
 125	 * drm_atomic_helper_cleanup_planes(). Since this can only happen after
 126	 * a vblank wait completed it might be a bit later. This completion is
 127	 * useful to throttle updates and avoid hardware updates getting ahead
 128	 * of the buffer cleanup too much.
 129	 *
 130	 * Drivers should call drm_atomic_helper_commit_cleanup_done() to signal
 131	 * completion of this stage.
 132	 */
 133	struct completion cleanup_done;
 134
 135	/**
 136	 * @commit_entry:
 137	 *
 138	 * Entry on the per-CRTC &drm_crtc.commit_list. Protected by
 139	 * $drm_crtc.commit_lock.
 140	 */
 141	struct list_head commit_entry;
 142
 143	/**
 144	 * @event:
 145	 *
 146	 * &drm_pending_vblank_event pointer to clean up private events.
 147	 */
 148	struct drm_pending_vblank_event *event;
 149
 150	/**
 151	 * @abort_completion:
 152	 *
 153	 * A flag that's set after drm_atomic_helper_setup_commit() takes a
 154	 * second reference for the completion of $drm_crtc_state.event. It's
 155	 * used by the free code to remove the second reference if commit fails.
 156	 */
 157	bool abort_completion;
 158};
 159
 160struct __drm_colorops_state {
 161	struct drm_colorop *ptr;
 162	struct drm_colorop_state *state, *old_state, *new_state;
 163};
 164
 165struct __drm_planes_state {
 166	struct drm_plane *ptr;
 167
 168	/**
 169	 * @state_to_destroy:
 170	 *
 171	 * Used to track the @drm_plane_state we will need to free when
 172	 * tearing down the associated &drm_atomic_state in
 173	 * $drm_mode_config_funcs.atomic_state_clear or
 174	 * drm_atomic_state_default_clear().
 175	 *
 176	 * Before a commit, and the call to
 177	 * drm_atomic_helper_swap_state() in particular, it points to
 178	 * the same state than @new_state. After a commit, it points to
 179	 * the same state than @old_state.
 180	 */
 181	struct drm_plane_state *state_to_destroy;
 182
 183	struct drm_plane_state *old_state, *new_state;
 184};
 185
 186struct __drm_crtcs_state {
 187	struct drm_crtc *ptr;
 188
 189	/**
 190	 * @state_to_destroy:
 191	 *
 192	 * Used to track the @drm_crtc_state we will need to free when
 193	 * tearing down the associated &drm_atomic_state in
 194	 * $drm_mode_config_funcs.atomic_state_clear or
 195	 * drm_atomic_state_default_clear().
 196	 *
 197	 * Before a commit, and the call to
 198	 * drm_atomic_helper_swap_state() in particular, it points to
 199	 * the same state than @new_state. After a commit, it points to
 200	 * the same state than @old_state.
 201	 */
 202	struct drm_crtc_state *state_to_destroy;
 203
 204	struct drm_crtc_state *old_state, *new_state;
 205
 206	/**
 207	 * @commit:
 208	 *
 209	 * A reference to the CRTC commit object that is kept for use by
 210	 * drm_atomic_helper_wait_for_flip_done() after
 211	 * drm_atomic_helper_commit_hw_done() is called. This ensures that a
 212	 * concurrent commit won't free a commit object that is still in use.
 213	 */
 214	struct drm_crtc_commit *commit;
 215
 216	s32 __user *out_fence_ptr;
 217	u64 last_vblank_count;
 218};
 219
 220struct __drm_connnectors_state {
 221	struct drm_connector *ptr;
 222
 223	/**
 224	 * @state_to_destroy:
 225	 *
 226	 * Used to track the @drm_connector_state we will need to free
 227	 * when tearing down the associated &drm_atomic_state in
 228	 * $drm_mode_config_funcs.atomic_state_clear or
 229	 * drm_atomic_state_default_clear().
 230	 *
 231	 * Before a commit, and the call to
 232	 * drm_atomic_helper_swap_state() in particular, it points to
 233	 * the same state than @new_state. After a commit, it points to
 234	 * the same state than @old_state.
 235	 */
 236	struct drm_connector_state *state_to_destroy;
 237
 238	struct drm_connector_state *old_state, *new_state;
 239
 240	/**
 241	 * @out_fence_ptr:
 242	 *
 243	 * User-provided pointer which the kernel uses to return a sync_file
 244	 * file descriptor. Used by writeback connectors to signal completion of
 245	 * the writeback.
 246	 */
 247	s32 __user *out_fence_ptr;
 248};
 249
 250struct drm_private_obj;
 251struct drm_private_state;
 252
 253/**
 254 * struct drm_private_state_funcs - atomic state functions for private objects
 255 *
 256 * These hooks are used by atomic helpers to create, swap and destroy states of
 257 * private objects. The structure itself is used as a vtable to identify the
 258 * associated private object type. Each private object type that needs to be
 259 * added to the atomic states is expected to have an implementation of these
 260 * hooks and pass a pointer to its drm_private_state_funcs struct to
 261 * drm_atomic_get_private_obj_state().
 262 */
 263struct drm_private_state_funcs {
 264	/**
 265	 * @atomic_duplicate_state:
 266	 *
 267	 * Duplicate the current state of the private object and return it. It
 268	 * is an error to call this before obj->state has been initialized.
 269	 *
 270	 * RETURNS:
 271	 *
 272	 * Duplicated atomic state or NULL when obj->state is not
 273	 * initialized or allocation failed.
 274	 */
 275	struct drm_private_state *(*atomic_duplicate_state)(struct drm_private_obj *obj);
 276
 277	/**
 278	 * @atomic_destroy_state:
 279	 *
 280	 * Frees the private object state created with @atomic_duplicate_state.
 281	 */
 282	void (*atomic_destroy_state)(struct drm_private_obj *obj,
 283				     struct drm_private_state *state);
 284
 285	/**
 286	 * @atomic_print_state:
 287	 *
 288	 * If driver subclasses &struct drm_private_state, it should implement
 289	 * this optional hook for printing additional driver specific state.
 290	 *
 291	 * Do not call this directly, use drm_atomic_private_obj_print_state()
 292	 * instead.
 293	 */
 294	void (*atomic_print_state)(struct drm_printer *p,
 295				   const struct drm_private_state *state);
 296};
 297
 298/**
 299 * struct drm_private_obj - base struct for driver private atomic object
 300 *
 301 * A driver private object is initialized by calling
 302 * drm_atomic_private_obj_init() and cleaned up by calling
 303 * drm_atomic_private_obj_fini().
 304 *
 305 * Currently only tracks the state update functions and the opaque driver
 306 * private state itself, but in the future might also track which
 307 * &drm_modeset_lock is required to duplicate and update this object's state.
 308 *
 309 * All private objects must be initialized before the DRM device they are
 310 * attached to is registered to the DRM subsystem (call to drm_dev_register())
 311 * and should stay around until this DRM device is unregistered (call to
 312 * drm_dev_unregister()). In other words, private objects lifetime is tied
 313 * to the DRM device lifetime. This implies that:
 314 *
 315 * 1/ all calls to drm_atomic_private_obj_init() must be done before calling
 316 *    drm_dev_register()
 317 * 2/ all calls to drm_atomic_private_obj_fini() must be done after calling
 318 *    drm_dev_unregister()
 319 *
 320 * If that private object is used to store a state shared by multiple
 321 * CRTCs, proper care must be taken to ensure that non-blocking commits are
 322 * properly ordered to avoid a use-after-free issue.
 323 *
 324 * Indeed, assuming a sequence of two non-blocking &drm_atomic_commit on two
 325 * different &drm_crtc using different &drm_plane and &drm_connector, so with no
 326 * resources shared, there's no guarantee on which commit is going to happen
 327 * first. However, the second &drm_atomic_commit will consider the first
 328 * &drm_private_obj its old state, and will be in charge of freeing it whenever
 329 * the second &drm_atomic_commit is done.
 330 *
 331 * If the first &drm_atomic_commit happens after it, it will consider its
 332 * &drm_private_obj the new state and will be likely to access it, resulting in
 333 * an access to a freed memory region. Drivers should store (and get a reference
 334 * to) the &drm_crtc_commit structure in our private state in
 335 * &drm_mode_config_helper_funcs.atomic_commit_setup, and then wait for that
 336 * commit to complete as the first step of
 337 * &drm_mode_config_helper_funcs.atomic_commit_tail, similar to
 338 * drm_atomic_helper_wait_for_dependencies().
 339 */
 340struct drm_private_obj {
 341	/**
 342	 * @head: List entry used to attach a private object to a &drm_device
 343	 * (queued to &drm_mode_config.privobj_list).
 344	 */
 345	struct list_head head;
 346
 347	/**
 348	 * @lock: Modeset lock to protect the state object.
 349	 */
 350	struct drm_modeset_lock lock;
 351
 352	/**
 353	 * @state: Current atomic state for this driver private object.
 354	 */
 355	struct drm_private_state *state;
 356
 357	/**
 358	 * @funcs:
 359	 *
 360	 * Functions to manipulate the state of this driver private object, see
 361	 * &drm_private_state_funcs.
 362	 */
 363	const struct drm_private_state_funcs *funcs;
 364};
 365
 366/**
 367 * drm_for_each_privobj() - private object iterator
 368 *
 369 * @privobj: pointer to the current private object. Updated after each
 370 *	     iteration
 371 * @dev: the DRM device we want get private objects from
 372 *
 373 * Allows one to iterate over all private objects attached to @dev
 374 */
 375#define drm_for_each_privobj(privobj, dev) \
 376	list_for_each_entry(privobj, &(dev)->mode_config.privobj_list, head)
 377
 378/**
 379 * struct drm_private_state - base struct for driver private object state
 380 *
 381 * Currently only contains a backpointer to the overall atomic update,
 382 * and the relevant private object but in the future also might hold
 383 * synchronization information similar to e.g. &drm_crtc.commit.
 384 */
 385struct drm_private_state {
 386	/**
 387	 * @state: backpointer to global drm_atomic_state
 388	 */
 389	struct drm_atomic_state *state;
 390
 391	/**
 392	 * @obj: backpointer to the private object
 393	 */
 394	struct drm_private_obj *obj;
 395};
 396
 397struct __drm_private_objs_state {
 398	struct drm_private_obj *ptr;
 399
 400	/**
 401	 * @state_to_destroy:
 402	 *
 403	 * Used to track the @drm_private_state we will need to free
 404	 * when tearing down the associated &drm_atomic_state in
 405	 * $drm_mode_config_funcs.atomic_state_clear or
 406	 * drm_atomic_state_default_clear().
 407	 *
 408	 * Before a commit, and the call to
 409	 * drm_atomic_helper_swap_state() in particular, it points to
 410	 * the same state than @new_state. After a commit, it points to
 411	 * the same state than @old_state.
 412	 */
 413	struct drm_private_state *state_to_destroy;
 414
 415	struct drm_private_state *old_state, *new_state;
 416};
 417
 418/**
 419 * struct drm_atomic_state - Atomic commit structure
 420 *
 421 * This structure is the kernel counterpart of @drm_mode_atomic and represents
 422 * an atomic commit that transitions from an old to a new display state. It
 423 * contains all the objects affected by the atomic commit and both the new
 424 * state structures and pointers to the old state structures for
 425 * these.
 426 *
 427 * States are added to an atomic update by calling drm_atomic_get_crtc_state(),
 428 * drm_atomic_get_plane_state(), drm_atomic_get_connector_state(), or for
 429 * private state structures, drm_atomic_get_private_obj_state().
 430 *
 431 * NOTE: struct drm_atomic_state first started as a single collection of
 432 * entities state pointers (drm_plane_state, drm_crtc_state, etc.).
 433 *
 434 * At atomic_check time, you could get the state about to be committed
 435 * from drm_atomic_state, and the one currently running from the
 436 * entities state pointer (drm_crtc.state, for example). After the call
 437 * to drm_atomic_helper_swap_state(), the entities state pointer would
 438 * contain the state previously checked, and the drm_atomic_state
 439 * structure the old state.
 440 *
 441 * Over time, and in order to avoid confusion, drm_atomic_state has
 442 * grown to have both the old state (ie, the state we replace) and the
 443 * new state (ie, the state we want to apply). Those names are stable
 444 * during the commit process, which makes it easier to reason about.
 445 *
 446 * You can still find some traces of that evolution through some hooks
 447 * or callbacks taking a drm_atomic_state parameter called names like
 448 * "old_state". This doesn't necessarily mean that the previous
 449 * drm_atomic_state is passed, but rather that this used to be the state
 450 * collection we were replacing after drm_atomic_helper_swap_state(),
 451 * but the variable name was never updated.
 452 *
 453 * Some atomic operations implementations followed a similar process. We
 454 * first started to pass the entity state only. However, it was pretty
 455 * cumbersome for drivers, and especially CRTCs, to retrieve the states
 456 * of other components. Thus, we switched to passing the whole
 457 * drm_atomic_state as a parameter to those operations. Similarly, the
 458 * transition isn't complete yet, and one might still find atomic
 459 * operations taking a drm_atomic_state pointer, or a component state
 460 * pointer. The former is the preferred form.
 461 */
 462struct drm_atomic_state {
 463	/**
 464	 * @ref:
 465	 *
 466	 * Count of all references to this update (will not be freed until zero).
 467	 */
 468	struct kref ref;
 469
 470	/**
 471	 * @dev: Parent DRM Device.
 472	 */
 473	struct drm_device *dev;
 474
 475	/**
 476	 * @allow_modeset:
 477	 *
 478	 * Allow full modeset. This is used by the ATOMIC IOCTL handler to
 479	 * implement the DRM_MODE_ATOMIC_ALLOW_MODESET flag. Drivers should
 480	 * generally not consult this flag, but instead look at the output of
 481	 * drm_atomic_crtc_needs_modeset(). The detailed rules are:
 482	 *
 483	 * - Drivers must not consult @allow_modeset in the atomic commit path.
 484	 *   Use drm_atomic_crtc_needs_modeset() instead.
 485	 *
 486	 * - Drivers must consult @allow_modeset before adding unrelated struct
 487	 *   drm_crtc_state to this commit by calling
 488	 *   drm_atomic_get_crtc_state(). See also the warning in the
 489	 *   documentation for that function.
 490	 *
 491	 * - Drivers must never change this flag, it is under the exclusive
 492	 *   control of userspace.
 493	 *
 494	 * - Drivers may consult @allow_modeset in the atomic check path, if
 495	 *   they have the choice between an optimal hardware configuration
 496	 *   which requires a modeset, and a less optimal configuration which
 497	 *   can be committed without a modeset. An example would be suboptimal
 498	 *   scanout FIFO allocation resulting in increased idle power
 499	 *   consumption. This allows userspace to avoid flickering and delays
 500	 *   for the normal composition loop at reasonable cost.
 501	 */
 502	bool allow_modeset : 1;
 503	/**
 504	 * @legacy_cursor_update:
 505	 *
 506	 * Hint to enforce legacy cursor IOCTL semantics.
 507	 *
 508	 * WARNING: This is thoroughly broken and pretty much impossible to
 509	 * implement correctly. Drivers must ignore this and should instead
 510	 * implement &drm_plane_helper_funcs.atomic_async_check and
 511	 * &drm_plane_helper_funcs.atomic_async_commit hooks. New users of this
 512	 * flag are not allowed.
 513	 */
 514	bool legacy_cursor_update : 1;
 515
 516	/**
 517	 * @async_update: hint for asynchronous plane update
 518	 */
 519	bool async_update : 1;
 520
 521	/**
 522	 * @duplicated:
 523	 *
 524	 * Indicates whether or not this atomic state was duplicated using
 525	 * drm_atomic_helper_duplicate_state(). Drivers and atomic helpers
 526	 * should use this to fixup normal  inconsistencies in duplicated
 527	 * states.
 528	 */
 529	bool duplicated : 1;
 530
 531	/**
 532	 * @checked:
 533	 *
 534	 * Indicates the state has been checked and thus must no longer
 535	 * be mutated. For internal use only, do not consult from drivers.
 536	 */
 537	bool checked : 1;
 538
 539	/**
 540	 * @plane_color_pipeline:
 541	 *
 542	 * Indicates whether this atomic state originated with a client that
 543	 * set the DRM_CLIENT_CAP_PLANE_COLOR_PIPELINE.
 544	 *
 545	 * Drivers and helper functions should use this to ignore legacy
 546	 * properties that are incompatible with the drm_plane COLOR_PIPELINE
 547	 * behavior, such as:
 548	 *
 549	 *  - COLOR_RANGE
 550	 *  - COLOR_ENCODING
 551	 *
 552	 * or any other driver-specific properties that might affect pixel
 553	 * values.
 554	 */
 555	bool plane_color_pipeline : 1;
 556
 557	/**
 558	 * @colorops:
 559	 *
 560	 * Pointer to array of @drm_colorop and @drm_colorop_state part of this
 561	 * update.
 562	 */
 563	struct __drm_colorops_state *colorops;
 564
 565	/**
 566	 * @planes:
 567	 *
 568	 * Pointer to array of @drm_plane and @drm_plane_state part of this
 569	 * update.
 570	 */
 571	struct __drm_planes_state *planes;
 572
 573	/**
 574	 * @crtcs:
 575	 *
 576	 * Pointer to array of @drm_crtc and @drm_crtc_state part of this
 577	 * update.
 578	 */
 579	struct __drm_crtcs_state *crtcs;
 580
 581	/**
 582	 * @num_connector: size of the @connectors array
 583	 */
 584	int num_connector;
 585
 586	/**
 587	 * @connectors:
 588	 *
 589	 * Pointer to array of @drm_connector and @drm_connector_state part of
 590	 * this update.
 591	 */
 592	struct __drm_connnectors_state *connectors;
 593
 594	/**
 595	 * @num_private_objs: size of the @private_objs array
 596	 */
 597	int num_private_objs;
 598
 599	/**
 600	 * @private_objs:
 601	 *
 602	 * Pointer to array of @drm_private_obj and @drm_private_obj_state part
 603	 * of this update.
 604	 */
 605	struct __drm_private_objs_state *private_objs;
 606
 607	/**
 608	 * @acquire_ctx: acquire context for this atomic modeset state update
 609	 */
 610	struct drm_modeset_acquire_ctx *acquire_ctx;
 611
 612	/**
 613	 * @fake_commit:
 614	 *
 615	 * Used for signaling unbound planes/connectors.
 616	 * When a connector or plane is not bound to any CRTC, it's still important
 617	 * to preserve linearity to prevent the atomic states from being freed too early.
 618	 *
 619	 * This commit (if set) is not bound to any CRTC, but will be completed when
 620	 * drm_atomic_helper_commit_hw_done() is called.
 621	 */
 622	struct drm_crtc_commit *fake_commit;
 623
 624	/**
 625	 * @commit_work:
 626	 *
 627	 * Work item which can be used by the driver or helpers to execute the
 628	 * commit without blocking.
 629	 */
 630	struct work_struct commit_work;
 631};
 632
 633void __drm_crtc_commit_free(struct kref *kref);
 634
 635/**
 636 * drm_crtc_commit_get - acquire a reference to the CRTC commit
 637 * @commit: CRTC commit
 638 *
 639 * Increases the reference of @commit.
 640 *
 641 * Returns:
 642 * The pointer to @commit, with reference increased.
 643 */
 644static inline struct drm_crtc_commit *drm_crtc_commit_get(struct drm_crtc_commit *commit)
 645{
 646	kref_get(&commit->ref);
 647	return commit;
 648}
 649
 650/**
 651 * drm_crtc_commit_put - release a reference to the CRTC commmit
 652 * @commit: CRTC commit
 653 *
 654 * This releases a reference to @commit which is freed after removing the
 655 * final reference. No locking required and callable from any context.
 656 */
 657static inline void drm_crtc_commit_put(struct drm_crtc_commit *commit)
 658{
 659	kref_put(&commit->ref, __drm_crtc_commit_free);
 660}
 661
 662int drm_crtc_commit_wait(struct drm_crtc_commit *commit);
 663
 664struct drm_atomic_state * __must_check
 665drm_atomic_state_alloc(struct drm_device *dev);
 666void drm_atomic_state_clear(struct drm_atomic_state *state);
 667
 668/**
 669 * drm_atomic_state_get - acquire a reference to the atomic state
 670 * @state: The atomic state
 671 *
 672 * Returns a new reference to the @state
 673 */
 674static inline struct drm_atomic_state *
 675drm_atomic_state_get(struct drm_atomic_state *state)
 676{
 677	kref_get(&state->ref);
 678	return state;
 679}
 680
 681void __drm_atomic_state_free(struct kref *ref);
 682
 683/**
 684 * drm_atomic_state_put - release a reference to the atomic state
 685 * @state: The atomic state
 686 *
 687 * This releases a reference to @state which is freed after removing the
 688 * final reference. No locking required and callable from any context.
 689 */
 690static inline void drm_atomic_state_put(struct drm_atomic_state *state)
 691{
 692	kref_put(&state->ref, __drm_atomic_state_free);
 693}
 694
 695int  __must_check
 696drm_atomic_state_init(struct drm_device *dev, struct drm_atomic_state *state);
 697void drm_atomic_state_default_clear(struct drm_atomic_state *state);
 698void drm_atomic_state_default_release(struct drm_atomic_state *state);
 699
 700struct drm_crtc_state * __must_check
 701drm_atomic_get_crtc_state(struct drm_atomic_state *state,
 702			  struct drm_crtc *crtc);
 703struct drm_plane_state * __must_check
 704drm_atomic_get_plane_state(struct drm_atomic_state *state,
 705			   struct drm_plane *plane);
 706struct drm_colorop_state *
 707drm_atomic_get_colorop_state(struct drm_atomic_state *state,
 708			     struct drm_colorop *colorop);
 709
 710struct drm_colorop_state *
 711drm_atomic_get_old_colorop_state(struct drm_atomic_state *state,
 712				 struct drm_colorop *colorop);
 713struct drm_colorop_state *
 714drm_atomic_get_new_colorop_state(struct drm_atomic_state *state,
 715				 struct drm_colorop *colorop);
 716
 717struct drm_connector_state * __must_check
 718drm_atomic_get_connector_state(struct drm_atomic_state *state,
 719			       struct drm_connector *connector);
 720
 721void drm_atomic_private_obj_init(struct drm_device *dev,
 722				 struct drm_private_obj *obj,
 723				 struct drm_private_state *state,
 724				 const struct drm_private_state_funcs *funcs);
 725void drm_atomic_private_obj_fini(struct drm_private_obj *obj);
 726
 727struct drm_private_state * __must_check
 728drm_atomic_get_private_obj_state(struct drm_atomic_state *state,
 729				 struct drm_private_obj *obj);
 730struct drm_private_state *
 731drm_atomic_get_old_private_obj_state(const struct drm_atomic_state *state,
 732				     struct drm_private_obj *obj);
 733struct drm_private_state *
 734drm_atomic_get_new_private_obj_state(const struct drm_atomic_state *state,
 735				     struct drm_private_obj *obj);
 736
 737struct drm_connector *
 738drm_atomic_get_old_connector_for_encoder(const struct drm_atomic_state *state,
 739					 struct drm_encoder *encoder);
 740struct drm_connector *
 741drm_atomic_get_new_connector_for_encoder(const struct drm_atomic_state *state,
 742					 struct drm_encoder *encoder);
 743struct drm_connector *
 744drm_atomic_get_connector_for_encoder(const struct drm_encoder *encoder,
 745				     struct drm_modeset_acquire_ctx *ctx);
 746
 747struct drm_crtc *
 748drm_atomic_get_old_crtc_for_encoder(struct drm_atomic_state *state,
 749					 struct drm_encoder *encoder);
 750struct drm_crtc *
 751drm_atomic_get_new_crtc_for_encoder(struct drm_atomic_state *state,
 752					 struct drm_encoder *encoder);
 753
 754/**
 755 * drm_atomic_get_old_crtc_state - get old CRTC state, if it exists
 756 * @state: global atomic state object
 757 * @crtc: CRTC to grab
 758 *
 759 * This function returns the old CRTC state for the given CRTC, or
 760 * NULL if the CRTC is not part of the global atomic state.
 761 */
 762static inline struct drm_crtc_state *
 763drm_atomic_get_old_crtc_state(const struct drm_atomic_state *state,
 764			      struct drm_crtc *crtc)
 765{
 766	return state->crtcs[drm_crtc_index(crtc)].old_state;
 767}
 768/**
 769 * drm_atomic_get_new_crtc_state - get new CRTC state, if it exists
 770 * @state: global atomic state object
 771 * @crtc: CRTC to grab
 772 *
 773 * This function returns the new CRTC state for the given CRTC, or
 774 * NULL if the CRTC is not part of the global atomic state.
 775 */
 776static inline struct drm_crtc_state *
 777drm_atomic_get_new_crtc_state(const struct drm_atomic_state *state,
 778			      struct drm_crtc *crtc)
 779{
 780	return state->crtcs[drm_crtc_index(crtc)].new_state;
 781}
 782
 783/**
 784 * drm_atomic_get_old_plane_state - get plane state, if it exists
 785 * @state: global atomic state object
 786 * @plane: plane to grab
 787 *
 788 * This function returns the old plane state for the given plane, or
 789 * NULL if the plane is not part of the global atomic state.
 790 */
 791static inline struct drm_plane_state *
 792drm_atomic_get_old_plane_state(const struct drm_atomic_state *state,
 793			       struct drm_plane *plane)
 794{
 795	return state->planes[drm_plane_index(plane)].old_state;
 796}
 797
 798/**
 799 * drm_atomic_get_new_plane_state - get plane state, if it exists
 800 * @state: global atomic state object
 801 * @plane: plane to grab
 802 *
 803 * This function returns the new plane state for the given plane, or
 804 * NULL if the plane is not part of the global atomic state.
 805 */
 806static inline struct drm_plane_state *
 807drm_atomic_get_new_plane_state(const struct drm_atomic_state *state,
 808			       struct drm_plane *plane)
 809{
 810	return state->planes[drm_plane_index(plane)].new_state;
 811}
 812
 813/**
 814 * drm_atomic_get_old_connector_state - get connector state, if it exists
 815 * @state: global atomic state object
 816 * @connector: connector to grab
 817 *
 818 * This function returns the old connector state for the given connector,
 819 * or NULL if the connector is not part of the global atomic state.
 820 */
 821static inline struct drm_connector_state *
 822drm_atomic_get_old_connector_state(const struct drm_atomic_state *state,
 823				   struct drm_connector *connector)
 824{
 825	int index = drm_connector_index(connector);
 826
 827	if (index >= state->num_connector)
 828		return NULL;
 829
 830	return state->connectors[index].old_state;
 831}
 832
 833/**
 834 * drm_atomic_get_new_connector_state - get connector state, if it exists
 835 * @state: global atomic state object
 836 * @connector: connector to grab
 837 *
 838 * This function returns the new connector state for the given connector,
 839 * or NULL if the connector is not part of the global atomic state.
 840 */
 841static inline struct drm_connector_state *
 842drm_atomic_get_new_connector_state(const struct drm_atomic_state *state,
 843				   struct drm_connector *connector)
 844{
 845	int index = drm_connector_index(connector);
 846
 847	if (index >= state->num_connector)
 848		return NULL;
 849
 850	return state->connectors[index].new_state;
 851}
 852
 853/**
 854 * __drm_atomic_get_current_plane_state - get current plane state
 855 * @state: global atomic state object
 856 * @plane: plane to grab
 857 *
 858 * This function returns the plane state for the given plane, either the
 859 * new plane state from @state, or if the plane isn't part of the atomic
 860 * state update, from @plane. This is useful in atomic check callbacks,
 861 * when drivers need to peek at, but not change, state of other planes,
 862 * since it avoids threading an error code back up the call chain.
 863 *
 864 * WARNING:
 865 *
 866 * Note that this function is in general unsafe since it doesn't check for the
 867 * required locking for access state structures. Drivers must ensure that it is
 868 * safe to access the returned state structure through other means. One common
 869 * example is when planes are fixed to a single CRTC, and the driver knows that
 870 * the CRTC lock is held already. In that case holding the CRTC lock gives a
 871 * read-lock on all planes connected to that CRTC. But if planes can be
 872 * reassigned things get more tricky. In that case it's better to use
 873 * drm_atomic_get_plane_state and wire up full error handling.
 874 *
 875 * Returns:
 876 *
 877 * Read-only pointer to the current plane state.
 878 */
 879static inline const struct drm_plane_state *
 880__drm_atomic_get_current_plane_state(const struct drm_atomic_state *state,
 881				     struct drm_plane *plane)
 882{
 883	struct drm_plane_state *plane_state;
 884
 885	plane_state = drm_atomic_get_new_plane_state(state, plane);
 886	if (plane_state)
 887		return plane_state;
 888
 889	/*
 890	 * If the plane isn't part of the state, fallback to the currently active one.
 891	 */
 892	return plane->state;
 893}
 894
 895int __must_check
 896drm_atomic_add_encoder_bridges(struct drm_atomic_state *state,
 897			       struct drm_encoder *encoder);
 898int __must_check
 899drm_atomic_add_affected_connectors(struct drm_atomic_state *state,
 900				   struct drm_crtc *crtc);
 901int __must_check
 902drm_atomic_add_affected_planes(struct drm_atomic_state *state,
 903			       struct drm_crtc *crtc);
 904int __must_check
 905drm_atomic_add_affected_colorops(struct drm_atomic_state *state,
 906				 struct drm_plane *plane);
 907
 908int __must_check drm_atomic_check_only(struct drm_atomic_state *state);
 909int __must_check drm_atomic_commit(struct drm_atomic_state *state);
 910int __must_check drm_atomic_nonblocking_commit(struct drm_atomic_state *state);
 911
 912void drm_state_dump(struct drm_device *dev, struct drm_printer *p);
 913
 914/**
 915 * for_each_oldnew_connector_in_state - iterate over all connectors in an atomic update
 916 * @__state: &struct drm_atomic_state pointer
 917 * @connector: &struct drm_connector iteration cursor
 918 * @old_connector_state: &struct drm_connector_state iteration cursor for the
 919 * 	old state
 920 * @new_connector_state: &struct drm_connector_state iteration cursor for the
 921 * 	new state
 922 * @__i: int iteration cursor, for macro-internal use
 923 *
 924 * This iterates over all connectors in an atomic update, tracking both old and
 925 * new state. This is useful in places where the state delta needs to be
 926 * considered, for example in atomic check functions.
 927 */
 928#define for_each_oldnew_connector_in_state(__state, connector, old_connector_state, new_connector_state, __i) \
 929	for ((__i) = 0;								\
 930	     (__i) < (__state)->num_connector;					\
 931	     (__i)++)								\
 932		for_each_if ((__state)->connectors[__i].ptr &&			\
 933			     ((connector) = (__state)->connectors[__i].ptr,	\
 934			     (void)(connector) /* Only to avoid unused-but-set-variable warning */, \
 935			     (old_connector_state) = (__state)->connectors[__i].old_state,	\
 936			     (new_connector_state) = (__state)->connectors[__i].new_state, 1))
 937
 938/**
 939 * for_each_old_connector_in_state - iterate over all connectors in an atomic update
 940 * @__state: &struct drm_atomic_state pointer
 941 * @connector: &struct drm_connector iteration cursor
 942 * @old_connector_state: &struct drm_connector_state iteration cursor for the
 943 * 	old state
 944 * @__i: int iteration cursor, for macro-internal use
 945 *
 946 * This iterates over all connectors in an atomic update, tracking only the old
 947 * state. This is useful in disable functions, where we need the old state the
 948 * hardware is still in.
 949 */
 950#define for_each_old_connector_in_state(__state, connector, old_connector_state, __i) \
 951	for ((__i) = 0;								\
 952	     (__i) < (__state)->num_connector;					\
 953	     (__i)++)								\
 954		for_each_if ((__state)->connectors[__i].ptr &&			\
 955			     ((connector) = (__state)->connectors[__i].ptr,	\
 956			     (void)(connector) /* Only to avoid unused-but-set-variable warning */, \
 957			     (old_connector_state) = (__state)->connectors[__i].old_state, 1))
 958
 959/**
 960 * for_each_new_connector_in_state - iterate over all connectors in an atomic update
 961 * @__state: &struct drm_atomic_state pointer
 962 * @connector: &struct drm_connector iteration cursor
 963 * @new_connector_state: &struct drm_connector_state iteration cursor for the
 964 * 	new state
 965 * @__i: int iteration cursor, for macro-internal use
 966 *
 967 * This iterates over all connectors in an atomic update, tracking only the new
 968 * state. This is useful in enable functions, where we need the new state the
 969 * hardware should be in when the atomic commit operation has completed.
 970 */
 971#define for_each_new_connector_in_state(__state, connector, new_connector_state, __i) \
 972	for ((__i) = 0;								\
 973	     (__i) < (__state)->num_connector;					\
 974	     (__i)++)								\
 975		for_each_if ((__state)->connectors[__i].ptr &&			\
 976			     ((connector) = (__state)->connectors[__i].ptr,	\
 977			     (void)(connector) /* Only to avoid unused-but-set-variable warning */, \
 978			     (new_connector_state) = (__state)->connectors[__i].new_state, \
 979			     (void)(new_connector_state) /* Only to avoid unused-but-set-variable warning */, 1))
 980
 981/**
 982 * for_each_oldnew_crtc_in_state - iterate over all CRTCs in an atomic update
 983 * @__state: &struct drm_atomic_state pointer
 984 * @crtc: &struct drm_crtc iteration cursor
 985 * @old_crtc_state: &struct drm_crtc_state iteration cursor for the old state
 986 * @new_crtc_state: &struct drm_crtc_state iteration cursor for the new state
 987 * @__i: int iteration cursor, for macro-internal use
 988 *
 989 * This iterates over all CRTCs in an atomic update, tracking both old and
 990 * new state. This is useful in places where the state delta needs to be
 991 * considered, for example in atomic check functions.
 992 */
 993#define for_each_oldnew_crtc_in_state(__state, crtc, old_crtc_state, new_crtc_state, __i) \
 994	for ((__i) = 0;							\
 995	     (__i) < (__state)->dev->mode_config.num_crtc;		\
 996	     (__i)++)							\
 997		for_each_if ((__state)->crtcs[__i].ptr &&		\
 998			     ((crtc) = (__state)->crtcs[__i].ptr,	\
 999			      (void)(crtc) /* Only to avoid unused-but-set-variable warning */, \
1000			     (old_crtc_state) = (__state)->crtcs[__i].old_state, \
1001			     (void)(old_crtc_state) /* Only to avoid unused-but-set-variable warning */, \
1002			     (new_crtc_state) = (__state)->crtcs[__i].new_state, \
1003			     (void)(new_crtc_state) /* Only to avoid unused-but-set-variable warning */, 1))
1004
1005/**
1006 * for_each_old_crtc_in_state - iterate over all CRTCs in an atomic update
1007 * @__state: &struct drm_atomic_state pointer
1008 * @crtc: &struct drm_crtc iteration cursor
1009 * @old_crtc_state: &struct drm_crtc_state iteration cursor for the old state
1010 * @__i: int iteration cursor, for macro-internal use
1011 *
1012 * This iterates over all CRTCs in an atomic update, tracking only the old
1013 * state. This is useful in disable functions, where we need the old state the
1014 * hardware is still in.
1015 */
1016#define for_each_old_crtc_in_state(__state, crtc, old_crtc_state, __i)	\
1017	for ((__i) = 0;							\
1018	     (__i) < (__state)->dev->mode_config.num_crtc;		\
1019	     (__i)++)							\
1020		for_each_if ((__state)->crtcs[__i].ptr &&		\
1021			     ((crtc) = (__state)->crtcs[__i].ptr,	\
1022			     (void)(crtc) /* Only to avoid unused-but-set-variable warning */, \
1023			     (old_crtc_state) = (__state)->crtcs[__i].old_state, 1))
1024
1025/**
1026 * for_each_new_crtc_in_state - iterate over all CRTCs in an atomic update
1027 * @__state: &struct drm_atomic_state pointer
1028 * @crtc: &struct drm_crtc iteration cursor
1029 * @new_crtc_state: &struct drm_crtc_state iteration cursor for the new state
1030 * @__i: int iteration cursor, for macro-internal use
1031 *
1032 * This iterates over all CRTCs in an atomic update, tracking only the new
1033 * state. This is useful in enable functions, where we need the new state the
1034 * hardware should be in when the atomic commit operation has completed.
1035 */
1036#define for_each_new_crtc_in_state(__state, crtc, new_crtc_state, __i)	\
1037	for ((__i) = 0;							\
1038	     (__i) < (__state)->dev->mode_config.num_crtc;		\
1039	     (__i)++)							\
1040		for_each_if ((__state)->crtcs[__i].ptr &&		\
1041			     ((crtc) = (__state)->crtcs[__i].ptr,	\
1042			     (void)(crtc) /* Only to avoid unused-but-set-variable warning */, \
1043			     (new_crtc_state) = (__state)->crtcs[__i].new_state, \
1044			     (void)(new_crtc_state) /* Only to avoid unused-but-set-variable warning */, 1))
1045
1046/**
1047 * for_each_oldnew_colorop_in_state - iterate over all colorops in an atomic update
1048 * @__state: &struct drm_atomic_state pointer
1049 * @colorop: &struct drm_colorop iteration cursor
1050 * @old_colorop_state: &struct drm_colorop_state iteration cursor for the old state
1051 * @new_colorop_state: &struct drm_colorop_state iteration cursor for the new state
1052 * @__i: int iteration cursor, for macro-internal use
1053 *
1054 * This iterates over all colorops in an atomic update, tracking both old and
1055 * new state. This is useful in places where the state delta needs to be
1056 * considered, for example in atomic check functions.
1057 */
1058#define for_each_oldnew_colorop_in_state(__state, colorop, old_colorop_state,	\
1059					 new_colorop_state, __i)		\
1060	for ((__i) = 0;								\
1061	     (__i) < (__state)->dev->mode_config.num_colorop;			\
1062	     (__i)++)								\
1063		for_each_if ((__state)->colorops[__i].ptr &&			\
1064			     ((colorop) = (__state)->colorops[__i].ptr,		\
1065			      (void)(colorop) /* Only to avoid unused-but-set-variable warning */, \
1066			      (old_colorop_state) = (__state)->colorops[__i].old_state,\
1067			      (new_colorop_state) = (__state)->colorops[__i].new_state, 1))
1068
1069/**
1070 * for_each_new_colorop_in_state - iterate over all colorops in an atomic update
1071 * @__state: &struct drm_atomic_state pointer
1072 * @colorop: &struct drm_colorop iteration cursor
1073 * @new_colorop_state: &struct drm_colorop_state iteration cursor for the new state
1074 * @__i: int iteration cursor, for macro-internal use
1075 *
1076 * This iterates over all colorops in an atomic update, tracking new state. This is
1077 * useful in places where the state delta needs to be considered, for example in
1078 * atomic check functions.
1079 */
1080#define for_each_new_colorop_in_state(__state, colorop, new_colorop_state, __i) \
1081	for ((__i) = 0;							\
1082	     (__i) < (__state)->dev->mode_config.num_colorop;		\
1083	     (__i)++)							\
1084		for_each_if ((__state)->colorops[__i].ptr &&		\
1085			     ((colorop) = (__state)->colorops[__i].ptr,	\
1086			      (void)(colorop) /* Only to avoid unused-but-set-variable warning */, \
1087			      (new_colorop_state) = (__state)->colorops[__i].new_state, 1))
1088
1089/**
1090 * for_each_oldnew_plane_in_state - iterate over all planes in an atomic update
1091 * @__state: &struct drm_atomic_state pointer
1092 * @plane: &struct drm_plane iteration cursor
1093 * @old_plane_state: &struct drm_plane_state iteration cursor for the old state
1094 * @new_plane_state: &struct drm_plane_state iteration cursor for the new state
1095 * @__i: int iteration cursor, for macro-internal use
1096 *
1097 * This iterates over all planes in an atomic update, tracking both old and
1098 * new state. This is useful in places where the state delta needs to be
1099 * considered, for example in atomic check functions.
1100 */
1101#define for_each_oldnew_plane_in_state(__state, plane, old_plane_state, new_plane_state, __i) \
1102	for ((__i) = 0;							\
1103	     (__i) < (__state)->dev->mode_config.num_total_plane;	\
1104	     (__i)++)							\
1105		for_each_if ((__state)->planes[__i].ptr &&		\
1106			     ((plane) = (__state)->planes[__i].ptr,	\
1107			      (void)(plane) /* Only to avoid unused-but-set-variable warning */, \
1108			      (old_plane_state) = (__state)->planes[__i].old_state,\
1109			      (new_plane_state) = (__state)->planes[__i].new_state, 1))
1110
1111/**
1112 * for_each_oldnew_plane_in_state_reverse - iterate over all planes in an atomic
1113 * update in reverse order
1114 * @__state: &struct drm_atomic_state pointer
1115 * @plane: &struct drm_plane iteration cursor
1116 * @old_plane_state: &struct drm_plane_state iteration cursor for the old state
1117 * @new_plane_state: &struct drm_plane_state iteration cursor for the new state
1118 * @__i: int iteration cursor, for macro-internal use
1119 *
1120 * This iterates over all planes in an atomic update in reverse order,
1121 * tracking both old and  new state. This is useful in places where the
1122 * state delta needs to be considered, for example in atomic check functions.
1123 */
1124#define for_each_oldnew_plane_in_state_reverse(__state, plane, old_plane_state, new_plane_state, __i) \
1125	for ((__i) = ((__state)->dev->mode_config.num_total_plane - 1);	\
1126	     (__i) >= 0;						\
1127	     (__i)--)							\
1128		for_each_if ((__state)->planes[__i].ptr &&		\
1129			     ((plane) = (__state)->planes[__i].ptr,	\
1130			      (old_plane_state) = (__state)->planes[__i].old_state,\
1131			      (new_plane_state) = (__state)->planes[__i].new_state, 1))
1132
1133/**
1134 * for_each_new_plane_in_state_reverse - other than only tracking new state,
1135 * it's the same as for_each_oldnew_plane_in_state_reverse
1136 * @__state: &struct drm_atomic_state pointer
1137 * @plane: &struct drm_plane iteration cursor
1138 * @new_plane_state: &struct drm_plane_state iteration cursor for the new state
1139 * @__i: int iteration cursor, for macro-internal use
1140 */
1141#define for_each_new_plane_in_state_reverse(__state, plane, new_plane_state, __i) \
1142	for ((__i) = ((__state)->dev->mode_config.num_total_plane - 1);	\
1143	     (__i) >= 0;						\
1144	     (__i)--)							\
1145		for_each_if ((__state)->planes[__i].ptr &&		\
1146			     ((plane) = (__state)->planes[__i].ptr,	\
1147			      (new_plane_state) = (__state)->planes[__i].new_state, 1))
1148
1149/**
1150 * for_each_old_plane_in_state - iterate over all planes in an atomic update
1151 * @__state: &struct drm_atomic_state pointer
1152 * @plane: &struct drm_plane iteration cursor
1153 * @old_plane_state: &struct drm_plane_state iteration cursor for the old state
1154 * @__i: int iteration cursor, for macro-internal use
1155 *
1156 * This iterates over all planes in an atomic update, tracking only the old
1157 * state. This is useful in disable functions, where we need the old state the
1158 * hardware is still in.
1159 */
1160#define for_each_old_plane_in_state(__state, plane, old_plane_state, __i) \
1161	for ((__i) = 0;							\
1162	     (__i) < (__state)->dev->mode_config.num_total_plane;	\
1163	     (__i)++)							\
1164		for_each_if ((__state)->planes[__i].ptr &&		\
1165			     ((plane) = (__state)->planes[__i].ptr,	\
1166			      (old_plane_state) = (__state)->planes[__i].old_state, 1))
1167/**
1168 * for_each_new_plane_in_state - iterate over all planes in an atomic update
1169 * @__state: &struct drm_atomic_state pointer
1170 * @plane: &struct drm_plane iteration cursor
1171 * @new_plane_state: &struct drm_plane_state iteration cursor for the new state
1172 * @__i: int iteration cursor, for macro-internal use
1173 *
1174 * This iterates over all planes in an atomic update, tracking only the new
1175 * state. This is useful in enable functions, where we need the new state the
1176 * hardware should be in when the atomic commit operation has completed.
1177 */
1178#define for_each_new_plane_in_state(__state, plane, new_plane_state, __i) \
1179	for ((__i) = 0;							\
1180	     (__i) < (__state)->dev->mode_config.num_total_plane;	\
1181	     (__i)++)							\
1182		for_each_if ((__state)->planes[__i].ptr &&		\
1183			     ((plane) = (__state)->planes[__i].ptr,	\
1184			      (void)(plane) /* Only to avoid unused-but-set-variable warning */, \
1185			      (new_plane_state) = (__state)->planes[__i].new_state, \
1186			      (void)(new_plane_state) /* Only to avoid unused-but-set-variable warning */, 1))
1187
1188/**
1189 * for_each_oldnew_private_obj_in_state - iterate over all private objects in an atomic update
1190 * @__state: &struct drm_atomic_state pointer
1191 * @obj: &struct drm_private_obj iteration cursor
1192 * @old_obj_state: &struct drm_private_state iteration cursor for the old state
1193 * @new_obj_state: &struct drm_private_state iteration cursor for the new state
1194 * @__i: int iteration cursor, for macro-internal use
1195 *
1196 * This iterates over all private objects in an atomic update, tracking both
1197 * old and new state. This is useful in places where the state delta needs
1198 * to be considered, for example in atomic check functions.
1199 */
1200#define for_each_oldnew_private_obj_in_state(__state, obj, old_obj_state, new_obj_state, __i) \
1201	for ((__i) = 0; \
1202	     (__i) < (__state)->num_private_objs && \
1203		     ((obj) = (__state)->private_objs[__i].ptr, \
1204		      (old_obj_state) = (__state)->private_objs[__i].old_state,	\
1205		      (new_obj_state) = (__state)->private_objs[__i].new_state, 1); \
1206	     (__i)++)
1207
1208/**
1209 * for_each_old_private_obj_in_state - iterate over all private objects in an atomic update
1210 * @__state: &struct drm_atomic_state pointer
1211 * @obj: &struct drm_private_obj iteration cursor
1212 * @old_obj_state: &struct drm_private_state iteration cursor for the old state
1213 * @__i: int iteration cursor, for macro-internal use
1214 *
1215 * This iterates over all private objects in an atomic update, tracking only
1216 * the old state. This is useful in disable functions, where we need the old
1217 * state the hardware is still in.
1218 */
1219#define for_each_old_private_obj_in_state(__state, obj, old_obj_state, __i) \
1220	for ((__i) = 0; \
1221	     (__i) < (__state)->num_private_objs && \
1222		     ((obj) = (__state)->private_objs[__i].ptr, \
1223		      (old_obj_state) = (__state)->private_objs[__i].old_state, 1); \
1224	     (__i)++)
1225
1226/**
1227 * for_each_new_private_obj_in_state - iterate over all private objects in an atomic update
1228 * @__state: &struct drm_atomic_state pointer
1229 * @obj: &struct drm_private_obj iteration cursor
1230 * @new_obj_state: &struct drm_private_state iteration cursor for the new state
1231 * @__i: int iteration cursor, for macro-internal use
1232 *
1233 * This iterates over all private objects in an atomic update, tracking only
1234 * the new state. This is useful in enable functions, where we need the new state the
1235 * hardware should be in when the atomic commit operation has completed.
1236 */
1237#define for_each_new_private_obj_in_state(__state, obj, new_obj_state, __i) \
1238	for ((__i) = 0; \
1239	     (__i) < (__state)->num_private_objs && \
1240		     ((obj) = (__state)->private_objs[__i].ptr, \
1241		      (void)(obj) /* Only to avoid unused-but-set-variable warning */, \
1242		      (new_obj_state) = (__state)->private_objs[__i].new_state, 1); \
1243	     (__i)++)
1244
1245/**
1246 * drm_atomic_crtc_needs_modeset - compute combined modeset need
1247 * @state: &drm_crtc_state for the CRTC
1248 *
1249 * To give drivers flexibility &struct drm_crtc_state has 3 booleans to track
1250 * whether the state CRTC changed enough to need a full modeset cycle:
1251 * mode_changed, active_changed and connectors_changed. This helper simply
1252 * combines these three to compute the overall need for a modeset for @state.
1253 *
1254 * The atomic helper code sets these booleans, but drivers can and should
1255 * change them appropriately to accurately represent whether a modeset is
1256 * really needed. In general, drivers should avoid full modesets whenever
1257 * possible.
1258 *
1259 * For example if the CRTC mode has changed, and the hardware is able to enact
1260 * the requested mode change without going through a full modeset, the driver
1261 * should clear mode_changed in its &drm_mode_config_funcs.atomic_check
1262 * implementation.
1263 */
1264static inline bool
1265drm_atomic_crtc_needs_modeset(const struct drm_crtc_state *state)
1266{
1267	return state->mode_changed || state->active_changed ||
1268	       state->connectors_changed;
1269}
1270
1271/**
1272 * drm_atomic_crtc_effectively_active - compute whether CRTC is actually active
1273 * @state: &drm_crtc_state for the CRTC
1274 *
1275 * When in self refresh mode, the crtc_state->active value will be false, since
1276 * the CRTC is off. However in some cases we're interested in whether the CRTC
1277 * is active, or effectively active (ie: it's connected to an active display).
1278 * In these cases, use this function instead of just checking active.
1279 */
1280static inline bool
1281drm_atomic_crtc_effectively_active(const struct drm_crtc_state *state)
1282{
1283	return state->active || state->self_refresh_active;
1284}
1285
1286/**
1287 * struct drm_bus_cfg - bus configuration
1288 *
1289 * This structure stores the configuration of a physical bus between two
1290 * components in an output pipeline, usually between two bridges, an encoder
1291 * and a bridge, or a bridge and a connector.
1292 *
1293 * The bus configuration is stored in &drm_bridge_state separately for the
1294 * input and output buses, as seen from the point of view of each bridge. The
1295 * bus configuration of a bridge output is usually identical to the
1296 * configuration of the next bridge's input, but may differ if the signals are
1297 * modified between the two bridges, for instance by an inverter on the board.
1298 * The input and output configurations of a bridge may differ if the bridge
1299 * modifies the signals internally, for instance by performing format
1300 * conversion, or modifying signals polarities.
1301 */
1302struct drm_bus_cfg {
1303	/**
1304	 * @format: format used on this bus (one of the MEDIA_BUS_FMT_* format)
1305	 *
1306	 * This field should not be directly modified by drivers
1307	 * (drm_atomic_bridge_chain_select_bus_fmts() takes care of the bus
1308	 * format negotiation).
1309	 */
1310	u32 format;
1311
1312	/**
1313	 * @flags: DRM_BUS_* flags used on this bus
1314	 */
1315	u32 flags;
1316};
1317
1318/**
1319 * struct drm_bridge_state - Atomic bridge state object
1320 */
1321struct drm_bridge_state {
1322	/**
1323	 * @base: inherit from &drm_private_state
1324	 */
1325	struct drm_private_state base;
1326
1327	/**
1328	 * @bridge: the bridge this state refers to
1329	 */
1330	struct drm_bridge *bridge;
1331
1332	/**
1333	 * @input_bus_cfg: input bus configuration
1334	 */
1335	struct drm_bus_cfg input_bus_cfg;
1336
1337	/**
1338	 * @output_bus_cfg: output bus configuration
1339	 */
1340	struct drm_bus_cfg output_bus_cfg;
1341};
1342
1343static inline struct drm_bridge_state *
1344drm_priv_to_bridge_state(struct drm_private_state *priv)
1345{
1346	return container_of(priv, struct drm_bridge_state, base);
1347}
1348
1349struct drm_bridge_state *
1350drm_atomic_get_bridge_state(struct drm_atomic_state *state,
1351			    struct drm_bridge *bridge);
1352struct drm_bridge_state *
1353drm_atomic_get_old_bridge_state(const struct drm_atomic_state *state,
1354				struct drm_bridge *bridge);
1355struct drm_bridge_state *
1356drm_atomic_get_new_bridge_state(const struct drm_atomic_state *state,
1357				struct drm_bridge *bridge);
1358
1359#endif /* DRM_ATOMIC_H_ */