drm/amd/display: Document set RECOUT operation

During the investigation on how to add visual confirmation on top of the
planes used by DCN, it becomes evident that the lack of information in
the code makes this work unnecessarily complicated. This commit
introduces a set of documentation related to the RECOUT operation in
order to make it easy for developers to navigate this set of functions.

Signed-off-by: Rodrigo Siqueira <[email protected]>
Reviewed-by: Harry Wentland <[email protected]>
Acked-by: Stylon Wang <[email protected]>
Tested-by: Daniel Wheeler <[email protected]>
Signed-off-by: Alex Deucher <[email protected]>

drivers/gpu/drm/amd/display/dc/dcn10/dcn10_dpp_dscl.c

@@ -653,33 +653,50 @@ static void dpp1_dscl_set_manual_ratio_init(
 	}
 }
 
-
-
-static void dpp1_dscl_set_recout(
-			struct dcn10_dpp *dpp, const struct rect *recout)
+/**
+ * dpp1_dscl_set_recout - Set the first pixel of RECOUT in the OTG active area
+ *
+ * @dpp: DPP data struct
+ * @recount: Rectangle information
+ *
+ * This function sets the MPC RECOUT_START and RECOUT_SIZE registers based on
+ * the values specified in the recount parameter.
+ *
+ * Note: This function only have effect if AutoCal is disabled.
+ */
+static void dpp1_dscl_set_recout(struct dcn10_dpp *dpp,
+				 const struct rect *recout)
 {
 	int visual_confirm_on = 0;
 	if (dpp->base.ctx->dc->debug.visual_confirm != VISUAL_CONFIRM_DISABLE)
 		visual_confirm_on = 1;
 
 	REG_SET_2(RECOUT_START, 0,
-		/* First pixel of RECOUT */
-			 RECOUT_START_X, recout->x,
-		/* First line of RECOUT */
-			 RECOUT_START_Y, recout->y);
+		  /* First pixel of RECOUT in the active OTG area */
+		  RECOUT_START_X, recout->x,
+		  /* First line of RECOUT in the active OTG area */
+		  RECOUT_START_Y, recout->y);
 
 	REG_SET_2(RECOUT_SIZE, 0,
-		/* Number of RECOUT horizontal pixels */
-			 RECOUT_WIDTH, recout->width,
-		/* Number of RECOUT vertical lines */
-			 RECOUT_HEIGHT, recout->height
+		  /* Number of RECOUT horizontal pixels */
+		  RECOUT_WIDTH, recout->width,
+		  /* Number of RECOUT vertical lines */
+		  RECOUT_HEIGHT, recout->height
 			 - visual_confirm_on * 2 * (dpp->base.inst + 1));
 }
 
-/* Main function to program scaler and line buffer in manual scaling mode */
-void dpp1_dscl_set_scaler_manual_scale(
-	struct dpp *dpp_base,
-	const struct scaler_data *scl_data)
+/**
+ * dpp1_dscl_set_scaler_manual_scale - Manually program scaler and line buffer
+ *
+ * @dpp_base: High level DPP struct
+ * @scl_data: scalaer_data info
+ *
+ * This is the primary function to program scaler and line buffer in manual
+ * scaling mode. To execute the required operations for manual scale, we need
+ * to disable AutoCal first.
+ */
+void dpp1_dscl_set_scaler_manual_scale(struct dpp *dpp_base,
+				       const struct scaler_data *scl_data)
 {
 	enum lb_memory_config lb_config;
 	struct dcn10_dpp *dpp = TO_DCN10_DPP(dpp_base);

drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h

@@ -32,6 +32,12 @@
 struct dpp {
 	const struct dpp_funcs *funcs;
 	struct dc_context *ctx;
+	/**
+	 * @inst:
+	 *
+	 * inst stands for "instance," and it is an id number that references a
+	 * specific DPP.
+	 */
 	int inst;
 	struct dpp_caps *caps;
 	struct pwl_params regamma_params;