mb/siemens: Unify and clean lcd_panel.c coding style

With the addition of the mc_ehl3 board variant, a few
points about commenting the code arose either from the
review or during the implementation itself.

This patch unifies structure of these files, which
have a similar structure across more Siemens boards
utilizing the PTN3460 eDP-to-LVDS bridge.

BUG=none
TEST=Check that images for the affected boards can be
built.

Change-Id: I59820362e1f87e296c5548b9c3cecba4d2710fe7
Signed-off-by: Jan Samek <jan.samek@siemens.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/72068
Reviewed-by: Werner Zeh <werner.zeh@siemens.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

1 files changed, 18 insertions, 16 deletions

diff --git a/src/mainboard/siemens/mc_ehl/variants/mc_ehl3/lcd_panel.c b/src/mainboard/siemens/mc_ehl/variants/mc_ehl3/lcd_panel.c
index bd21460f60..b1c4e0100c 100644
--- a/src/mainboard/siemens/mc_ehl/variants/mc_ehl3/lcd_panel.c
+++ b/src/mainboard/siemens/mc_ehl/variants/mc_ehl3/lcd_panel.c
@@ -6,9 +6,10 @@
 #include <hwilib.h>
 #include <types.h>
 
-/** \brief This function provides EDID data to the driver for DP2LVDS Bridge (PTN3460)
- * @param  edid_data	pointer to EDID data in driver
-*/
+/** \brief This function provides EDID data to the driver for DP2LVDS Bridge (PTN3460).
+ * @param  edid_data  pointer to EDID data in driver
+ * @return CB_SUCCESS on successful EDID data retrieval, CB_ERR otherwise
+ */
 enum cb_err mb_get_edid(uint8_t edid_data[0x80])
 {
 	const char *hwi_block = "hwinfo.hex";
@@ -28,16 +29,18 @@ enum cb_err mb_get_edid(uint8_t edid_data[0x80])
 
 /** \brief This function provides EDID block [0..6] to the driver for DP2LVDS Bridge (PTN3460)
  * which has to be used.
-*/
+ * @return Index of the EDID slot selected for EDID emulation
+ */
 uint8_t mb_select_edid_table(void)
 {
 	return 6; /* With this mainboard we use EDID block 6 for emulation in PTN3460. */
 }
 
-/** \brief Function to enable mainboard to adjust the config data of PTN3460.
- * @param   *cfg_ptr  Pointer to the PTN config structure to modify.
+/** \brief Function to enable mainboard to adjust the config data of PTN3460. For reference,
+ * see NXP document AN11128 - PTN3460 Programming guide.
+ * @param   *cfg_ptr  Pointer to the PTN config structure to modify
  * @return  -1 on error; PTN_CFG_MODIFIED if data was modified and needs to be updated.
-*/
+ */
 int mb_adjust_cfg(struct ptn_3460_config *cfg)
 {
 	const char *hwi_block = "hwinfo.hex";
@@ -58,9 +61,10 @@ int mb_adjust_cfg(struct ptn_3460_config *cfg)
 		return -1;
 	}
 
-	/* Set up configuration data according to the hwinfo block we got. */
+	/* Set up PTN3460 registers based on hwinfo and fixed board-specific parameters: */
+	/* Use 2 lanes for eDP, no P/N swapping, no ASSR, allow both HBR and RBR modes. */
 	cfg->dp_interface_ctrl = 0x00;
-	/* Use odd-bus for clock distribution only. */
+	/* Use odd bus for LVDS clock distribution only. */
 	cfg->lvds_interface_ctrl1 = 0x01;
 	if (disp_con == PF_DISPLCON_LVDS_DUAL) {
 		/* Turn on dual LVDS lane and clock. */
@@ -70,19 +74,17 @@ int mb_adjust_cfg(struct ptn_3460_config *cfg)
 		/* Use 18 bits per pixel. */
 		cfg->lvds_interface_ctrl1 |= 0x20;
 	}
-
-	/* Set up remaining board-specific LVDS parameters: */
-	/* No clock spreading, 300 mV LVDS swing. */
+	/* No LVDS clock spreading, 300 mV LVDS swing */
 	cfg->lvds_interface_ctrl2 = 0x03;
-	/* No lane/channel swapping */
+	/* No LVDS lane/channel swapping */
 	cfg->lvds_interface_ctrl3 = 0x00;
-	/* Enable VDD to LVDS active delay (16 ms). */
+	/* Enable VDD to LVDS active delay. */
 	cfg->t2_delay = 0x01;
-	/* LVDS to backlight active delay: 200 ms. */
+	/* LVDS to backlight active delay: 200 ms */
 	cfg->t3_timing = 0x04;
 	/* Minimum re-power delay: 500 ms */
 	cfg->t12_timing = 0x0a;
-	/* Backlight off to LVDS inactive delay: 200 ms. */
+	/* Backlight off to LVDS inactive delay: 200 ms */
 	cfg->t4_timing = 0x04;
 	/* Enable LVDS to VDD inactive delay. */
 	cfg->t5_delay = 0x01;