The current documentation of drm_atomic_state says that it's the "global
state object". This is confusing since, while it does contain all the
objects affected by an update and their respective states, if an object
isn't affected by this update it won't be part of it.

Thus, it's not truly a "global state", unlike object state structures
that do contain the entire state of a given object.

Reviewed-by: Hamza Mahfooz <hamza.mahfooz@amd.com>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Link: https://lore.kernel.org/r/20231214100917.277842-4-mripard@kernel.org
Signed-off-by: Maxime Ripard <mripard@kernel.org>

Commits 63e83c1dba54 ("drm: Consolidate connector arrays in
drm_atomic_state"), b8b5342b699b ("drm: Consolidate plane arrays in
drm_atomic_state") and 5d943aa6c0d4 ("drm: Consolidate crtc arrays in
drm_atomic_state") moved the object pointer and their state pointer to
an intermediate structure storing both.

The CRTC commit didn't update the doc of the crtcs field to reflect
that, and the doc for the planes and connectors fields mention that they
are pointers to an array of structures with per-$OBJECT data.

The private_objs field was added later on by commit b430c27a7de3 ("drm:
Add driver-private objects to atomic state") reusing the same sentence
than the crtcs field, probably due to copy and paste.

While these fields are indeed pointers to an array, each item of that
array contain a pointer to the object structure affected by the update,
and its old and new state. There's no per-object data there, and there's
more than just a pointer to the objects.

Let's rephrase those fields a bit to better match the current situation.

Acked-by: Sui Jingfeng <sui.jingfeng@linux.dev>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://lore.kernel.org/r/20231214100917.277842-3-mripard@kernel.org
Signed-off-by: Maxime Ripard <mripard@kernel.org>

Commit 63e83c1dba54 ("drm: Consolidate connector arrays in
drm_atomic_state") removed the connector_states field but didn't remove
its mention in the num_connectors documentation.

Acked-by: Sui Jingfeng <sui.jingfeng@linux.dev>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://lore.kernel.org/r/20231214100917.277842-2-mripard@kernel.org
Signed-off-by: Maxime Ripard <mripard@kernel.org>

Some fields of drm_atomic_state have been documented in-line, but some
were documented in the main kerneldoc block before the structure.

Since the former is the preferred option in DRM, let's move all the
fields to an inline documentation.

Acked-by: Sui Jingfeng <sui.jingfeng@linux.dev>
Link: https://lore.kernel.org/r/20231214100917.277842-1-mripard@kernel.org
Signed-off-by: Maxime Ripard <mripard@kernel.org>

There's an obvious copy-paste error in the description of
output_bus_cfg. Fix it.

Fixes: f32df58acc68 ("drm/bridge: Add the necessary bits to support bus format negotiation")
Signed-off-by: Douglas Anderson <dianders@chromium.org>
Signed-off-by: Maxime Ripard <mripard@kernel.org>
Link: https://patchwork.freedesktop.org/patch/msgid/20230817094808.1.I41b04c3a8305c9f1c17af886c327941c5136ca3b@changeid

Add new helper functions, drm_atomic_get_old_crtc_for_encoder
and drm_atomic_get_new_crtc_for_encoder to retrieve the
corresponding crtc for the encoder.

Signed-off-by: Sankeerth Billakanti <quic_sbillaka@quicinc.com>
Signed-off-by: Vinod Polimera <quic_vpolimer@quicinc.com>
Reviewed-by: Douglas Anderson <dianders@chromium.org>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Patchwork: https://patchwork.freedesktop.org/patch/524718/
Link: https://lore.kernel.org/r/1677774797-31063-2-git-send-email-quic_vpolimer@quicinc.com
Signed-off-by: Dmitry Baryshkov <dmitry.baryshkov@linaro.org>

The drm_atomic_get_(old|new)_*_state don't modify the passed
drm_atomic_state, so we can make it const.

Reviewed-by: Javier Martinez Canillas <javierm@redhat.com>
Signed-off-by: Maxime Ripard <maxime@cerno.tech>
Link: https://patchwork.freedesktop.org/patch/msgid/20221123-rpi-kunit-tests-v1-9-051a0bb60a16@cerno.tech

Fix the `unused-but-set-variable` warning as how other iteration
wrappers do.

Link: https://lore.kernel.org/all/202206071049.pofHsRih-lkp@intel.com/
Reported-by: kernel test robot <lkp@intel.com>
Signed-off-by: GONG, Ruiqi <gongruiqi1@huawei.com>
Signed-off-by: Maxime Ripard <maxime@cerno.tech>
Link: https://patchwork.freedesktop.org/patch/msgid/20220607110848.941486-1-gongruiqi1@huawei.com

A number of drivers (amdgpu, komeda, vc4, etc.) leverage the
drm_private_state structure, but we don't have any infrastructure to
provide debugging like we do for the other components state. Let's add
an atomic_print_state hook to be consistent.

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Maxime Ripard <maxime@cerno.tech>
Link: https://lore.kernel.org/r/20220328124304.2309418-3-maxime@cerno.tech

Add description for parameters for
for_each_new_plane_in_state_reverse to fix warnings:

include/drm/drm_atomic.h:908: warning: Function parameter or member '__state' not described in 'for_each_new_plane_in_state_reverse'
include/drm/drm_atomic.h:908: warning: Function parameter or member 'plane' not described in 'for_each_new_plane_in_state_reverse'
include/drm/drm_atomic.h:908: warning: Function parameter or member 'new_plane_state' not described in 'for_each_new_plane_in_state_reverse'
include/drm/drm_atomic.h:908: warning: Function parameter or member '__i' not described in 'for_each_new_plane_in_state_reverse'

Fixes: a6c3c37b661d ("drm/amd/display: fix gcc set but not used warning of variable 'old_plane_state'")
Signed-off-by: Yu Kuai <yukuai3@huawei.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>