soc/amd: Document VBIOS handling

The code flow isn't that obvious in the beginning. You pass an address
of the VBIOS to FSP, but don't load any VBIOS until BS_DEV_RESOURCES
phase.
Add comments to document what is done and when. This will help to
improve the code in the next step.

Change-Id: I643bc9088306d99cc0fbb79648809e16b068fb33
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/86298
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Held <felix-coreboot@felixheld.de>

src/soc/amd/cezanne/fsp_s_params.c

@@ -8,6 +8,11 @@
 
 static void fsp_assign_vbios_upds(FSP_S_CONFIG *scfg)
 {
+	/*
+	 * The VBIOS contains the ATOMBIOS tables that will be modified as
+	 * part of FSP GOP init. We can delay loading of the VBIOS until
+	 * before FSP notify AFTER_PCI_ENUM.
+	 */
 	scfg->vbios_buffer = CONFIG(RUN_FSP_GOP) ? PCI_VGA_RAM_IMAGE_START : 0;
 }
 

src/soc/amd/common/block/graphics/graphics.c

@@ -147,9 +147,13 @@ static const char *graphics_acpi_name(const struct device *dev)
 }
 
 /*
- * Even though AMD does not need VBT we still need to implement the
- * vbt_get() function to not break the build with GOP driver enabled
- * (see fsps_return_value_handler() in fsp2_0/silicon_init.c
+ * On AMD platforms the VBT is called ATOMBIOS and is always part of the
+ * VGA Option ROM. As part of the FSP GOP init the ATOMBIOS tables are
+ * updated in place. Thus the VBIOS must be loaded into RAM before FSP GOP
+ * runs. The address of the VBIOS must be passed to FSP-S using UPDs, but
+ * loading of the VBIOS can be delayed until before FSP AFTER_PCI_ENUM
+ * notify is called. FSP expects a pointer to the PCI option rom instead
+ * a pointer to the ATOMBIOS table directly.
  */
 void *vbt_get(void)
 {
@@ -165,6 +169,7 @@ static void graphics_set_resources(struct device *const dev)
 	if (!CONFIG(RUN_FSP_GOP))
 		return;
 
+	/* Load the VBIOS before FSP AFTER_PCI_ENUM notify is called. */
 	timestamp_add_now(TS_OPROM_INITIALIZE);
 	if (CONFIG(USE_SELECTIVE_GOP_INIT) && vbios_cache_is_valid() &&
 			!display_init_required()) {
@@ -172,6 +177,11 @@ static void graphics_set_resources(struct device *const dev)
 		timestamp_add_now(TS_OPROM_COPY_END);
 		return;
 	}
+
+	/*
+	 * VBIOS cache was not used, so load it from CBFS and let FSP GOP
+	 * initialize the ATOMBIOS tables.
+	 */
 	rom = pci_rom_probe(dev);
 	if (rom == NULL) {
 		printk(BIOS_ERR, "%s: Unable to find ROM for %s\n",

src/soc/amd/glinda/fsp_s_params.c

@@ -10,6 +10,11 @@
 
 static void fsp_assign_vbios_upds(FSP_S_CONFIG *scfg)
 {
+	/*
+	 * The VBIOS contains the ATOMBIOS tables that will be modified as
+	 * part of FSP GOP init. We can delay loading of the VBIOS until
+	 * before FSP notify AFTER_PCI_ENUM.
+	 */
 	scfg->vbios_buffer = CONFIG(RUN_FSP_GOP) ? PCI_VGA_RAM_IMAGE_START : 0;
 }
 

src/soc/amd/mendocino/fsp_s_params.c

@@ -20,6 +20,11 @@ static void fsp_assign_vbios_upds(FSP_S_CONFIG *scfg)
 		printk(BIOS_SPEW, "%s: using VBIOS cache; skipping GOP driver.\n", __func__);
 		return;
 	}
+	/*
+	 * The VBIOS contains the ATOMBIOS tables that will be modified as
+	 * part of FSP GOP init. We can delay loading of the VBIOS until
+	 * before FSP notify AFTER_PCI_ENUM.
+	 */
 	printk(BIOS_SPEW, "%s: not using VBIOS cache; running GOP driver.\n", __func__);
 	scfg->vbios_buffer = CONFIG(RUN_FSP_GOP) ? PCI_VGA_RAM_IMAGE_START : 0;
 }

src/soc/amd/phoenix/fsp_s_params.c

@@ -10,6 +10,11 @@
 
 static void fsp_assign_vbios_upds(FSP_S_CONFIG *scfg)
 {
+	/*
+	 * The VBIOS contains the ATOMBIOS tables that will be modified as
+	 * part of FSP GOP init. We can delay loading of the VBIOS until
+	 * before FSP notify AFTER_PCI_ENUM.
+	 */
 	scfg->vbios_buffer = CONFIG(RUN_FSP_GOP) ? PCI_VGA_RAM_IMAGE_START : 0;
 }
 

src/soc/amd/picasso/fsp_s_params.c

@@ -185,6 +185,11 @@ static void fsp_edp_tuning_upds(FSP_S_CONFIG *scfg,
 
 static void fsp_assign_vbios_upds(FSP_S_CONFIG *scfg)
 {
+	/*
+	 * The VBIOS contains the ATOMBIOS tables that will be modified as
+	 * part of FSP GOP init. We can delay loading of the VBIOS until
+	 * before FSP notify AFTER_PCI_ENUM.
+	 */
 	scfg->vbios_buffer_addr = CONFIG(RUN_FSP_GOP) ? PCI_VGA_RAM_IMAGE_START : 0;
 }