drm/amd/display: Add kernel doc for commit sequence

Add basic kernel-doc that describes some of the struct and functions
that are part of the DC commit sequence..

Tested-by: Mark Broadworth <mark.broadworth@amd.com>
Reviewed-by: Aurabindo Pillai <Aurabindo.Pillai@amd.com>
Acked-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>

diff --git a/drivers/gpu/drm/amd/display/dc/core/dc.c b/drivers/gpu/drm/amd/display/dc/core/dc.c
index 945b521..2858917 100644 (file)
--- a/drivers/gpu/drm/amd/display/dc/core/dc.c
+++ b/drivers/gpu/drm/amd/display/dc/core/dc.c
@@ -1714,8 +1714,13 @@ void dc_z10_save_init(struct dc *dc)
                dc->hwss.z10_save_init(dc);
 }
 
-/*
- * Applies given context to HW and copy it into current context.
+/**
+ * dc_commit_state_no_check - Apply context to the hardware
+ *
+ * @dc: DC object with the current status to be updated
+ * @context: New state that will become the current status at the end of this function
+ *
+ * Applies given context to the hardware and copy it into current context.
  * It's up to the user to release the src context afterwards.
  */
 static enum dc_status dc_commit_state_no_check(struct dc *dc, struct dc_state *context)
@@ -3651,10 +3656,24 @@ static void commit_planes_for_stream(struct dc *dc,
        }
 }
 
