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 bernardo.perez.priego@intel.com 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.