How drm_atomic_state structures and the various entity structures are
allocated and freed isn't really trivial, so let's document it.
Signed-off-by: Maxime Ripard <mrip...@kernel.org>
---
Documentation/gpu/drm-kms.rst | 6 ++++++
drivers/gpu/drm/drm_atomic.c | 45 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 51 insertions(+)
diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index
abfe220764e1edc758a6bc6fb5ff9c8e1c7749ff..dc0f61a3d29e752889077d855a4bea381f2e2c18
100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -280,10 +280,16 @@ structure, ordering of committing state changes to
hardware is sequenced using
:c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
coverage of specific topics.
+Atomic State Lifetime
+---------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
+ :doc: state lifetime
+
Handling Driver Private State
-----------------------------
.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
:doc: handling driver private state
diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c
index
cd15cf52f0c9144711da5879da57884674aea9e4..b356d26faad4acaa25c1fe6f9bd5043b6364ce87
100644
--- a/drivers/gpu/drm/drm_atomic.c
+++ b/drivers/gpu/drm/drm_atomic.c
@@ -44,10 +44,55 @@
#include <drm/drm_writeback.h>
#include "drm_crtc_internal.h"
#include "drm_internal.h"
+/**
+ * DOC: state lifetime
+ *
+ * &struct drm_atomic_state represents an update to video pipeline state.
+ *
+ * Its lifetime is:
+ *
+ * - at reset time, the entity reset implementation will allocate a
+ * new, default, state and will store it in the entity state pointer.
+ *
+ * - whenever a new update is needed:
+ *
+ * + we allocate a new &struct drm_atomic_state using
drm_atomic_state_alloc().
+ *
+ * + we copy the state of each affected entity into our &struct
+ * drm_atomic_state using drm_atomic_get_plane_state(),
+ * drm_atomic_get_crtc_state(), drm_atomic_get_connector_state(), or
+ * drm_atomic_get_private_obj_state(). That state can then be
+ * modified.
+ *
+ * At that point, &struct drm_atomic_state stores three state
+ * pointers for that particular entity: the old, new, and existing
+ * (called "state") states. The old state is the state currently
+ * active in the hardware, ie either the one initialized by reset()
+ * or a newer one if a commit has been made. The new state is the
+ * state we just allocated and we might eventually commit to the
+ * hardware. The existing state points to the state we'll eventually
+ * have to free, the new state for now.
+ *
+ * + Once we run a commit, it is first checked and if the check is
+ * successful, it is committed. Part of the commit is a call to
+ * drm_atomic_helper_swap_state() which will turn the new state into
+ * the active state. Doing so involves updating the entity state
+ * pointer (&drm_crtc.state or similar) to point to the new state,
+ * and the existing state will now point to the old state, that used
+ * to be active but isn't anymore.
+ *
+ * + When the commit is done, and when all references to our &struct
+ * drm_atomic_state are put, drm_atomic_state_clear() runs and will
+ * free all the old states.
+ *
+ * + Now, we don't have any active &struct drm_atomic_state anymore,
+ * and only the entity active states remain allocated.
+ */
+
void __drm_crtc_commit_free(struct kref *kref)
{
struct drm_crtc_commit *commit =
container_of(kref, struct drm_crtc_commit, ref);
--
2.50.1