-/* Determines if the incoming context requires a applying transition state with unnecessary
- * pipe splitting and ODM disabled, due to hardware limitations. In a case where
- * the OPP associated with an MPCC might change due to plane additions, this function
+/**
+ * could_mpcc_tree_change_for_active_pipes - Check if an OPP associated with MPCC might change
+ *
+ * @dc: Used to get the current state status
+ * @stream: Target stream, which we want to remove the attached planes
+ * @surface_count: Number of surface update
+ * @is_plane_addition: [in] Fill out with true if it is a plane addition case
+ *
+ * DCN32x and newer support a feature named Dynamic ODM which can conflict with
+ * the MPO if used simultaneously in some specific configurations (e.g.,
+ * 4k@144). This function checks if the incoming context requires applying a
+ * transition state with unnecessary pipe splitting and ODM disabled to
+ * circumvent our hardware limitations to prevent this edge case. If the OPP
+ * associated with an MPCC might change due to plane additions, this function
  * returns true.
+ *
+ * Return:
+ * Return true if OPP and MPCC might change, otherwise, return false.
  */
 static bool could_mpcc_tree_change_for_active_pipes(struct dc *dc,
                struct dc_stream_state *stream,
@@ -3729,6 +3748,24 @@ static bool could_mpcc_tree_change_for_active_pipes(struct dc *dc,
        return force_minimal_pipe_splitting;
 }
 
+/**
+ * commit_minimal_transition_state - Create a transition pipe split state
+ *
+ * @dc: Used to get the current state status
+ * @transition_base_context: New transition state
+ *
+ * In some specific configurations, such as pipe split on multi-display with
+ * MPO and/or Dynamic ODM, removing a plane may cause unsupported pipe
+ * programming when moving to new planes. To mitigate those types of problems,
+ * this function adds a transition state that minimizes pipe usage before
+ * programming the new configuration. When adding a new plane, the current
+ * state requires the least pipes, so it is applied without splitting. When
+ * removing a plane, the new state requires the least pipes, so it is applied
+ * without splitting.
+ *
+ * Return:
+ * Return false if something is wrong in the transition state.
+ */
 static bool commit_minimal_transition_state(struct dc *dc,
                struct dc_state *transition_base_context)
 {
@@ -3742,6 +3779,10 @@ static bool commit_minimal_transition_state(struct dc *dc,
 
        if (!transition_context)
                return false;
+       /* Setup:
+        * Store the current ODM and MPC config in some temp variables to be
+        * restored after we commit the transition state.
+        */
 
        /* check current pipes in use*/
        for (i = 0; i < dc->res_pool->pipe_count; i++) {
@@ -3777,7 +3818,7 @@ static bool commit_minimal_transition_state(struct dc *dc,
 
        dc_resource_state_copy_construct(transition_base_context, transition_context);
 
-       //commit minimal state
+       /* commit minimal state */
        if (dc->res_pool->funcs->validate_bandwidth(dc, transition_context, false)) {
                for (i = 0; i < transition_context->stream_count; i++) {
                        struct dc_stream_status *stream_status = &transition_context->stream_status[i];
@@ -3795,10 +3836,12 @@ static bool commit_minimal_transition_state(struct dc *dc,
                ret = dc_commit_state_no_check(dc, transition_context);
        }
 
-       /*always release as dc_commit_state_no_check retains in good case*/
+       /* always release as dc_commit_state_no_check retains in good case */
        dc_release_state(transition_context);
 
-       /*restore previous pipe split and odm policy*/
+       /* TearDown:
+        * Restore original configuration for ODM and MPO.
+        */
        if (!dc->config.is_vmin_only_asic)
                dc->debug.pipe_split_policy = tmp_mpc_policy;
 
@@ -3806,12 +3849,12 @@ static bool commit_minimal_transition_state(struct dc *dc,
        dc->debug.force_disable_subvp = temp_subvp_policy;
 
        if (ret != DC_OK) {
-               /*this should never happen*/
+               /* this should never happen */
                BREAK_TO_DEBUGGER();
                return false;
        }
 
-       /*force full surface update*/
+       /* force full surface update */
        for (i = 0; i < dc->current_state->stream_count; i++) {
                for (j = 0; j < dc->current_state->stream_status[i].plane_count; j++) {
                        dc->current_state->stream_status[i].plane_states[j]->update_flags.raw = 0xFFFFFFFF;

diff --git a/drivers/gpu/drm/amd/display/dc/core/dc_resource.c b/drivers/gpu/drm/amd/display/dc/core/dc_resource.c
index 7caf313..da16468 100644 (file)
--- a/drivers/gpu/drm/amd/display/dc/core/dc_resource.c
+++ b/drivers/gpu/drm/amd/display/dc/core/dc_resource.c
@@ -1768,6 +1768,17 @@ bool dc_remove_plane_from_context(
        return true;
 }
 
+/**
+ * dc_rem_all_planes_for_stream - Remove planes attached to the target stream.
+ *
+ * @dc: Current dc state.
+ * @stream: Target stream, which we want to remove the attached plans.
+ * @context: New context.
+ *
+ * Return:
+ * Return true if DC was able to remove all planes from the target
+ * stream, otherwise, return false.
+ */
 bool dc_rem_all_planes_for_stream(
                const struct dc *dc,
                struct dc_stream_state *stream,

diff --git a/drivers/gpu/drm/amd/display/dc/inc/core_types.h b/drivers/gpu/drm/amd/display/dc/inc/core_types.h
index fe34cfd..85495ef 100644 (file)
--- a/drivers/gpu/drm/amd/display/dc/inc/core_types.h
+++ b/drivers/gpu/drm/amd/display/dc/inc/core_types.h
@@ -420,7 +420,10 @@ struct pipe_ctx {
 
        struct pll_settings pll_settings;
 
-       /* link config records software decision for what link config should be
+       /**
+        * @link_config:
+        *
+        * link config records software decision for what link config should be
         * enabled given current link capability and stream during hw resource
         * mapping. This is to decouple the dependency on link capability during
         * dc commit or update.
@@ -542,6 +545,10 @@ struct dc_state {
 
        /**
         * @bw_ctx: The output from bandwidth and watermark calculations and the DML
+        *
+        * Each context must have its own instance of VBA, and in order to
+        * initialize and obtain IP and SOC, the base DML instance from DC is
+        * initially copied into every context.
         */
        struct bw_context bw_ctx;
 
@@ -559,6 +566,13 @@ struct dc_state {
 
        struct clk_mgr *clk_mgr;
 
+       /**
+        * @refcount: refcount reference
+        *
+        * Notice that dc_state is used around the code to capture the current
+        * context, so we need to pass it everywhere. That's why we want to use
+        * kref in this struct.
+        */
        struct kref refcount;
 
        struct {