Change in coreboot[master]: Documentation/soc/intel: Add common code 2.0 romstage design document

[Bernardo Perez Priego (Code Review)]

Bernardo Perez Priego has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/51260 )

Change subject: Documentation/soc/intel: Add common code 2.0 romstage design document
......................................................................

Documentation/soc/intel: Add common code 2.0 romstage design document

Add common code 2.0 romstage design document for Intel SOC's.

Documented items:
*Introduction
*Redundant code identified
*Proposed solution
*Conclusion

Signed-off-by: Bernardo Perez Priego 
Change-Id: I6b4b467149bbfac3f736be544bd9b754c96f64f9
---
A Documentation/soc/intel/code_development_model/coreboot_common_code_2_0_romstage.md
1 file changed, 143 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/60/51260/1

diff --git a/Documentation/soc/intel/code_development_model/coreboot_common_code_2_0_romstage.md b/Documentation/soc/intel/code_development_model/coreboot_common_code_2_0_romstage.md
new file mode 100644
index 0000000..daf9a66
--- /dev/null
+++ b/Documentation/soc/intel/code_development_model/coreboot_common_code_2_0_romstage.md
@@ -0,0 +1,143 @@
+# Intel common code 2.0 romstage strategy
+
+## Introduction
+
+This document has the intention of describing the efforts to reduce the amount
+of code duplicated in Romstage across multiple Intel SOC's. This reduction is
+achieved by identifying sections of code that are redundant, to encapsulate
+this code in such way that common code can be reused and any SOC specific
+features can be added easily.
+
+The main purpose of Romstage is to configure DDR controller to access main
+memory. This is a complex process that is done by Intel FSP. During its
+execution, Romstage will locate, load, configure and execute FSP module in
+charge of memory initialization.
+
+## Redundant code identified
+
+#### Romstage entry
+``mainboard_romstage_entry`` function is our first example, this is redefined
+within every Intel SOC folder, please note that each instance of this function
+has similar structure.
+
+### Is S3 awake
+Composed by functions ``pmc_get_power_state`` and ``pmc_fill_power_state``,
+this routine is used to determine if system is coming from warm boot (S3),
+this information is required by memory initialization and afterwards during
+romstage execution.
+
+#### FSP Memory Initialization
+FSP memory initialization is invoked using API ``fsp_memory_init``, this function
+will locate, load and execute memory initialization module. Prior FSP module
+execution, ``platform_fsp_memory_init_params_cb`` will be called. Every SOC is
+responsible for defining this function, one of its parameters is a pointer to
+UPD structure. Implementation must include populating UPD structure with desired
+memory configuration.
+
+### DIMM information storage
+After memory is initialized, SOC will export memory parameters using SMBIOS
+interface, various parameters are obtained from HOB buffers after cold boot.
+See function ``save_dimm_info``.
+
+### To find definitions of above mentioned, please refer to following files:
+- **CNL** - src/soc/intel/cannonlake/romstage/romstage.c
+- **SKL** - src/soc/intel/skylake/romstage/romstage.c
+- **TGL** - src/soc/intel/tigerlake/romstage/romstage.c
+
+#### PCH Initialization
+Another routine that share this similarities is pch intialization, this can be
+marked as common code, please refer to:
+- **TGL PCH** - src/soc/intel/tigerlake/romstage/pch.c
+- **SKL PCH** - src/soc/intel/skylake/romstage/pch.c
+- **CNL PCH** - src/soc/intel/cannonlake/romstage/pch.c
+
+## Proposed solution
+From above observations we could proceed to have a generic execution flow and
+a common romstage entry for all SOC’s. Execution flow can be defined in
+following four phases:
+
+1 Initialization
+- SOC
+- PCH
+- CPU
+
+2 FSP memory initialization configuration
+- Set SOC parameters
+- Set Mainboard parameters
+
+3 FSP memory initialization execution
+
+4 FSP post memory initialization
+- SOC
+- Mainboard
+
+Note that execution flow is fixed. However, each subphase implementation is
+declared as ``__weak``, this way we can redefine, stub or extended common code
+depending on platform requirements.
+
+This is how common code inside some rewritable functions are declared:
+```
+void romstage_cmn_xxxxxxx(void)
+```
+user is free to call this function on its subphase implementation accordingly.
+
+### Execution Flow
+Main entry function:
+```
+void mainboard_romstage_entry(void)
+{
+    bool s3wake = romstage_is_s3wake();
+    romstage_init();
+    fsp_memory_init(s3wake);
+    romstage_post_mem_init();
+}
+```
+
+Initialization phase include three functions:
+```
+static void romstage_init(void)
+{
+    romstage_soc_init();
+    romstage_pch_init();
+    romstage_cpu_init();
+}
+
+void __weak romstage_soc_init(void)
+
+void __weak romstage_pch_init(void)
+
+void __weak romstage_cpu_init(void)
+```
+
+Same way with fsp memory intitialization phase:
+```
+static void platform_fsp_memory_init_params_cb(FSPM_UPD *mupd, uint32_t version)
+{
+    romstage_soc_mem_init_params(mupd, version);
+
+    romstage_mb_mem_init_params(mupd);
+}
+
+void __weak romstage_soc_post_mem_init(void)
+
+void __weak romstage_mb_post_mem_init(void)
+```
+
+Finally post memory initialization phase:
+```
+static void romstage_post_mem_init(void)
+{
+    romstage_soc_post_mem_init();
+    romstage_mb_post_mem_init();
+}
+
+void __weak romstage_soc_post_mem_init(void)
+
+void __weak romstage_mb_post_mem_init(void)
+```
+
+## Conclusion
+Reducing code duplicates facilitates project support, new fixes can be ported to
+other SOC's that this may apply with minimal effort.
+Having a uniform execution flow will not only make code easier to understand but
+also allow new SOC's to quickly start development.