From 438b463a8f5f739eb02422a3d00b8dfcbeefc2e9 Mon Sep 17 00:00:00 2001 From: Philipp Deppenwiese Date: Sun, 13 May 2018 15:47:18 +0200 Subject: Documentation: Update index.md and move files * Add more subdirectories and index.mds. * Move "getting started" and "lessons" into sub-directories. * Move "NativeRaminit" into northbridge/intel/sandybridge folder. * Move "MultiProcessorInit" into soc/intel/icelake folder. * Reference new files Change-Id: I78c3ec0e8bcc342686277ae141a88d0486680978 Signed-off-by: Philipp Deppenwiese Signed-off-by: Patrick Rudolph Reviewed-on: https://review.coreboot.org/26262 Reviewed-by: Patrick Georgi Reviewed-by: Philipp Deppenwiese Tested-by: build bot (Jenkins) --- .../Intel/MultiProcessorInit/MultiProcessorInit.md | 85 - .../coreboot_publish_mp_service_api.png | Bin 123328 -> 0 bytes .../Intel/NativeRaminit/SandyBridge_registers.md | 2174 -------------------- Documentation/Intel/NativeRaminit/Sandybridge.md | 135 -- .../Intel/NativeRaminit/Sandybridge_freq.md | 165 -- .../Intel/NativeRaminit/Sandybridge_read.md | 153 -- .../NativeRaminit/timA_lane0-3_adjust_fine.png | Bin 92363 -> 0 bytes .../NativeRaminit/timA_lane0-3_discover_420x.png | Bin 100726 -> 0 bytes .../Intel/NativeRaminit/timA_lane0-3_rt53.png | Bin 103600 -> 0 bytes .../Intel/NativeRaminit/timA_lane0-3_rt54.png | Bin 104571 -> 0 bytes .../Intel/NativeRaminit/timA_lane0-3_rt55.png | Bin 105582 -> 0 bytes Documentation/Lesson1.md | 168 -- Documentation/Lesson2.md | 281 --- Documentation/build_system.md | 86 - Documentation/core/Kconfig.md | 1235 ----------- Documentation/gerrit_guidelines.md | 277 --- Documentation/getting_started/build_system.md | 86 + Documentation/getting_started/gerrit_guidelines.md | 277 +++ Documentation/getting_started/index.md | 6 + Documentation/getting_started/kconfig.md | 1235 +++++++++++ Documentation/getting_started/submodules.md | 46 + Documentation/index.md | 13 +- Documentation/lessons/index.md | 4 + Documentation/lessons/lesson1.md | 168 ++ Documentation/lessons/lesson2.md | 281 +++ Documentation/mainboard/hp/compaq_8200_sff.md | 26 +- Documentation/northbridge/index.md | 7 + Documentation/northbridge/intel/index.md | 7 + .../northbridge/intel/sandybridge/index.md | 7 + Documentation/northbridge/intel/sandybridge/nri.md | 135 ++ .../northbridge/intel/sandybridge/nri_freq.md | 165 ++ .../northbridge/intel/sandybridge/nri_read.md | 153 ++ .../northbridge/intel/sandybridge/nri_registers.md | 2174 ++++++++++++++++++++ .../intel/sandybridge/timA_lane0-3_adjust_fine.png | Bin 0 -> 92363 bytes .../sandybridge/timA_lane0-3_discover_420x.png | Bin 0 -> 100726 bytes .../intel/sandybridge/timA_lane0-3_rt53.png | Bin 0 -> 103600 bytes .../intel/sandybridge/timA_lane0-3_rt54.png | Bin 0 -> 104571 bytes .../intel/sandybridge/timA_lane0-3_rt55.png | Bin 0 -> 105582 bytes Documentation/soc/index.md | 7 + .../soc/intel/icelake/MultiProcessorInit.md | 85 + .../icelake/coreboot_publish_mp_service_api.png | Bin 0 -> 123328 bytes Documentation/soc/intel/icelake/index.md | 7 + Documentation/soc/intel/index.md | 7 + Documentation/submodules.md | 46 - 44 files changed, 4875 insertions(+), 4826 deletions(-) delete mode 100644 Documentation/Intel/MultiProcessorInit/MultiProcessorInit.md delete mode 100644 Documentation/Intel/MultiProcessorInit/coreboot_publish_mp_service_api.png delete mode 100644 Documentation/Intel/NativeRaminit/SandyBridge_registers.md delete mode 100644 Documentation/Intel/NativeRaminit/Sandybridge.md delete mode 100644 Documentation/Intel/NativeRaminit/Sandybridge_freq.md delete mode 100644 Documentation/Intel/NativeRaminit/Sandybridge_read.md delete mode 100644 Documentation/Intel/NativeRaminit/timA_lane0-3_adjust_fine.png delete mode 100644 Documentation/Intel/NativeRaminit/timA_lane0-3_discover_420x.png delete mode 100644 Documentation/Intel/NativeRaminit/timA_lane0-3_rt53.png delete mode 100644 Documentation/Intel/NativeRaminit/timA_lane0-3_rt54.png delete mode 100644 Documentation/Intel/NativeRaminit/timA_lane0-3_rt55.png delete mode 100644 Documentation/Lesson1.md delete mode 100644 Documentation/Lesson2.md delete mode 100644 Documentation/build_system.md delete mode 100644 Documentation/core/Kconfig.md delete mode 100644 Documentation/gerrit_guidelines.md create mode 100644 Documentation/getting_started/build_system.md create mode 100644 Documentation/getting_started/gerrit_guidelines.md create mode 100644 Documentation/getting_started/index.md create mode 100644 Documentation/getting_started/kconfig.md create mode 100644 Documentation/getting_started/submodules.md create mode 100644 Documentation/lessons/index.md create mode 100644 Documentation/lessons/lesson1.md create mode 100644 Documentation/lessons/lesson2.md create mode 100644 Documentation/northbridge/index.md create mode 100644 Documentation/northbridge/intel/index.md create mode 100644 Documentation/northbridge/intel/sandybridge/index.md create mode 100644 Documentation/northbridge/intel/sandybridge/nri.md create mode 100644 Documentation/northbridge/intel/sandybridge/nri_freq.md create mode 100644 Documentation/northbridge/intel/sandybridge/nri_read.md create mode 100644 Documentation/northbridge/intel/sandybridge/nri_registers.md create mode 100644 Documentation/northbridge/intel/sandybridge/timA_lane0-3_adjust_fine.png create mode 100644 Documentation/northbridge/intel/sandybridge/timA_lane0-3_discover_420x.png create mode 100644 Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt53.png create mode 100644 Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt54.png create mode 100644 Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt55.png create mode 100644 Documentation/soc/index.md create mode 100644 Documentation/soc/intel/icelake/MultiProcessorInit.md create mode 100644 Documentation/soc/intel/icelake/coreboot_publish_mp_service_api.png create mode 100644 Documentation/soc/intel/icelake/index.md create mode 100644 Documentation/soc/intel/index.md delete mode 100644 Documentation/submodules.md diff --git a/Documentation/Intel/MultiProcessorInit/MultiProcessorInit.md b/Documentation/Intel/MultiProcessorInit/MultiProcessorInit.md deleted file mode 100644 index ab0b5135ed..0000000000 --- a/Documentation/Intel/MultiProcessorInit/MultiProcessorInit.md +++ /dev/null @@ -1,85 +0,0 @@ -# Intel Common Code Block Publishing EFI_MP_SERVICES_PPI - -## Introduction - -This documentation is intended to document the purpose for creating EFI service -Interface inside coreboot space to perform CPU feature programming on Application -Processors for Intel 9th Gen (Cannon Lake) and beyond CPUs. - -Today coreboot is capable enough to handle multi-processor initialization on IA platforms. - -The multi-processor initialization code has to take care of lots of duties: - -1. Bringing all cores out of reset -2. Load latest microcode on all cores -3. Sync latest MTRR snapshot between BSP and APs -4. Perform sets of CPU feature programming - * CPU Power & Thermal Management - * Overclocking - * Intel Trusted Execution Technology - * Intel Software Guard Extensions - * Intel Processor Trace etc. - -This above CPU feature programming lists are expected to grow with current and future -CPU complexity and there might be some cases where certain feature programming mightbe -closed source in nature. - -Platform code might need to compromise on those closed source nature of CPU programming -if we don't plan to provide an alternate interface which can be used by coreboot to -get-rid of such close source CPU programming. - -## Proposal - -As coreboot is doing CPU multi-processor initialization for IA platform before FSP-S -initialization and having all possible information about cores in terms of maximum number -of cores, APIC ids, stack size etc. It’s also possible for coreboot to extend its own -support model and create a sets of APIs which later can be used by FSP to run CPU feature -programming using coreboot published APIs. - -Due to the fact that FSP is using EFI infrastructure and need to relying on install/locate -PPI to perform certain API call, hence coreboot has to created MP services APIs known as -EFI_MP_SERVICES_PPI as per PI specification volume 1, section 8.3.9. -More details here: [PI_Spec_1_6] - -### coreboot to publish EFI_MP_SERVICES_PPI APIs - -```eval_rst -+------------------------------+------------------------------------------------------------------+ -| API | Description | -+==============================+==================================================================+ -| PeiGetNumberOfProcessors | Get the number of CPU's. | -+------------------------------+------------------------------------------------------------------+ -| PeiGetProcessorInfo | Get information on a specific CPU. | -+------------------------------+------------------------------------------------------------------+ -| PeiStartupAllAPs | Activate all of the application processors. | -+------------------------------+------------------------------------------------------------------+ -| PeiStartupThisAP | Activate a specific application processor. | -+------------------------------+------------------------------------------------------------------+ -| PeiSwitchBSP | Switch the boot strap processor. | -+------------------------------+------------------------------------------------------------------+ -| PeiEnableDisableAP | Enable or disable an application processor. | -+------------------------------+------------------------------------------------------------------+ -| PeiWhoAmI | Identify the currently executing processor. | -+------------------------------+------------------------------------------------------------------+ -``` - -## Code Flow - -Here is proposed design flow with coreboot has implemented EFI_MP_SERVICES_PPI API and FSP will make -use of the same to perform some CPU feature programming. - -**coreboot-FSP MP init flow** -![coreboot-fsp mp init flow][coreboot_publish_mp_service_api] - -[coreboot_publish_mp_service_api]: coreboot_publish_mp_service_api.png - -## Benefits -1. coreboot was using SkipMpInit=1 which will skip entire FSP CPU feature programming. -With proposed model, coreboot will make use of SkipMpInit=0 which will allow to run all -Silicon recommended CPU programming. -2. CPU feature programming inside FSP will be more transparent than before as it’s using -coreboot interfaces to execute those programming. -3. coreboot will have more control over running those feature programming as API optimization -handled by coreboot. - -[PI_Spec_1_6]: http://www.uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf diff --git a/Documentation/Intel/MultiProcessorInit/coreboot_publish_mp_service_api.png b/Documentation/Intel/MultiProcessorInit/coreboot_publish_mp_service_api.png deleted file mode 100644 index 5836140c53..0000000000 Binary files a/Documentation/Intel/MultiProcessorInit/coreboot_publish_mp_service_api.png and /dev/null differ diff --git a/Documentation/Intel/NativeRaminit/SandyBridge_registers.md b/Documentation/Intel/NativeRaminit/SandyBridge_registers.md deleted file mode 100644 index 601157c464..0000000000 --- a/Documentation/Intel/NativeRaminit/SandyBridge_registers.md +++ /dev/null @@ -1,2174 +0,0 @@ -# Inoffical Documentation of Intel MCHBAR register space. - -The MCHBAR can be enabled by using register 0x48 of PCI(0:0:0) device. - -This documentation is incomplete and might be incorrect. -Please handle with care ! - -**MCHBAR + 0x4** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x10** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x14** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x18** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x1c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x20** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x24** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x28** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x2c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x204** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x210** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x214** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x218** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x21c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x220** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x224** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x228** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x22c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x404** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x410** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x414** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x418** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x41c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x420** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x424** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x428** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x42c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x604** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x610** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x614** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x618** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x61c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x620** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x624** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x628** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x62c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x804** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x810** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x814** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x818** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x81c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x820** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x824** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x828** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x82c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 4 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa04** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa10** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa14** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa18** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa1c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa20** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa24** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa28** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xa2c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 5 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc04** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc10** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc14** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 0:5| Rank 0 CLK phase shift, low | -+-----------+------------------------------------------------------------------+ -| 6:11| Rank 1 CLK phase shift, low | -+-----------+------------------------------------------------------------------+ -| 12:17| Rank 2 CLK phase shift, low | -+-----------+------------------------------------------------------------------+ -| 18:23| Rank 3 CLK phase shift, low | -+-----------+------------------------------------------------------------------+ -| 24:27| Rankmap to enable clock crossover on | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc18** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 0 | Rank 0 CLK phase shift, high | -+-----------+------------------------------------------------------------------+ -| 1 | Rank 1 CLK phase shift, high | -+-----------+------------------------------------------------------------------+ -| 2 | Rank 2 CLK phase shift, high | -+-----------+------------------------------------------------------------------+ -| 3 | Rank 3 CLK phase shift, high | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc1c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc20** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc24** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc28** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xc2c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 6 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe04** - -*Width:* 64 Bit - -*Desc:* Lane training result Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:63| Training result, each bit corresponds to one of the 64 settings | -| | of IO delay | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe10** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe14** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe18** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe1c** - -*Width:* 32 Bit - -*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 6:11| DQS phase shift on rising edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -| 16:18| IO delay in DCKs | -+-----------+------------------------------------------------------------------+ -| 20:25| DQS phase shift on falling edge in 1/64 DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe20** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe24** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe28** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0xe2c** - -*Width:* 24 Bit - -*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 7 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| DQ IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 8:13| DQS IO phase shift in 1/64th DCKs | -+-----------+------------------------------------------------------------------+ -| 15:17| DQS IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -| 20 | DQ IO phase shift in DCKs | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x1810** - -*Width:* 32 Bit - -*Desc:* COMP1 Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 9:11| ODT | -+-----------+------------------------------------------------------------------+ -| 21:23| CLK drive up | -+-----------+------------------------------------------------------------------+ -| 27:29| CTRL drive up | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x320c** - -*Width:* 32 Bit - -*Desc:* Command crossover enable Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:5| CLK phase, low | -+-----------+------------------------------------------------------------------+ -| 12 | CLK phase, high | -+-----------+------------------------------------------------------------------+ -| 14 | Enable hardware | -+-----------+------------------------------------------------------------------+ -| 17 | Enable on slot 1 | -+-----------+------------------------------------------------------------------+ -| 27 | Enable on slot 2 | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x3714** - -*Width:* 32 Bit - -*Desc:* COMP2 Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:31| COMP2 value | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4000** - -*Width:* 24 Bit - -*Desc:* TC_DBP - Timing of DDR - Bin Parameter Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:3| tRCD | -+-----------+------------------------------------------------------------------+ -| 4:7| tRP | -+-----------+------------------------------------------------------------------+ -| 8:11| CAS | -+-----------+------------------------------------------------------------------+ -| 12:15| CWL | -+-----------+------------------------------------------------------------------+ -| 16:19| tRAS | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4004** - -*Width:* 32 Bit - -*Desc:* TC_RAP - Timing of DDR - Regular Access Parameters Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:3| tRRD | -+-----------+------------------------------------------------------------------+ -| 4:7| tRTP | -+-----------+------------------------------------------------------------------+ -| 8:11| CKE | -+-----------+------------------------------------------------------------------+ -| 12:15| WTR | -+-----------+------------------------------------------------------------------+ -| 16:19| tFAW | -+-----------+------------------------------------------------------------------+ -| 24:27| tWR | -+-----------+------------------------------------------------------------------+ -| 29 | Command 3-state options | -| | - 0: Drive when channel is active, tri-state when inactive, | -| | - 1: Always drive command bus | -+-----------+------------------------------------------------------------------+ -| 30:31| CMD stretch, | -| | - 00b: 1N, | -| | - 10b: 2N, | -| | - 11b: 3N | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x400c** - -*Width:* 24 Bit - -*Desc:* OTHP ODT control Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:3| tXPDLL ? | -+-----------+------------------------------------------------------------------+ -| 5:7| tXP ? | -+-----------+------------------------------------------------------------------+ -| 16:17| ODT stretch | -+-----------+------------------------------------------------------------------+ -| 18:19| ODT stretch | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x401c** - -*Width:* 16 Bit - -*Desc:* OTHP Workaround (SandyBridge only) Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 12:13| ODT stretch | -+-----------+------------------------------------------------------------------+ -| 14:15| ODT stretch | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4024** - -*Width:* 32 Bit - -*Desc:* Rounttrip time Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:7| RTT Rank 0 DIMM 0 | -+-----------+------------------------------------------------------------------+ -| 8:15| RTT Rank 1 DIMM 0 | -+-----------+------------------------------------------------------------------+ -| 16:23| RTT Rank 0 DIMM 1 | -+-----------+------------------------------------------------------------------+ -| 24:31| RTT Rank 1 DIMM 1 | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4028** - -*Width:* 24 Bit - -*Desc:* SC_IO_LATENCY Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:3| IO latency Rank 0 DIMM 0 | -+-----------+------------------------------------------------------------------+ -| 4:7| IO latency Rank 1 DIMM 0 | -+-----------+------------------------------------------------------------------+ -| 8:11| IO latency Rank 0 DIMM 1 | -+-----------+------------------------------------------------------------------+ -| 12:15| IO latency Rank 1 DIMM 1 | -+-----------+------------------------------------------------------------------+ -| 16:21| Rount trip - I/O compensation | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4200** - -*Width:* 32 Bit - -*Desc:* RAM training queue, address Register, Channel 0, queue idx 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:15| Address | -+-----------+------------------------------------------------------------------+ -| 20:22| Bank address | -+-----------+------------------------------------------------------------------+ -| 24:25| Slotrank | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4204** - -*Width:* 32 Bit - -*Desc:* RAM training queue, address Register, Channel 0, queue idx 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:15| Address | -+-----------+------------------------------------------------------------------+ -| 20:22| Bank address | -+-----------+------------------------------------------------------------------+ -| 24:25| Slotrank | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4208** - -*Width:* 32 Bit - -*Desc:* RAM training queue, address Register, Channel 0, queue idx 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:15| Address | -+-----------+------------------------------------------------------------------+ -| 20:22| Bank address | -+-----------+------------------------------------------------------------------+ -| 24:25| Slotrank | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x420c** - -*Width:* 32 Bit - -*Desc:* RAM training queue, address Register, Channel 0, queue idx 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:15| Address | -+-----------+------------------------------------------------------------------+ -| 20:22| Bank address | -+-----------+------------------------------------------------------------------+ -| 24:25| Slotrank | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4220** - -*Width:* 8 Bit - -*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0 | !RAS | -+-----------+------------------------------------------------------------------+ -| 1 | !CAS | -+-----------+------------------------------------------------------------------+ -| 2 | !WE | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4224** - -*Width:* 8 Bit - -*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0 | !RAS | -+-----------+------------------------------------------------------------------+ -| 1 | !CAS | -+-----------+------------------------------------------------------------------+ -| 2 | !WE | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4228** - -*Width:* 8 Bit - -*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0 | !RAS | -+-----------+------------------------------------------------------------------+ -| 1 | !CAS | -+-----------+------------------------------------------------------------------+ -| 2 | !WE | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x422c** - -*Width:* 8 Bit - -*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0 | !RAS | -+-----------+------------------------------------------------------------------+ -| 1 | !CAS | -+-----------+------------------------------------------------------------------+ -| 2 | !WE | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4230** - -*Width:* 32 Bit - -*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 16:31| Clock cycles to wait after command | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4234** - -*Width:* 32 Bit - -*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 1 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 16:31| Clock cycles to wait after command | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4238** - -*Width:* 32 Bit - -*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 2 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 16:31| Clock cycles to wait after command | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x423c** - -*Width:* 32 Bit - -*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 3 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 16:31| Clock cycles to wait after command | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4284** - -*Width:* 24 Bit - -*Desc:* RAM training queue, cooldown Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0 | Start executing DRAM command queue | -+-----------+------------------------------------------------------------------+ -| 16:19| (Number of queued commands - 1) * 4 | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4298** - -*Width:* 40 Bit - -*Desc:* TC - Refresh parameters Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:15| tREFI, average period between refresh in DCLK cycles | -+-----------+------------------------------------------------------------------+ -| 16:24| tRFC, Time of refresh, from beginning of refresh until next ACT | -| | or refresh is allowed in DCLK cycles | -+-----------+------------------------------------------------------------------+ -| 25:32| tREFIx9, Maximum time allowed between refreshes to a rank. | -| | Should be programmed to 8.9 * tREFI / 1024 | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x42a4** - -*Width:* 32 Bit - -*Desc:* SRFTP Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:11| tXSDLL | -+-----------+------------------------------------------------------------------+ -| 12:15| tXS_offset | -+-----------+------------------------------------------------------------------+ -| 16:25| tZQOPER | -+-----------+------------------------------------------------------------------+ -| 28:31| tMOD | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4c20** - -*Width:* 32 Bit - -*Desc:* Scheduler parameters Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:31| scheduler parameters | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4cb0** - -*Width:* 16 Bit - -*Desc:* PM - Power-down configuration, Broadcast Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:7| PDWN_idle_counter, This defines the rank indle period in DCLK | -| | cycles that causes power-down entrance. The minimum value | -| | should be greater then or equal to the worst roundtrip time | -| | plus burst length. | -+-----------+------------------------------------------------------------------+ -| 8:10| PDWN_mode, selects the mode of power-down: | -| | - 0x0: No power down, | -| | - 0x1: APD, | -| | - 0x2: PPD, | -| | - 0x3: APD+PPD, | -| | - 0x4: Reserved, | -| | - 0x5: Reserved, | -| | - 0x6: PPD-DLLoff, | -| | - 0x7: APD+PPD+DLLof | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4e80** - -*Width:* 32 Bit - -*Desc:* Power mode preset Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:31| Power mode preset | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4e94** - -*Width:* 16 Bit - -*Desc:* TC - Refresh parameters Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:7| OREF_RI, Rank idle period that defines an oppertunity for | -| | refresh | -+-----------+------------------------------------------------------------------+ -| 8:11| Refresh_HP_WM, tREFI count level that turns the refresh | -| | priority to high | -+-----------+------------------------------------------------------------------+ -| 12:15| Refresh_panic_WM, tREFI count level in which the refresh | -| | priority is panic | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x4e98** - -*Width:* 40 Bit - -*Desc:* TC - Refresh parameters Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:15| tREFI, average period between refresh in DCLK cycles | -+-----------+------------------------------------------------------------------+ -| 16:24| tRFC, Time of refresh, from beginning of refresh until next ACT | -| | or refresh is allowed in DCLK cycles | -+-----------+------------------------------------------------------------------+ -| 25:32| tREFIx9, Maximum time allowed between refreshes to a rank. | -| | Should be programmed to 8.9 * tREFI / 1024 | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5000** - -*Width:* 8 Bit - -*Desc:* Global channel size control Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:1| CH_A, defines the largest channel. | -| | - 00b: Channel 0, | -| | - 01b: Channel 1, | -| | - 10b: Channel 2 | -+-----------+------------------------------------------------------------------+ -| 2:3| CH_B, defines the mid-size channel. | -| | - 00b: Channel 0, | -| | - 01b: Channel 1, | -| | - 10b: Channel 2 | -+-----------+------------------------------------------------------------------+ -| 2:3| CH_C, defines the smallest channel. | -| | - 00b: Channel 0, | -| | - 01b: Channel 1, | -| | - 10b: Channel 2, CH_C is 10 if only 2 channels are supported | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5004** - -*Width:* 32 Bit - -*Desc:* Address Decode Register, Channel 0 - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:7| DIMMA size in 256 MB multiples | -+-----------+------------------------------------------------------------------+ -| 16 | DIMM A select (DAS) Slot to DIMM mapping, | -| | - 0: DIMMA, DIMMB, | -| | - 1: DIMMB, DIMMA | -+-----------+------------------------------------------------------------------+ -| 17 | DIMM A number of ranks | -+-----------+------------------------------------------------------------------+ -| 19 | DIMM A DRAM width x8 / x16 | -+-----------+------------------------------------------------------------------+ -| 8:15| DIMM B size in 256 MB multiples | -+-----------+------------------------------------------------------------------+ -| 18 | DIMM B number of ranks | -+-----------+------------------------------------------------------------------+ -| 20 | DIMM B DRAM width in 8x / x16 | -+-----------+------------------------------------------------------------------+ -| 21 | Rank interleave enable | -+-----------+------------------------------------------------------------------+ -| 22 | Enhanced interleave enable | -+-----------+------------------------------------------------------------------+ -| 26 | High order Rank interleave enable | -+-----------+------------------------------------------------------------------+ -| 27:29| High Order Rank interleave Address. Selects on of address bits | -| | 20-27 to use for high rank interleave | -+-----------+------------------------------------------------------------------+ -| 24:25| ECC, | -| | - 00b: No ECC active, | -| | - 01b: ECC is active on IO, | -| | - 11b: ECC is active on both IO and ECC logic | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5030** - -*Width:* 8 Bit - -*Desc:* Global DDR3 control Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 1 | DDR reset | -+-----------+------------------------------------------------------------------+ -| 2 | DCLK enable | -+-----------+------------------------------------------------------------------+ -| 5 | IO reset | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5034** - -*Width:* 32 Bit - -*Desc:* Version Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:31| MRC version | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5060** - -*Width:* 16 Bit - -*Desc:* PM - Self refresh config Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:15| Idle_timer, The value is used when the SREF_enable field is set | -| | and defines the # of cycles that there should not be any | -| | transaction in order to enter self-refresh. | -+-----------+------------------------------------------------------------------+ -| 16 | SR_Enable, enable self-refresh mechanism. Clear SREF_en and | -| | SREF_exit first. | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5084** - -*Width:* 24 Bit - -*Desc:* RCOMP status Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 16 | Busy | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5090** - -*Width:* 32 Bit - -*Desc:* ECC - Address compare for ECC error injection Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:31| Inject error when ECC_Inj_Addr_Compare[31:0] = ADDR[37:6] | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5094** - -*Width:* 32 Bit - -*Desc:* ECC - Address mask for ECC error injection Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:31| Inject error when ECC_inj_Addr_Compare[31:0] = | -| | ADDR[37:6] && ECC_Inj_Addr_Mask[31:0] | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5e00** - -*Width:* 32 Bit - -*Desc:* MC_BIOS_REQ Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:7| Selected multiplier: 100Mhz [7,12], 133Mhz [3,19] | -+-----------+------------------------------------------------------------------+ -| 8 | - 1: 100Mhz reference clock | -| | - 0: 133Mhz reference clock (IvyBridge only) | -+-----------+------------------------------------------------------------------+ -| 31 | PLL busy | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5e04** - -*Width:* 8 Bit - -*Desc:* MC_BIOS_DATA Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 0:7| Active multiplier: | -| | - 100Mhz [7,12], | -| | - 133Mhz [3,19] | -+-----------+------------------------------------------------------------------+ -``` - -**MCHBAR + 0x5f08** - -*Width:* 16 Bit - -*Desc:* RCOMP control Register - -```eval_rst -+-----------+------------------------------------------------------------------+ -| Bit | Description | -+===========+==================================================================+ -| 8 | Force RCOMP | -+-----------+------------------------------------------------------------------+ diff --git a/Documentation/Intel/NativeRaminit/Sandybridge.md b/Documentation/Intel/NativeRaminit/Sandybridge.md deleted file mode 100644 index 5c83a0dad2..0000000000 --- a/Documentation/Intel/NativeRaminit/Sandybridge.md +++ /dev/null @@ -1,135 +0,0 @@ -# Sandy Bridge Raminit - -## Introduction - -This documentation is intended to document the closed source memory controller -hardware for Intel 2nd Gen (Sandy Bride) and 3rd Gen (Ivy Bridge) core-i CPUs. - -The memory initialization code has to take care of lots of duties: -1. Selection of operating frequency -* Selection of common timings -* Applying frequency specific compensation values -* Read training of all populated channels -* Write training of all populated channels -* Adjusting delay networks of address and command signals -* DQS training of all populated channels -* Programming memory map -* Report DRAM configuration -* Error handling - -## Definitions -```eval_rst -+---------+-------------------------------------------------------------------+------------+--------------+ -| Symbol | Description | Units | Valid region | -+=========+===================================================================+============+==============+ -| SCK | DRAM system clock cycle time | s | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| tCK | DRAM system clock cycle time | 1/256th ns | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| DCK | Data clock cycle time: The time between two SCK clock edges | s | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) | -+---------+-------------------------------------------------------------------+------------+--------------+ -| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| REFCK | Reference clock, either 100 or 133 | Mhz | 100, 133 | -+---------+-------------------------------------------------------------------+------------+--------------+ -| MULT | DRAM PLL multiplier | | [3-12] | -+---------+-------------------------------------------------------------------+------------+--------------+ -| XMP | Extreme Memory Profiles | | | -+---------+-------------------------------------------------------------------+------------+--------------+ -``` - -## (Inoffical) register documentation -- [Sandy Bride - Register documentation](SandyBridge_registers.md) - -## Frequency selection -- [Sandy Bride - Frequency selection](Sandybridge_freq.md) - -## Read training -- [Sandy Bride - Read training](Sandybridge_read.md) - -### SMBIOS type 17 -The SMBIOS specification allows to report the memory configuration in use. -On GNU/Linux you can run `# dmidecode -t 17` to view it. -Example output of dmidecode: - -``` -Handle 0x0045, DMI type 17, 34 bytes - Memory Device - Array Handle: 0x0042 - Error Information Handle: Not Provided - Total Width: 64 bits - Data Width: 64 bits - Size: 8192 MB - Form Factor: DIMM - Set: None - Locator: ChannelB-DIMM0 - Bank Locator: BANK 2 - Type: DDR3 - Type Detail: Synchronous - Speed: 933 MHz - Manufacturer: 0420 - Serial Number: 00000000 - Asset Tag: 9876543210 - Part Number: F3-1866C9-8GSR - Rank: 2 - Configured Clock Speed: 933 MHz -``` -The memory frequency printed by dmidecode is the active memory frequency. It's -**not** the double datarate and it's **not** the one encoded maximum frequency -in each DIMM's SPD. - -> **Note:** This feature is available since coreboot 4.4 - -### MRC cache -The name *MRC cache* might be missleading as in case of *Native ram init* -there's no MRC, but for historical reasons it's still named *MRC cache*. -The MRC cache is part of flash memory that is writeable by coreboot. -At the end of the boot process coreboot will write the RAM training results to -flash for future use, as RAM training is time intensive. Storing the results -allows to boot faster on normal boot and allows to support S3 resume, -as the RAM training results can't be stored in RAM (you need to configure -the memory controller first to access RAM). - -The MRC cache needs to be invalidated in case the memory configuration has -been changed. To detect a changed memory configuration the CRC16 of each DIMM -is stored to MRC cache. -> **Note:** This feature is available since coreboot 4.4 - -### Error handling -As of writing the only supported error handling is to disable the failing -channel and restart the memory training sequence. It's very likely to succeed, -as memory channels operate independent of each other. -In case no DIMM could be initilized coreboot will halt. The screen will stay -black until you power of your device. On some platforms there's additional -feedback to indicate such an event. - -If you find `dmidecode -t 17` to report only half of the memory installed, -it's likely that a fatal memory init failure had happened. -It is assumed, that a working board with less physical memory, is much better, -than a board that doesn't boot at all. - -> **Note:** This feature is available since coreboot 4.5 - -Try to swap memory modules and or try to use a different vendor. If nothing -helps you could have a look at capter [Debuggin] or report a ticket -at [ticket.coreboot.org]. Please provide a full RAM init log, -that has been captured using EHCI debug. - -To enable extensive RAM training logging enable the Kconfig option -`DEBUG_RAM_SETUP` -#### Lenovo Thinkpads -Lenovo Thinkpads do have an additional feature to indicate that RAM init has -failed and coreboot has died (it calls die() on fatal error, thus the name). -The Kconfig options -`H8_BEEP_ON_DEATH` -`H8_FLASH_LEDS_ON_DEATH` -enable blinking LEDs and enable a beep to indicate death. - -> **Note:** This feature is available since coreboot 4.7 - -## Debugging -It's recommended to use an external debugger, such as serial or EHCI debug -dongle. In case of failing memory init the board might not boot at all, -preventing you from using CBMEM. diff --git a/Documentation/Intel/NativeRaminit/Sandybridge_freq.md b/Documentation/Intel/NativeRaminit/Sandybridge_freq.md deleted file mode 100644 index d8b73b3aec..0000000000 --- a/Documentation/Intel/NativeRaminit/Sandybridge_freq.md +++ /dev/null @@ -1,165 +0,0 @@ -# Frequency selection - -## Introduction -This chapter explains the frequency selection done on Sandybride and Ivybridge. - -## Definitions -```eval_rst -+---------+-------------------------------------------------------------------+------------+--------------+ -| Symbol | Description | Units | Valid region | -+=========+===================================================================+============+==============+ -| SCK | DRAM system clock cycle time | s | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| tCK | DRAM system clock cycle time | 1/256th ns | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| DCK | Data clock cycle time: The time between two SCK clock edges | s | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 | -+---------+-------------------------------------------------------------------+------------+--------------+ -| MULT | DRAM PLL multiplier | | [3-12] | -+---------+-------------------------------------------------------------------+------------+--------------+ -| XMP | Extreme Memory Profiles | | | -+---------+-------------------------------------------------------------------+------------+--------------+ -``` -## SPD -The [SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect") -located on every DIMM is factory program with various timings. One of them -specifies the maximum clock frequency the DIMM should be used with. The -operating frequency is stores as fixed point value (tCK), rounded to the next -smallest supported operating frequency. Some -[SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect") -contains additional and optional -[XMP](https://de.wikipedia.org/wiki/Extreme_Memory_Profile "Extreme Memory Profile") -data, that stores so called "performance" modes, that advertises higher clock -frequencies. - -## XMP profiles -At time of writing coreboot's raminit is able to parse XMP profile 1 and 2. -Only **XMP profile 1** is being used in case it advertises: -* 1.5V operating voltage -* The channel's installed DIMM count doesn't exceed the XMP coded limit - -In case the XMP profile doesn't fullfill those limits, the regular SPD will be -used. -> **Note:** XMP Profiles are supported since coreboot 4.4. - -It is possible to ignore the max DIMM count limit set by XMP profiles. -By activating Kconfig option `NATIVE_RAMINIT_IGNORE_XMP_MAX_DIMMS` it is -possible to install two DIMMs per channel, even if XMP tells you not to do. - -> **Note:** Ignoring XMP Profiles limit is supported since coreboot 4.7. - -## Soft fuses -Every board manufacturer does program "soft" fuses to indicate the maximum -DRAM frequency supported. However, those fuses don't set a limit in hardware -and thus are called "soft" fuses, as it is possible to ignore them. - -> **Note:** Ignoring the fuses might cause system instability ! - -On Sandy Bride *CAPID0_A* is being read, and on Ivybridge *CAPID0_B* is being -read. coreboot reads those registers and honors the limit in case the Kconfig -option `CONFIG_NATIVE_RAMINIT_IGNORE_MAX_MEM_FUSES` wasn't set. -Power users that want to let their RAM run at DRAM's "stock" frequency need to -enable the Kconfig symbol. - -It is possible to override the soft fuses limit by using a board-specific -[devicetree](#devicetree) setting. - -> **Note:** Ignoring max mem freq. fuses is supported since coreboot 4.7. - -## Hard fuses -"Hard" fuses are programmed by Intel and limit the maximum frequency that can -be used on a given CPU/board/chipset. At time of writing there's no register -to read this limit, before trying to set a given DRAM frequency. The memory PLL -won't lock, indicating that the chosen memory multiplier isn't available. In -this case coreboot tries the next smaller memory multiplier until the PLL will -lock. - -## Devicetree -The devicetree register `max_mem_clock_mhz` overrides the "soft" fuses set -by the board manufacturer. - -By using this register it's possible to force a minimum operating frequency. - -## Reference clock -While Sandybride supports 133 MHz reference clock (REFCK), Ivy Bridge also -supports 100 MHz reference clock. The reference clock is multiplied by the DRAM -multiplier to select the DRAM frequency (SCK) by the following formula: - - REFCK * MULT = 1 / DCK - -> **Note:** Since coreboot 4.6 Ivy Bridge supports 100MHz REFCK. - -## Sandy Bride's supported frequencies -```eval_rst -+------------+-----------+------------------+-------------------------+---------------+ -| SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment | -+============+===========+==================+=========================+===============+ -| 400 | DDR3-800 | 3 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 533 | DDR3-1066 | 4 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 666 | DDR3-1333 | 5 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 800 | DDR3-1600 | 6 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 933 | DDR3-1866 | 7 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 1066 | DDR3-2166 | 8 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -``` - -## Ivybridge's supported frequencies -```eval_rst -+------------+-----------+------------------+-------------------------+---------------+ -| SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment | -+============+===========+==================+=========================+===============+ -| 400 | DDR3-800 | 3 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 533 | DDR3-1066 | 4 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 666 | DDR3-1333 | 5 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 800 | DDR3-1600 | 6 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 933 | DDR3-1866 | 7 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 1066 | DDR3-2166 | 8 | 133 MHz | | -+------------+-----------+------------------+-------------------------+---------------+ -| 700 | DDR3-1400 | 7 | 100 MHz | '1 | -+------------+-----------+------------------+-------------------------+---------------+ -| 800 | DDR3-1600 | 8 | 100 MHz | '1 | -+------------+-----------+------------------+-------------------------+---------------+ -| 900 | DDR3-1800 | 9 | 100 MHz | '1 | -+------------+-----------+------------------+-------------------------+---------------+ -| 1000 | DDR3-2000 | 10 | 100 MHz | '1 | -+------------+-----------+------------------+-------------------------+---------------+ -| 1100 | DDR3-2200 | 11 | 100 MHz | '1 | -+------------+-----------+------------------+-------------------------+---------------+ -| 1200 | DDR3-2400 | 12 | 100 MHz | '1 | -+------------+-----------+------------------+-------------------------+---------------+ -``` -> '1: since coreboot 4.6 - -## Multiplier selection -coreboot select the maximum frequency to operate at by the following formula: -``` -if devicetree's max_mem_clock_mhz > 0: - freq_max := max_mem_clock_mhz -else: - freq_max := soft_fuse_max_mhz - -for i in SPDs: - freq_max := MIN(freq_max, ddr_spd_max_mhz[i]) -``` - -As you can see, by using DIMMs with different maximum DRAM frequencies, the -slowest DIMMs' frequency will be selected, to prevent over-clocking it. - -The selected frequency gives the PLL multiplier to operate at. In case the PLL -locks (see Take me to [Hard fuses](#hard_fuses)) the frequency will be used for -all DIMMs. At this point it's not possible to change the multiplier again, -until the system has been powered off. In case the PLL doesn't lock, the next -smaller multiplier will be used until a working multiplier will be found. diff --git a/Documentation/Intel/NativeRaminit/Sandybridge_read.md b/Documentation/Intel/NativeRaminit/Sandybridge_read.md deleted file mode 100644 index 0496657b3f..0000000000 --- a/Documentation/Intel/NativeRaminit/Sandybridge_read.md +++ /dev/null @@ -1,153 +0,0 @@ -# Read training - -## Introduction - -This chapter explains the read training sequence done on Sandy Bride and -Ivy Bridge memory initialization. - -Read training is done to compensate the skew between DQS and SCK and to find -the smallest supported roundtrip delay. - -Every board does have a vendor depended routing topology, and can be equip -with any combination of DDR3 memory modules, that introduces different -skew between the memory lanes. With DDR3 a "Fly-By" routing topology -has been introduced, that makes the biggest part of DQS-SCK skew. -The memory code measures the actual skew and actives delay gates, -that will "compensate" the skew. - -When in read training the DRAM and the controller are placed in a special mode. -On every read instruction the DRAM outputs a predefined pattern and the memory -controller samples the DQS after a given delay. As the pattern is known, the -actual delay of every lane can be measured. - -The values programmed in read training effect DRAM-to-MC transfers only ! - -## Definitions -```eval_rst -+---------+-------------------------------------------------------------------+------------+--------------+ -| Symbol | Description | Units | Valid region | -+=========+===================================================================+============+==============+ -| SCK | DRAM system clock cycle time | s | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| tCK | DRAM system clock cycle time | 1/256th ns | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| DCK | Data clock cycle time: The time between two SCK clock edges | s | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) | -+---------+-------------------------------------------------------------------+------------+--------------+ -| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 | -+---------+-------------------------------------------------------------------+------------+--------------+ -| MULT | DRAM PLL multiplier | | [3-12] | -+---------+-------------------------------------------------------------------+------------+--------------+ -| XMP | Extreme Memory Profiles | | | -+---------+-------------------------------------------------------------------+------------+--------------+ -| DQS | Data Strobe signal used to sample all lane's DQ signals | | | -+---------+-------------------------------------------------------------------+------------+--------------+ -``` -## Hardware -The hardware does have delay logic blocks that can delay the DQ / DQS of a -lane/rank by one or multiple clock cylces and it does have delay logic blocks -that can delay the signal by a multiple of 1/64th DCK per lane. - -All delay values can be controlled via software by writing registers in the -MCHBAR. - -## IO phase - -The IO phase can be adjusted in [0-512) * 1/64th DCK. Incrementing it by 64 is -the same as Incrementing IO delay by 1. - -## IO delay -Delays the DQ / DQS signal by one or multiple clock cycles. - -### Roundtrip time -The roundtrip time is the time the memory controller waits for data arraving -after a read has been issued. Due to clock-domain crossings, multiple -delay instances and phase interpolators, the signal runtime to DRAM and back -to memory controller defaults to 55 DCKs. The real roundtrip time has to be -measured. - -After a read command has been issued, a counter counts down until zero has been -reached and activates the input buffers. - -The following pictures shows the relationship between those three values. -The picture was generated from 16 IO delay values times 64 timA values. -The highest IO delay was set on the right-hand side, while the last block -on the left-hand side has zero IO delay. - -#### roundtrip 55 DCKs -![timA for lane0 - lane3, roundtrip 55][timA_lane0-3_rt55] - -[timA_lane0-3_rt55]: timA_lane0-3_rt55.png - -#### roundtrip 54 DCKs -![timA for lane0 - lane3, roundtrip 54][timA_lane0-3_rt54] - -[timA_lane0-3_rt54]: timA_lane0-3_rt54.png - - -#### roundtrip 53 DCKs -![timA for lane0 - lane3, roundtrip 53][timA_lane0-3_rt53] - -[timA_lane0-3_rt53]: timA_lane0-3_rt53.png - -As you can see the signal has some jitter as every sample was taken in a -different loop iteration. The result register only contains a single bit per -lane. - -## Algorithm -### Steps -The algorithm finds the roundtrip time, IO delay and IO phase. The IO phase -will be adjusted to match the falling edge of the preamble of each lane. -The roundtrip time is adjusted to an minimal value, that still includes the -preamble. - -### Synchronize to data phase - -The first measurement done in read-leveling samples all DQS values for one -phase [0-64) * 1/64th DCK. It then searches for the middle of the low data -symbol and adjusts timA to the found phase and thus the following measurements -will be aligned to the low data symbol. -The code assumes that the initial roundtrip time causes the measurement to be -in the alternating pattern data phase. - -### Finding the preamble -After adjusting the IO phase to the middle of one data symbol the preamble will -be located. Unlike the data phase, which is an alternating pattern (010101...), -the preamble consists of two high data cycles. - -The code decrements the IO delay/RTT and samples the DQS signal with timA -untouched. As it has been positioned in the middle of the data symbol, it'll -read as either "low" or "high". - -If it's "low" we are still in the data phase. -If it's "high" we have found the preamble. - -The roundtrip time and IO delay will be adjusted until all lanes are aligned. -The resulting IO delay is visible in the picture below. - -**roundtrip time: 49 DCKs, IO delay (at blue point): 6 DCKs** -![timA for lane0 - lane3, finding minimum roundtrip time][timA_lane0-3_discover_420x] - -[timA_lane0-3_discover_420x]: timA_lane0-3_discover_420x.png - -**Note: The sampled data has been shifted by timA. The preamble is now -in phase.** - -## Fine adjustment - -As timA still points the middle of the data symbol an offset of 32 is added. -It now points the falling edge of the preamble. -The fine adjustment is to reduce errors introduced by jitter. The phase is -adjusted from `timA - 25` to `timA + 25` and the DQS signal is sampled 100 -times. The fine adjustment finds the middle of each rising edge (it's actual -the falling edge of the preamble) to get the final IO phase. You can see the -result in the picture below. - -![timA for lane0 - lane3, fine adjustment][timA_lane0-3_adjust_fine] - -[timA_lane0-3_adjust_fine]: timA_lane0-3_adjust_fine.png - -Lanes 0 - 2 will be adjusted by a phase of -10, while lane 3 is already correct. diff --git a/Documentation/Intel/NativeRaminit/timA_lane0-3_adjust_fine.png b/Documentation/Intel/NativeRaminit/timA_lane0-3_adjust_fine.png deleted file mode 100644 index d72e4c6d84..0000000000 Binary files a/Documentation/Intel/NativeRaminit/timA_lane0-3_adjust_fine.png and /dev/null differ diff --git a/Documentation/Intel/NativeRaminit/timA_lane0-3_discover_420x.png b/Documentation/Intel/NativeRaminit/timA_lane0-3_discover_420x.png deleted file mode 100644 index 6f33217d1e..0000000000 Binary files a/Documentation/Intel/NativeRaminit/timA_lane0-3_discover_420x.png and /dev/null differ diff --git a/Documentation/Intel/NativeRaminit/timA_lane0-3_rt53.png b/Documentation/Intel/NativeRaminit/timA_lane0-3_rt53.png deleted file mode 100644 index 191e792845..0000000000 Binary files a/Documentation/Intel/NativeRaminit/timA_lane0-3_rt53.png and /dev/null differ diff --git a/Documentation/Intel/NativeRaminit/timA_lane0-3_rt54.png b/Documentation/Intel/NativeRaminit/timA_lane0-3_rt54.png deleted file mode 100644 index fa7f6089d0..0000000000 Binary files a/Documentation/Intel/NativeRaminit/timA_lane0-3_rt54.png and /dev/null differ diff --git a/Documentation/Intel/NativeRaminit/timA_lane0-3_rt55.png b/Documentation/Intel/NativeRaminit/timA_lane0-3_rt55.png deleted file mode 100644 index 7f2fa397dd..0000000000 Binary files a/Documentation/Intel/NativeRaminit/timA_lane0-3_rt55.png and /dev/null differ diff --git a/Documentation/Lesson1.md b/Documentation/Lesson1.md deleted file mode 100644 index 0a10ba3723..0000000000 --- a/Documentation/Lesson1.md +++ /dev/null @@ -1,168 +0,0 @@ -coreboot lesson 1 - Starting from scratch -========================================= - -From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for -a very basic build: - -Download, configure, and build coreboot ---------------------------------------- - -### Step 1 - Install tools and libraries needed for coreboot - $ sudo apt-get install -y bison build-essential curl flex git gnat-5 libncurses5-dev m4 zlib1g-dev - -### Step 2 - Download coreboot source tree - $ git clone https://review.coreboot.org/coreboot - $ cd coreboot - -### Step 3 - Build the coreboot toolchain -Please note that this can take a significant amount of time - - $ make crossgcc-i386 CPUS=$(nproc) - -Also note that you can possibly use your system toolchain, but the results are -not reproducible, and may have issues, so this is not recommended. See step 5 -to use your system toolchain. - -### Step 4 - Build the payload - coreinfo - $ make -C payloads/coreinfo olddefconfig - $ make -C payloads/coreinfo - -### Step 5 - Configure the build - -* ##### Configure your mainboard - $ make menuconfig - select 'Mainboard' menu - Beside 'Mainboard vendor' should be '(Emulation)' - Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4' - select < Exit > -These should be the default selections, so if anything else was set, run -`make distclean` to remove your old config file and start over. - -* ##### Optionally use your system toolchain (Again, not recommended) - select 'General Setup' menu - select 'Allow building with any toolchain' - select < Exit > - -* ##### Select the payload - select 'Payload' menu - select 'Add a Payload' - choose 'An Elf executable payload' - select 'Payload path and filename' - enter 'payloads/coreinfo/build/coreinfo.elf' - select < Exit > - select < Exit > - select < Yes > - -##### check your configuration (optional step): - - $ make savedefconfig - $ cat defconfig - -There should only be two lines (or 3 if you're using the system toolchain): - - CONFIG_PAYLOAD_ELF=y - CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf" - -### Step 6 - build coreboot - $ make - -At the end of the build, you should see: - - Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4) - -This means your build was successful. The output from the build is in the build -directory. build/coreboot.rom is the full rom file. - -Test the image using QEMU -------------------------- - -### Step 7 - Install QEMU - $ sudo apt-get install -y qemu - -### Step 8 - Run QEMU -Start QEMU, and point it to the ROM you just built: - - $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio - -You should see the serial output of coreboot in the original console window, and -a new window will appear running the coreinfo payload. - -Summary -------- - -### Step 1 summary - Install tools and libraries needed for coreboot -You installed the minimum additional requirements for ubuntu to download and -build coreboot. Ubuntu already has most of the other tools that would be -required installed by default. - -* `build-essential` is the basic tools for doing builds. It comes pre-installed -on some Ubuntu flavors, and not on others. -* `git` is needed to download coreboot from the coreboot git repository. -* `libncurses5-dev` is needed to build the menu for 'make menuconfig' -* `m4, bison, curl, flex, gnat-5, zlib1g-dev` are needed to build the coreboot -toolchain. - -If you started with a different distribution, you might need to install many -other items which vary by distribution. - -### Step 2 summary - Download coreboot source tree -This will download a 'read-only' copy of the coreboot tree. This just means -that if you made changes to the coreboot tree, you couldn't immediately -contribute them back to the community. To pull a copy of coreboot that would -allow you to contribute back, you would first need to sign up for an account on -gerrit. - -### Step 3 summary - Build the coreboot toolchain. -This builds one of the coreboot cross-compiler toolchains for X86 platforms. -Because of the variability of compilers and the other required tools between -the various operating systems that coreboot can be built on, coreboot supplies -and uses its own cross-compiler toolchain to build the binaries that end up as -part of the coreboot ROM. The toolchain provided by the operating system (the -'host toolchain') is used to build various tools that will run on the local -system during the build process. - -### Step 4 summary - Build the payload -To actually do anything useful with coreboot, you need to build a payload to -include in the rom. The idea behind coreboot is that it does the minimum amount -possible before passing control of the machine to a payload. There are various -payloads such as grub or SeaBIOS that are typically used to boot the operating -system. Instead, we used coreinfo, a small demonstration payload that allows the -user to look at various things such as memory and the contents of coreboot's -cbfs - the pieces that make up the coreboot rom. - -### Step 5 summary - Configure the build -This step configures coreboot's build options using the menuconfig interface to -Kconfig. Kconfig is the same configuration program used by the linux kernel. It -allows you to enable, disable, and change various values to control the coreboot -build process, including which mainboard(motherboard) to use, which toolchain to -use, and how the runtime debug console should be presented and saved. -Anytime you change mainboards in Kconfig, you should always run `make distclean` -before running `make menuconfig`. Due to the way that Kconfig works, values will -be kept from the previous mainboard if you skip the clean step. This leads to a -hybrid configuration which may or may not work as expected. - -### Step 6 summary - Build coreboot -You may notice that a number of other pieces are downloaded at the beginning of -the build process. These are the git submodules used in various coreboot builds. -By default, the BLOBS submodule is not downloaded. This git submodule may be -required for other builds for microcode or other binaries. To enable downloading -this submodule, select the option "Allow use of binary-only repository" in the -"General Setup" menu of Kconfig -This attempts to build the coreboot rom. The rom file itself ends up in the -build directory as 'coreboot.rom'. At the end of the build process, the build -displayed the contents of the rom file. - -### Step 7 summary - Install QEMU -QEMU is a processor emulator which we can use to show coreboot - -### Step 8 summary - Run QEMU -Here's the command line broken down: -* `qemu-system-x86_64` -This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to -ISA bridge. -* `-bios build/coreboot.rom` -Use the bios rom image that we just built. If this is left off, the standard -SeaBIOS image that comes with QEMU is used. -* `-serial stdio` -Send the serial output to the console. This allows you to view the coreboot -debug output. diff --git a/Documentation/Lesson2.md b/Documentation/Lesson2.md deleted file mode 100644 index ec929c8014..0000000000 --- a/Documentation/Lesson2.md +++ /dev/null @@ -1,281 +0,0 @@ -# coreboot Lesson 2: Submitting a patch to coreboot.org - -## Part 1: Setting up an account at coreboot.org - -If you already have an account, skip to Part 2. - -Otherwise, go to in your preferred web browser. -Select **Register** in the upper right corner. - -Select the appropriate sign-in. For example, if you have a Google account, -select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your -username for the account will be the username of the account you used to -sign-in with. (ex. your Google username). - -## Part 2a: Set up RSA Private/Public Key - -If you prefer to use an HTTP password instead, skip to Part 2b. - -For the most up-to-date instructions on how to set up SSH keys with Gerrit go to - -and follow the instructions there. Then, skip to Part 3. - -Additionally, that section of the Web site provides explanation on starting -an ssh-agent, which may be particularly helpful for those who anticipate -frequently uploading changes. - -If you instead prefer to have review.coreboot.org specific instructions, -follow the steps below. Note that this particular section may have the -most up-to-date instructions. - -If you do not have an RSA key set up on your account already (as is the case -with a newly created account), follow the instructions below; otherwise, -doing so could overwrite an existing key. - -In the upper right corner, select your name and click on **Settings**. -Select **SSH Public Keys** on the left-hand side. - -In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa". - -Make a passphrase -- remember this phrase. It will be needed whenever you use -this RSA Public Key. **Note:** You might want to use a short password, or -forego the password altogether as you will be using it very often. - -Open "id_rsa.pub", copy all contents and paste into the textbox under -"Add SSH Public Key" in the https://review.coreboot.org webpage. - -## Part 2b: Setting up an HTTP Password - -Alternatively, instead of using SSH keys, you can use an HTTP password. To do so, -after you select your name and click on **Settings** on the left-hand side, rather -than selecting **SSH Public Keys**, select **HTTP Password**. - -Click **Generate Password**. This should fill the "Password" box with a password. Copy -the password, and add the following to your $HOME/.netrc file: - - machine review.coreboot.org login YourUserNameHere password YourPasswordHere - -where YourUserNameHere is your username, and YourPasswordHere is the password you -just generated. - -## Part 3: Clone coreboot and configure it for submitting patches - -Go to the **Projects** tab in the upper left corner and select **List**. -From the dropdown menu that appears, select "coreboot". - -If you are using SSH keys, select **ssh** from the tabs under "Project coreboot" -and run the command that appears. This should prompt you for your id_rsa passphrase, -if you previously set one. - -If you are using HTTP, instead, select **http** from the tabs under "Project coreboot" -and run the command that appears - -After it finishes cloning, "cd coreboot" will take you into the local -git repository. Run "make gitconfig" to set up the hooks and configurations. -For example, you will be asked to run the following commands to set your -username and email. - - git config --global user.name "Your Name" - git config --global user.email "Your Email" - -## Part 4: Submit a commit - -An easy first commit to make is fixing existing checkpatch errors and warnings -in the source files. To see errors that are already present, build the files in -the repository by running 'make lint' in the coreboot directory. Alternatively, -if you want to run 'make lint' on a specific directory, run: - - for file in $(git ls-files | grep src/amd/quadcore); do \ - util/lint/checkpatch.pl --file $file --terse; done - -where is the filepath of the directory (ex. src/cpu/amd/car). - -Any changes made to files under the src directory are made locally, -and can be submitted for review. - -Once you finish making your desired changes, use the command line to stage -and submit your changes. An alternative and potentially easier way to stage -and submit commits is to use git cola, a graphical user interface for git. For -instructions on how to do so, skip to Part 4b. - -## Part 4a: Using the command line to stage and submit a commit - -To use the command line to stage a commit, run - - git add - -where `filename` is the name of your file. - -To commit the change, run - - git commit -s - -**Note:** The -s adds a signed-off-by line by the committer. Your commit should be -signed off with your name and email (i.e. **Your Name** ****, based on -what you set with git config earlier). - -Running git commit first checks for any errors and warnings using lint. If -there are any, you must go back and fix them before submitting your commit. -You can do so by making the necessary changes, and then staging your commit again. - -When there are no errors or warnings, your default text editor will open. -This is where you will write your commit message. - -The first line of your commit message is your commit summary. This is a brief -one-line description of what you changed in the files using the template -below: - -: Short description -*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors* -**Note:** It is good practice to use present tense in your descriptions -and do not punctuate your summary. - -Then hit Enter. The next paragraph should be a more in-depth explanation of the -changes you've made to the files. Again, it is good practice to use present -tense. -*ex. Fix space prohibited between function name and open parenthesis, -line over 80 characters, unnecessary braces for single statement blocks, -space required before open brace errors and warnings.* - -When you have finished writing your commit message, save and exit the text -editor. You have finished committing your change. If, after submitting your -commit, you wish to make changes to it, running "git commit --amend" allows -you to take back your commit and amend it. - -When you are done with your commit, run 'git push' to push your commit to -coreboot.org. **Note:** To submit as a draft, use -'git push origin HEAD:refs/drafts/master' Submitting as a draft means that -your commit will be on coreboot.org, but is only visible to those you add -as reviewers. - -## Part 4b: Using git cola to stage and submit a commit - -If git cola is not installed on your machine, see -https://git-cola.github.io/downloads.html for download instructions. - -After making some edits to src files, rather than run "git add," run -'git cola' from the command line. You should see all of the files -edited under "Modified". - -In the textbox labeled "Commit summary" provide a brief one-line -description of what you changed in the files according to the template -below: - -: Short description -*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors* -**Note:** It is good practice to use present tense in your descriptions -and do not punctuate your short description. - -In the larger text box labeled 'Extended description...' provide a more -in-depth explanation of the changes you've made to the files. Again, it -is good practice to use present tense. -*ex. Fix space prohibited between function name and open parenthesis, -line over 80 characters, unnecessary braces for single statement blocks, -space required before open brace errors and warnings.* - -Then press Enter two times to move the cursor to below your description. -To the left of the text boxes, there is an icon with an downward arrow. -Press the arrow and select "Sign Off." Make sure that you are signing off -with your name and email (i.e. **Your Name** ****, based on what -you set with git config earlier). - -Now, review each of your changes and mark either individual changes or -an entire file as Ready to Commit by marking it as 'Staged'. To do -this, select one file from the 'Modified' list. If you only want to -submit particular changes from each file, then highlight the red and -green lines for your changes, right click and select 'Stage Selected -Lines'. Alternatively, if an entire file is ready to be committed, just -double click on the file under 'Modified' and it will be marked as -Staged. - -Once the descriptions are done and all the edits you would like to -commit have been staged, press 'Commit' on the right of the text -boxes. - -If the commit fails due to persisting errors, a text box will appear -showing the errors. You can correct these errors within 'git cola' by -right-clicking on the file in which the error occurred and selecting -'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and -'Stage' the corrected file again. It might be necessary to refresh -'git cola' in order for the file to be shown under 'Modified' again. -Note: Be sure to add any other changes that haven't already been -explained in the extended description. - -When ready, select 'Commit' again. Once all errors have been satisfied -and the commit succeeds, move to the command line and run 'git push'. -**Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master' -Submitting as a draft means that your commit will be on coreboot.org, but is -only visible to those you add as reviewers. - -## Part 5: Getting your commit reviewed - -Your commits can now be seen on review.coreboot.org if you select “My” -and click on “Changes” and can be reviewed by others. Your code will -first be reviewed by build bot (Jenkins), which will either give you a warning -or verify a successful build; if so, your commit will receive a +1. Other -users may also give your commit +1. For a commit to be merged, it needs -to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users -can give a +2. - -## Part 6 (optional): bash-git-prompt - -To help make it easier to understand the state of the git repository -without running 'git status' or 'git log', there is a way to make the -command line show the status of the repository at every point. This -is through bash-git-prompt. - -Instructions for installing this are found at: -https://github.com/magicmonty/bash-git-prompt -**Note:** Feel free to search for different versions of git prompt, -as this one is specific to bash. - -Alternatively, follow the instructions below: -Run the following two commands in the command line: - - cd - git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt --depth=1 - -**Note:** cd will change your directory to your home directory, so the -git clone command will be run there. - -Finally, open the ~/.bashrc file and append the following two lines: - - GIT_PROMPT_ONLY_IN_REPO=1 - source ~/.bash-git-prompt/gitprompt.sh - -Now, whenever you are in a git repository, it will continuously display -its state. - -There also are additional configurations that you can change depending on your -preferences. If you wish to do so, look at the "All configs for .bashrc" section -on https://github.com/magicmonty/bash-git-prompt. Listed in that section are -various lines that you can copy, uncomment and add to your .bashrc file to -change the configurations. Example configurations include avoid fetching remote -status, and supporting versions of Git older than 1.7.10. - -## Appendix: Miscellaneous Advice - -### Updating a commit after running git push: - -Suppose you would like to update a commit that has already been pushed to the -remote repository. If the commit you wish to update is the most recent -commit you have made, after making your desired changes, stage the files -(either using git add or in git cola), and amend the commit. To do so, -if you are using the command line, run "git commit --amend." If you are -using git cola, click on the gear icon located on the upper left side under -**Commit** and select **Amend Last Commit** in the drop down menu. Then, stage -the files you have changed, commit the changes, and run git push to push the -changes to the remote repository. Your change should be reflected in Gerrit as -a new patch set. - -If, however, the commit you wish to update is not the most recent commit you -have made, you will first need to checkout that commit. To do so, find the -URL of the commit on and go to that page; if -the commit is one that you previously pushed, it can be found by selecting -**My** and then **Changes** in the upper left corner. To checkout this commit, -in the upper right corner, click on **Download**, and copy the command listed -next to checkout by clicking **Copy to clipboard**. Then, run the copied -command in your coreboot repository. Now, the last commit should be the most -recent commit to that patch; to update it, make your desired changes, stage -the files, then amend and push the commit using the instructions in the above -paragraph. \ No newline at end of file diff --git a/Documentation/build_system.md b/Documentation/build_system.md deleted file mode 100644 index 787c833d2b..0000000000 --- a/Documentation/build_system.md +++ /dev/null @@ -1,86 +0,0 @@ -# The coreboot build system -(this document is still incomplete and will be filled in over time) - -## General operation -The coreboot build system is based on GNU make but extends it significantly -to the point of providing its own custom language. -The overhead of learning this new syntax is (hopefully) offset by its lower -complexity. - -The build system is defined in the toplevel `Makefile` and `toolchain.inc` -and is supposed to be generic (and is in fact used with a number of other -projects). Project specific configuration should reside in files called -`Makefile.inc`. - -In general, the build system provides a number of "classes" that describe -various parts of the build. These cover the various build targets in coreboot -such as the stages, subdirectories with more source code, and the general -addition of files. - -Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used -by filling in a variable of that name followed by `-y` (eg. `romstage-y`, -`subdirs-y`, `cbfs-files-y`). -The `-y` suffix allows a simple interaction with our Kconfig build -configuration system: Kconfig options are available as variables starting -with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty. - -This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to -`class` depending on the choice for `FOO`. - -## classes -Classes can be defined as required. `subdirs` is handled internally since -it's parsed per subdirectory to add further directories to the rule set. - -TODO: explain how to create new classes and how to evaluate them. - -### subdirs -`subdirs` contains subdirectories (relative to the current directory) that -should also be handled by the build system. The build system expects these -directories to contain a file called `Makefile.inc`. - -Subdirectories are not read at the point where the `subdirs` statement -resides but later, after the current directory is handled (and potentially -others, too). - -### cbfs-files -This class is used to add files to the final CBFS image. Since several more -options need to be maintained than can comfortably fit in that single -variable, additional variables are used. - -`cbfs-files-y` contains the file name used in the CBFS image (called `foo` -here). Additional options are added in `foo-$(option)` variables. The -supported options are: - -* `file`: The on-disk file to add as `foo` (required) -* `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary` - (required) -* `compression`: Can be `none` or `lzma` (default: none) -* `position`: An absolute position constraint for the placement of the file - (default: none) -* `align`: Minimum alignment for the file (default: none) -* `options`: Additional cbfstool options (default: none) - -`position` and `align` are mutually exclusive. - -#### FMAP region support -With the addition of FMAP flash partitioning support to coreboot, there was a -need to extend the specification of files to provide more precise control -which regions should contain which files, and even change some flags based on -the region. - -Since FMAP policies depend on features using FMAP, that's kept separate from -the cbfs-files class. - -The `position` and `align` options for file `foo` can be overwritten for a -region `REGION` using `foo-REGION-position` and `foo-REGION-align`. - -The regions that each file should end in can be defined by overriding a -function called `regions-for-file` that's called as -`$(call regions-for-file,$(filename))` and should return a comma-separated -list of regions, such as `REGION1,REGION2,REGION3`. - -The default implementation just returns `COREBOOT` (the default region) for -all files. - -vboot provides its own implementation of `regions-for-file` that can be used -as reference in `src/vboot/Makefile.inc`. diff --git a/Documentation/core/Kconfig.md b/Documentation/core/Kconfig.md deleted file mode 100644 index 7b436ce80a..0000000000 --- a/Documentation/core/Kconfig.md +++ /dev/null @@ -1,1235 +0,0 @@ -# Kconfig in coreboot - -## Overview -Kconfig is a tool used in coreboot, Linux, and many other projects as the main -configuration mechanism. In coreboot, it allows a developer both to select -which platform to build and to modify various features within the platform. The -Kconfig language was developed as a way to configure the Linux kernel, and is -still maintained as a part of the Linux kernel tree. Starting in Linux 2.5.45, -the ncurses based menuconfig was added, which is still used as the main -configuration front end in coreboot today. - -The official Kconfig source and documentation is kept at kernel.org: - -- [Kconfig source](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig) -- [Kconfig Language Documentation](https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt) - -The advantage to using Kconfig is that it allows users to easily select the -high level features of the project to be enabled or disabled at build time. -Ultimately the Kconfig tool generates a list of values which are used by the -source code and Makefiles of the project. This allows the source files to -select features, and allows the build to determine which files should be -compiled and linked to the rom. - - -## Kconfig targets in Make -The Kconfig program in coreboot is built from source in util/kconfig. There are -various targets in the makefile to build Kconfig in different ways. These give -the user control over how to build the platform - - -### Front end configuration targets -These are the make targets that would be used to update the configuration of -the platform. -- config - Text mode configuration tool, asks each configuration option in turn. - This does actually run in coreboot, but it is recommended that this not be - used as there is no way to save a partial config. -- gconfig - Graphical configuration tool based on GTK+ 2.0. -- menuconfig - Text mode, menu driven configuration tool. -- nconfig - Text mode, menu driven configuration tool. -- xconfig - Graphical front end based on QT. - - -### Targets that update config files -These options are used to update the coreboot config files, typically .config. -The target file can be changed with variables in the environment or on the make -command line. - -- defconfig - This generates a config based on another config file. Use the - environment variable KBUILD_DEFCONFIG to specify the base config file. -- oldconfig - Displays the answers to all configuration questions as it - generates the config.h file. If an interactive question is found that does - not have an answer yet, it stops and queries the user for the desired value. -- olddefconfig - Generates a config, using the default value for any symbols not - listed in the .config file. -- savedefconfig - Creates a ‘mini-config’ file, stripping out all of the symbols - that were left as default values. This is very useful for debugging, and is - how config files should be saved. -- silentoldconfig - This evaluates the .config file the same way that the - oldconfig target does, but does not print out each question as it is - evaluated. It still stops to query the user if an option with no answer in - the .config file is found. - - -### Targets not typically used in coreboot -- localmodconfig, localnoconfig, randconfig, allyesconfig, allnoconfig - These - are all used to generate various Kconfig files for testing. - - -### Environment Variables that affect Kconfig -These variables are typically set in the makefiles or on the make command line. - -#### Variables added to the coreboot Kconfig source -These variables were added to Kconfig specifically for coreboot and are not -included in the Linux version. - -- COREBOOT_BUILD_DIR=path for temporary files. This is used by coreboot’s - abuild tool. - -- KCONFIG_STRICT=value. Define to enable warnings as errors. This is enabled - in coreboot, and should not be changed. - -- KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file - (build/config.h). This is enabled in coreboot, and should not be changed. - - -#### Variables used to control the input and output config files -- KBUILD_DEFCONFIG=inputname of the defconfig file. This defaults to - ‘configs/defconfig’ and is used by the ‘defconfig’ target. - -- DEFCONFIG=output name of the defconfig file. This defaults to ‘defconfig’ - and is used by ‘savedefconfig’ target as the output filename. - -- DOTCONFIG=name of the .config file. This defaults to '.config' and is used - by most config type targets. - - -#### Variables used by the makefiles for controlling Kconfig -- Kconfig=root Kconfig file. This is set to 'src/Kconfig' in the coreboot - makefile. - -- KCONFIG_CONFIG=input config file. coreboot sets this to $(DOTCONFIG). - -- KCONFIG_AUTOHEADER=path and filename of autoconf.h file. coreboot sets this - to $(obj)/config.h. - -- KCONFIG_DEPENDENCIES=”kbuild dependency file". This defaults to - auto.conf.cmd and outputs the name of all of the Kconfig files used. - -- KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”. - coreboot sets this to $(obj)/config. - -#### Used only for ‘make menuconfig’ -- MENUCONFIG_MODE=single_menu. Set to "single_menu" to enable. All other - values disable the option. This makes submenus appear below the menu option - instead of opening a new screen. - -- MENUCONFIG_COLOR=<theme>. This sets the color theme for the menu from - these options: - - - mono => selects colors suitable for monochrome displays. - - blackbg => selects a color scheme with black background. - - classic => theme with blue background. The classic look. - - bluetitle => an LCD friendly version of classic. (default). - - -#### Used only for ‘make nconfig’ - -- NCONFIG_MODE=single_menu - - Submenus appear below the menu option instead of opening a new screen. - - -#### Unused in coreboot - -Although these variables are not used by coreboot, their values should be left -at the default values. Other values may have unexpected effects on the -codebase. - -- KCONFIG_SEED=randconfig seed value. -- KCONFIG_PROBABILITY=randconfig percent to set to y. -- KCONFIG_NOSILENTUPDATE=value. Define to prevent silent updates to .config - file. -- KCONFIG_OVERWRITECONFIG=value. Define to prevent breaking a .config symlink. -- KCONFIG_TRISTATE=filename of tristate.conf file. -- SRCTREE=path to src directory. -- KCONFIG_AUTOCONFIG=path and filename of the auto.conf file. - - coreboot sets this to $(obj)/auto.conf. Although this value is actually - set by coreboot, the resulting file is not used. - -- CONFIG_=prefix for Kconfig output symbols. - - coreboot expects this to *NOT* be set. - - - -## Kconfig Language - -The Kconfig language has about 30 keywords, some overloaded, and some with the -same meaning. Whitespace may have specific meaning, for example in the 'help' -keyword. There are 8 logical operators for use in expressions, which allow -values to be set based on other values. - - -### Terminology - -- Symbols - There are two types of symbols, "constant" and “non-constant”. - - Constant symbols are alphanumeric values used in expressions for - comparison. The Kconfig language specification says that these must be - surrounded by single or double quotes. - - Non-constant symbols are the 'config' values that are output into the - saved .config, auto.conf and config.h files. Non-constant symbols are - typically defined with the 'config' keyword, although they can also be - defined with the 'choice' keyword. These symbols may be used in a file's - expressions before they are defined. Valid characters for non-constant - symbols are any combination of alphanumeric characters, underscore. - Although “1234” is accepted as a symbol name, as is “o_o”, convention is - to use all uppercase words that are descriptive of the symbol's use so - they make sense when turned into CONFIG_NAME #defines. - -- Expressions - An expression is a logical evaluation. It can be as simple as - a static 'y' or 'n', or can be a symbol. Alternatively, expressions can be - complex evaluations of multiple symbols using the various logical operators. - The Kconfig language allows these logical evaluations in several places. The - most common use for complex expressions is following 'if' or ‘depends on’ - keywords, but they can also be used to set the value for a prompt or default - values. - -- Types - Each Kconfig symbol is one of the following types: bool, hex, int, - string, or tristate. The tristate type is not used for coreboot, leaving just - four types. As noted in the keyword summaries, a symbol must have a consistent - type anywhere it is defined. Also, Kconfig will simply not display a symbol - that has no type defined. A warning will be displayed in the terminal where - menuconfig was run if this happens: - _src/Kconfig:25:warning: config symbol defined without type_. - -- Prompts - Input prompts are the text associated with the symbols which shown - to the user. The Kconfig language definition does not require surrounding the - prompt’s text with quotes, however it is recommended that quotes be used for - maximum compatibility. - -- Menu Entries - These keyword blocks create the symbols and questions that are - visible in the front end. - - -## Keywords - -### bool - -The 'bool' keyword assigns a boolean type to a symbol. The allowable values for -a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt -string which makes the symbol editable in one of the configuration front ends. - - -##### Usage: -bool \[prompt\] \[if <expr>\] - - -##### Example: - config ANY_TOOLCHAIN - bool "Allow building with any toolchain" - default n - depends on COMPILER_GCC - - -##### Notes: -- Putting the prompt after the 'bool' keyword is the same as using a 'prompt' - keyword later. See the 'prompt' keyword for more notes. -- Only the first type definition for each symbol is valid. Further matching - definitions are fine, although unnecessary. Conflicting type definitions will - be ignored, and a warning will be presented on the console where the - configuration front end was run: - _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. -- Boolean symbols do not need a default and will default to ‘n’. - - -##### Restrictions: - -- This keyword must be within a symbol definition block, started by the - 'config' keyword. - --------------------------------------------------------------------------------- - -### choice - -This creates a selection list of one or more boolean symbols. For bools, only -one of the symbols can be selected, and one will be be forced to be selected, -either by a ‘default’ statement, or by selecting the first config option if -there is no default value listed. - -##### Usage: -choice \[symbol\] -- \[prompt\] -- \[default\] - - -##### Example: - choice TESTCHOICE - prompt "Test choice" - default TESTCHOICE2 if TESTCHOICE_DEFAULT_2 - default TESTCHOICE3 - - config TESTCHOICE1 - bool "Choice 1" - config TESTCHOICE2 - bool "Choice 2" - config TESTCHOICE3 - bool "Choice 3" - config TESTCHOICE4 - bool "Choice 4" if TESTCHOICE_SHOW_4 - endchoice - - config TESTCHOICE_DEFAULT_2 - def_bool y - - config TESTCHOICE_SHOW_4 - def_bool n - - config TESTSTRING - string - default “String #1” if TESTCHOICE1 - default “String #2” if TESTCHOICE2 - default “String #4” if TESTCHOICE3 - default “String #4” if TESTCHOICE4 - default “” - - -##### Notes: -- If no symbol is associated with a choice, then you can not have multiple - definitions of that choice. If a symbol is associated to the choice, then - you may define the same choice (ie. with the same entries) in another place. - Any selection in either location will update both choice menu selections. In - coreboot, the value of the symbol is always 1. -- As shown in the example above, the choice between bools can be used to set - the default for a non-bool type. This works best when the non-bool type - does not have an input prompt. - - -##### Restrictions: -- Symbols used for 'choice' entries must have input prompts defined using the - 'prompt' keyword. -- Symbols used in 'choice' entries may not be enabled with a 'select' - statement, they can be defaulted using a second Kconfig symbol however. - --------------------------------------------------------------------------------- - -### comment - -This keyword defines a line of text that is displayed to the user in the -configuration frontend and is additionally written to the output files. - - -##### Usage: -comment <prompt> -- \[depends on\] - - -##### Example: - - if CONSOLE_SERIAL - comment "I/O mapped, 8250-compatible" - depends on DRIVERS_UART_8250IO - endif - - -##### Notes: -- Comments are only valid outside of config blocks, but can be within menu and - if blocks. - --------------------------------------------------------------------------------- - -### config - -This is the keyword that starts a block defining a Kconfig symbol. The symbol -modifiers follow the 'config' statement. - -##### Usage: -config <symbol> - -- \[bool | def_bool | int | hex | string\] -- \[depends on\] -- \[prompt\] -- \[help\] -- \[range\] -- \[select\] - - -##### Example: - config SEABIOS_PS2_TIMEOUT - prompt "PS/2 keyboard timeout" if PAYLOAD_SEABIOS - default 0 - depends on PAYLOAD_SEABIOS - int - help - Some PS/2 keyboard controllers don't respond to commands - immediately after powering on. This specifies how long - SeaBIOS will wait for the keyboard controller to become - ready before giving up. - - -##### Notes: -- Non-coreboot projects also use the 'tristate' and 'def_tristate' types. -- Ends at the next Kconfig keyword that is not valid inside the config block: - - menu | endmenu | if | endif | choice | config | source | comment - --------------------------------------------------------------------------------- - -### default - -The ‘default’ keyword assigns a value to a symbol in the case where no preset -value exists, i.e. the symbol is not present and assigned in .config. If there -is no preset value, and no ‘default’ keyword, the user will be asked to enter a -valid value when building coreboot. - - -##### Usage: -default <expr> \[if <expr>\] - - -##### Example: - config GENERATE_MP_TABLE - prompt "Generate an MP table" if HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC - bool - default HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC - help - Generate an MP table (conforming to the Intel - MultiProcessor specification 1.4) for this board. - - -##### Notes: -- Kconfig defaults for symbols without a prompt *NEVER* affect existing legal - symbol definitions in a .config file. The default only affects the symbol if - there is no valid definition in a config file. This is a frequent source of - confusion. It’s covered again in the Tips section below. -- The first valid 'default' entry for a symbol is always used. Any further - 'default' statements for a symbol are ignored. This means that the order of - Kconfig files is very important as the earlier files get to set the defaults - first. They should be sourced in the order from most specific (mainboard - Kconfig files) to the most generic (architecture-specific Kconfig files). -- If there is no 'default' entry for a symbol, it gets set to 'n', 0, 0x0, or - “” depending on the type, however the 'bool' type is the only type that - should be left without a default value. - --------------------------------------------------------------------------------- - -### def_bool - -‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to -boolean. It lets you set the type and default value at the same time, instead -of setting the type and the prompt at the same time. It's typically used for -symbols that don't have prompts. - - -##### Usage: -def_bool <expr> \[if <expr>\] - - -##### Example: - config EC_GOOGLE_CHROMEEC_LPC - depends on EC_GOOGLE_CHROMEEC && ARCH_X86 - def_bool y - select SERIRQ_CONTINUOUS_MODE - help - Google Chrome EC via LPC bus. - - -##### Notes: -- Only the first type definition for each symbol is valid. Further matching - definitions are fine, although unnecessary. Conflicting type definitions will - be ignored, and a warning will be presented on the console where the - configuration front end was run: - _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. - -##### Restrictions: -- This keyword must be within a symbol definition block, started by the - 'config' keyword. - --------------------------------------------------------------------------------- - -### depends on - -This defines a dependency for a menu entry, including symbols and comments. It -behaves the same as surrounding the menu entry with an if/endif block. If the -‘depends on’ expression evaluates to false, the 'prompt' value will not be -printed, and defaults will not be set based on this block. - - -##### Usage: -depends on <expr> - - -##### Example: - config COMMON_CBFS_SPI_WRAPPER - bool - default n - depends on SPI_FLASH - depends on !ARCH_X86 - help - Use common wrapper to interface CBFS to SPI bootrom. - - -##### Notes: -- Symbols that have multiple ‘depends on’ sections as above are equivalent to a - single ‘depends on’ statement with sections joined by &&. So the above is - the same as “depends on SPI_FLASH && ! ARCH_X86”. - --------------------------------------------------------------------------------- - -### endchoice - -This ends a choice block. See the 'choice' keyword for more information and an -example. - --------------------------------------------------------------------------------- - -### endif - -This ends a block started by the 'if' keyword. See the 'if' keyword for more -information and an example. - --------------------------------------------------------------------------------- - -### endmenu - -This ends a menu block. See the 'menu' keyword for more information and an -example. - --------------------------------------------------------------------------------- - -### help - -The 'help' keyword defines the subsequent block of text as help for a config or -choice block. The help block is started by the 'help' keyword on a line by -itself, and the indentation level of the next line controls the end of the help -block. The help ends on the next non-blank line that has an indentation level -less than the indentation level of the first line following the 'help' keyword. - -##### Usage: -help <help text> - - -##### Example: - config COMPILER_GCC - bool "GCC" - help - Use the GNU Compiler Collection (GCC) to build coreboot. For details - see http://gcc.gnu.org. - - -##### Notes: -- Identical to the '---help---' keyword which isn’t used in coreboot. -- Other keywords are allowed inside the help block, and are not recognized as - keywords so long as the indentation rules are followed, even if they start a - line. - - -##### Restrictions: -- Only used for 'config' and 'choice' keywords. - --------------------------------------------------------------------------------- - -### hex - -This is another symbol type specifier, specifying an unsigned integer value -formatted as hexadecimal. - -##### Usage: -hex <expr> \[if <expr>\] - - -##### Example: - config INTEL_PCH_UART_CONSOLE_NUMBER - hex "Serial IO UART number to use for console" - default 0x0 - depends on INTEL_PCH_UART_CONSOLE - - -##### Notes: -- Kconfig doesn’t complain if you don’t start the default value for a hex - symbol with ‘0x’, but not doing so will lead to issues. It will update 10 - to 0x10 without warning the user. -- Putting the prompt text after the 'hex' keyword is the same as using a - 'prompt' keyword later. See the 'prompt' keyword for more notes. -- Only the first type definition for each symbol is valid. Further matching - definitions are fine, although unnecessary. Conflicting type definitions will - be ignored, and a warning will be presented on the console where the - configuration front end was run: - _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. - - -##### Restrictions: -- This keyword must be within a symbol definition block, started by the - 'config' keyword. -- 'hex' type symbols must have a 'default' entry set. - --------------------------------------------------------------------------------- - -### if - -The 'if' keyword is overloaded, used in two different ways. The first definition -enables and disables various other keywords, and follows the other keyword -definition. This usage is shown in each of the other keywords' usage listings. - -The second usage of the 'if' keyword is part of an if/endif block. Most items -within an if/endif block are not evaluated, while others, such as the 'source' -keyword, ignore the existence of the if/endif block completely. Symbols defined -within an if/endif block are still created, although their default values are -ignored - all values are set to 'n'. - - -##### Usage: -if <expr> - -- \[config\] -- \[choice\] -- \[comment\] -- \[menu\] - -endif - - -##### Example: - if ARCH_X86 - - config SMP - bool - default y if MAX_CPUS != 1 - default n - help - This option is used to enable certain functions to make - coreboot work correctly on symmetric multi processor (SMP) systems. - endif - -##### Restrictions: -- Corresponding ‘if’ and ‘endif’ statements must exist in the same file. - --------------------------------------------------------------------------------- - -### int - -A type setting keyword, defines a symbol as an integer, accepting only signed -numeric values. The values can be further restricted with the ‘range’ keyword. - - -##### Usage: -int <expr> \[if <expr>\] - - -##### Example: - config PRE_GRAPHICS_DELAY - int "Graphics initialization delay in ms" - default 0 - help - On some systems, coreboot boots so fast that connected - monitors (mostly TVs) won't be able to wake up fast enough - to talk to the VBIOS. On those systems we need to wait for a - bit before executing the VBIOS. - - -##### Notes: -- Only the first type definition for each symbol is valid. Further matching - definitions are fine, although unnecessary. Conflicting type definitions will - be ignored, and a warning will be presented on the console where the - configuration front end was run: - _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. - - -##### Restrictions: -- This keyword must be within a symbol definition block, started by the 'config' - keyword. -- 'int' type symbols must have a default value set. - --------------------------------------------------------------------------------- - -### mainmenu - -The 'mainmenu' keyword sets the title or title bar of the configuration front - end, depending on how the configuration program decides to use it. It can only - be specified once and at the very beginning of the top level Kconfig file, - before any other statements. - - -##### Usage: -mainmenu <prompt> - -##### Example: -mainmenu "coreboot configuration" - -##### Restrictions: -- Must be the first statement in the top level Kconfig. -- Must only be used once in the entire Kconfig tree. - --------------------------------------------------------------------------------- - -### menu - -The 'menu' and 'endmenu' keywords tell the configuration front end that the -enclosed statements are part of a group of related pieces. - - -##### Usage: -menu <prompt> - -- \[choice\] -- \[config\] -- \[menu\] -- \[if/endif\] - -endmenu - - -##### Example: - menu "On-Chip Device Power Down Control" - config TEMP_POWERDOWN - bool "Temperature sensor power-down" - - config SATA_POWERDOWN - bool "SATA power-down" - - config ADC_POWERDOWN - bool "ADC power-down" - - config PCIE0_POWERDOWN - bool "PCIE0 power-down" - - config MAC_POWERDOWN - bool "MAC power-down" - - config USB1_POWERDOWN - bool "USB2.0 Host Controller 1 power-down" - - config IDE_POWERDOWN - bool "IDE power-down" - - endmenu - -##### Restrictions: -- Must be closed by a corresponding ‘endmenu’ keyword in the same file. - --------------------------------------------------------------------------------- - -### prompt - -The 'prompt' keyword sets the text displayed for a config symbol or choice in -configuration front end. - - -##### Usage: -prompt <prompt> \[if <expr>\] - - -##### Example: - config REALMODE_DEBUG - prompt "Enable debug messages for option ROM execution" - bool - default n - depends on PCI_OPTION_ROM_RUN_REALMODE - depends on DEFAULT_CONSOLE_LOGLEVEL_7 || DEFAULT_CONSOLE_LOGLEVEL_8 - help - This option enables additional x86emu related debug - messages. Note: This option will increase the time to emulate a ROM. - - If unsure, say N. - - -##### Notes: -- The same rules apply for menu entries defined by the 'prompt' keyword and - other prompt types such as those defined by the 'int' or 'string' keywords. -- Redefining the prompt text in multiple instances of config symbols is allowed. - Only the current prompt statement for a particular entry will be displayed by - the front end in any given location. This means that multiple mainboards can - set different prompt values for a symbol, and it would appear differently in - each mainboard’s menu. The symbol can even have multiple entries in the same - menu with different prompts if desired. For example, both of these would get - printed, and changing either entry would change the other. - - config PROMPT_TEST - string "Prompt value 1" - - config PROMPT_TEST - prompt "Prompt value 2" - -- Although not required, it's recommended that you use quotes around prompt - statements. -* If the prompt is redefined inside the SAME config entry, you will get a - warning: - _warning: prompt redefined_. - For example, this is not allowed: - - config PROMPT_TEST - string "Prompt value 1" - prompt "Prompt value 2" --------------------------------------------------------------------------------- - -### range - -This sets the allowable minimum and maximum entries for hex or int type config -symbols. - - -##### Usage: -range <symbol> <symbol> \[if <expr>\] - - -##### Example: - config TEST1 - hex "test 1" - range 0x0 0x10 - - -##### Notes: -- Only the first definition of a range is used for any symbol. Further - definitions will be ignored without warning. - --------------------------------------------------------------------------------- - -### select - -The ‘select’ keyword is used within a bool type config block. In coreboot (and -other projects that don't use modules), the 'select' keyword can force an -unassociated bool type symbol to 'y'. When the symbol for the config block is -‘y’, the ‘select’ action is taken. Otherwise the bool is unaffected. - - -##### Usage: -select <symbol> \[if <expr>\] - - -##### Example: - config TPM - bool - default n - select LPC_TPM if ARCH_X86 - select I2C_TPM if ARCH_ARM - select I2C_TPM if ARCH_ARM64 - help - Enable this option to enable TPM support in coreboot. - If unsure, say N. - -##### Notes: -- Using the 'select' keyword can create logical contradictions in Kconfig, which - will create warnings and fail to save the .config. Following is an example of - an obviously invalid configuration, where selecting BOOLTEST violates the - ‘depends on’ of BOOLTEST2: - - config BOOLTEST - bool "bool Test" - select BOOLTEST2 - - config BOOLTEST2 - bool "Bool Test 2" - depends on !BOOLTEST - -##### Restrictions: -- The ‘select’ keyword only works on bool type symbols. -- Symbols created inside of choice blocks cannot be selected, and should be - enabled by using default values instead. - --------------------------------------------------------------------------------- - -### source - -The 'source' keyword functions much the same as an 'include' statement in c. -This pulls one or more files into Kconfig at the location of the 'source' -command. This statement is always parsed - there is no way to conditionally -source a file. coreboot has modified the source statement slightly to handle -directory globbing. The '*' character will match with any directory. - - -##### Usage: -source <prompt> - - -##### Example: - - choice - prompt "Mainboard vendor" - default VENDOR_EMULATION - - source "src/mainboard/*/Kconfig.name" - - endchoice - - source "src/mainboard/*/Kconfig" - - -##### Notes: -- As with all prompt values, the 'source' prompt may be enclosed in single or - double quotes, or left without any quotes. Using quotes is highly recommended - however. -- The 'source' keyword loads files relative to the working directory where the - Kconfig command was run. For coreboot, this is the root coreboot directory, so - all source commands in the src directory need to start with ‘src/’. -- In coreboot's Kconfig, if a sourced file does not exist, the statement is - simply ignored. This is different than other versions of Kconfig. -- 'source' pulls a file into the Kconfig tree at the location of the keyword. - This allows for files containing small bits of the Kconfig tree to be pulled - into a larger construct. A restriction on this is that the starting/ending - keyword pairs must be within the same file - ‘endif’ cannot appear in a - different file than the ‘if’ statement that it ends. The same is true of - menu/endmenu and choice/endchoice pairs. - -The coreboot Kconfig structure uses this along with globbing to build up the -mainboard directory. Each mainboard’s Kconfig.name file contains just two -statements that generate a list of all the platform names: - - config BOARD_AMD_NORWICH - bool "Norwich" - - -##### Restrictions: -- 'source' keywords always load in the specified file or files. There is no way - to optionally pull in a file. Putting an if/endif block around a source - command does not affect the source command, although it does affect the - content. To avoid confusion, use if/endif blocks inside sourced files to - remove their content if necessary. - --------------------------------------------------------------------------------- - -### string - -The last of the symbol type assignment keywords. 'string' allows a text value to -be entered. - - -##### Usage: -string <expr> \[if <expr>\] - - -##### Example: - config BOOTBLOCK_SOUTHBRIDGE_INIT - string - default "southbridge/amd/pi/hudson/bootblock.c" - - config HUDSON_GEC_FWM_FILE - string "GEC firmware path and filename" - depends on HUDSON_GEC_FWM - - -##### Notes: -- Putting the prompt after the 'string' keyword is the same as using a 'prompt' -keyword later. See the prompt keyword for more notes. -- Only the first type definition for each symbol is valid. Further matching - definitions are fine, although unnecessary. Conflicting type definitions will - be ignored, and a warning will be presented on the console where the - configuration front end was run: - _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'string'_. -- Some characters may not get interpreted correctly when inside a string entry - depending on how they are used - inside a C file, inside a Makefile, passed - through a Makefile to a C file, or something else. It may be necessary to - escape the characters at times. Because this is very dependent upon how the - symbol is actually used, a definitive guide cannot be given here. -- 'string' type variables do NOT need a default, and will default to the - value “”. - - -##### Restrictions: -- This keyword must be within a symbol definition block, started by the 'config' - keyword. - --------------------------------------------------------------------------------- - - - - -## Keywords not used in coreboot at the time of writing: - -- allnoconfig_y: -- defconfig_list -- def_tristate -- env -- ---help--- -- menuconfig -- modules -- optional -- option -- tristate -- visible if - - -## Build files generated by Kconfig - -### build/config.h - -The config.h file is a very basic header file made up of a list of #define -statements: - - #define SYMBOL NAME XXX - - -##### Symbol types: -- bool, int, and hex types - Every symbol of one of these types created in the - Kconfig tree is defined. It doesn’t matter whether they’re in an if/endif - block, or have a ‘depends on’ statement - they ALL end up being defined in - this file. -- String - Only string types that actually have a value associated with them - are defined. - -The config.h file uses 0 and 1 to represent Kconfig's 'n' and 'y' values -respectively. String values are placed inside double quotes. - -The name of the file is controlled by the $KCONFIG_AUTOHEADER environment -variable, which is set to $(obj)/config.h by the coreboot makefiles. - -The prefix used for the symbols is controlled by the $CONFIG_ environment -variable. This is not set in coreboot, which uses the default CONFIG_ prefix -for all of its symbols. - -The coreboot makefile forces the config.h file to be included into all coreboot -C files. This is done in Makefile.inc on the compiler command line using the -“-include $(obj)/config.h” command line option. - -Example of various symbol types in the config.h file: - - #define CONFIG_BOOTBLOCK_SOURCE "bootblock_simple.c" # String - #define CONFIG_CBFS_SIZE 0x00300000 # Hex - #define CONFIG_TTYS0_BAUD 115200 # Int - #define CONFIG_HAVE_ACPI_TABLES 1 # Bool enabled - #define CONFIG_EXPERT 0 # Bool disabled - #define CONFIG_NORTHBRIDGE_INTEL_I440LX 0 # Bool excluded - - -### .config - -The .config file in the root directory is used as the input file, but also by -the makefiles to set variable values. The main difference is that it does not -contain all of the symbols. It excludes symbols defined in an if/endif block -whose expression evaluated as false. Note that the symbol -CONFIG_NORTHBRIDGE_INTEL_I440LX shown in the config.h example above is not -present in the .config file. - -In addition, the .config file below contains the 'comment' prompt text from the -Kconfig, separating the blocks. - - ## General setup ## - CONFIG_BOOTBLOCK_SOURCE="bootblock_simple.c" # String - CONFIG_CBFS_SIZE=0x00300000 # Hex - CONFIG_TTYS0_BAUD=115200 # Int - CONFIG_HAVE_ACPI_TABLES=y # Bool enabled - # CONFIG_EXPERT is not set # Bool disabled - -This file is included directly by the makefile, and sets the CONFIG symbols so -that they are available during the build process. - - -### build/auto.conf - -Although the controlling variable for the auto.conf filename, -KCONFIG_AUTOCONFIG, is set in the coreboot makefiles, the auto.conf file itself -is not used by coreboot. This file has the same syntax and structure as the -.config file, but contains all symbols in the Kconfig tree, including those that -are not enabled, or are excluded by if/endif blocks, or the 'depends on' -keyword. The kconfig tool could be updated to not generate this file, but since -it's not hurting anything, it's still being generated. - - - -## Defconfig or Miniconfig files - -Miniconfig files are the standard .config files with all of the symbols which -are set to their default values stripped out. These files are very useful for -debugging your config, as well as being the best way to store your .config file. -If you store your config as a full config file, it will be much harder to -maintain. Any Kconfig symbols with updated default values will retain their old -values, and any symbols which have been removed will still remain in the file. -Storing full config files just generally leads to a lot more maintenance than -storing miniconfig files. - -The easiest way to generate the miniconfig file is by running - - make savedefconfig DOTCONFIG=.config DEFCONFIG=[output file] - -DEFCONFIG defaults to ‘defconfig’, DOTCONFIG defaults to ‘.config’. - - -To turn the miniconfig back into a full config file, use one of the two targets: - - make olddefconfig DOTCONFIG=[input/output file] - -or - - make defconfig KBUILD_DEFCONFIG=[input file] DOTCONFIG=[output file] - -In both of these cases, DOTCONFIG defaults to .config. - - - -## Editing and updating saved .config files - - -### Don’t save full config files - -Save miniconfig files, as mentioned in the previous section. - - -### Disable values with ‘# CONFIG_SYMBOL is not set’ - -A common mistake when trying to disable a value is to edit the .config file and -change it from ‘CONFIG_SYMBOL=y’ to ‘CONFIG_SYMBOL=n’, but this doesn’t -correctly disable the symbol. If the default value for the symbol is ‘n’ to -begin with, this isn’t an issue - the symbol just gets ignored, and the default -value is used. The problem is where the default for the symbol is ‘y’. When -the bad entry in the .config file gets ignored, the value is set back to ‘y’, -leading to much frustration. - -Always disable the Kconfig symbols in the .config file with the syntax: - - # CONFIG_SYMBOL is not set - -### Only the LAST instance of a symbol is used - -When reading a saved .config file, Kconfig uses the LAST instance of a symbol -that it comes across, and ignores any previous instances. This can be used to -override symbols in a saved .config file by appending the new value to a config -file. - -For example: - -A .config file that contains these two lines: - - # CONFIG_BOOLTEST is not set - CONFIG_BOOLTEST=y - -After running ‘make olddefconfig’, ends up with the value: - - CONFIG_BOOLTEST=y - -A case where this can be used is by a making a script to create two versions of -a coreboot rom for a single platform. The first ROM could be built with serial -console disabled, and the second ROM, built as a debug version, could have -serial console enabled by overriding the "CONFIG_CONSOLE_SERIAL" symbol, and -setting it to enabled. - -## General Kconfig Tips and Notes - -### Default values for config options - -The FIRST valid default that the Kconfig parser comes across will be used for -each symbol. This means that the organization of the tree is very important. -The structure should go from most specific at the top of the Kconfig tree to the -most general later in the tree. In coreboot, the mainboard directories get -loaded first, as they are sourced very early in the src/Kconfig file. Chipset -Kconfig files get sourced later, and the architecture specific Kconfig files get -sourced even later. This allows the mainboards to set their defaults early, -overriding the default values set in chipset or architecture. - -Due to this mechanism, a default defined early cannot be changed by a default -set in a later Kconfig file. There are ways around this, involving 'depends on' -statements, but they add additional variables which are generally just used -internal to Kconfig. - - -### Select statement usage - -The 'select' keyword forces the value of a symbol with a bool type to 'y'. It -overrides any dependencies of the symbol, so using it carelessly can lead to -unpredictable results. - - - -### All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code - -All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code if they -are in a sourced Kconfig - do NOT use #ifdef CONFIG_SYMBOL - -String symbols are the exception. All others (int, hex, etc.) are always -defined in config.h. Never use an #ifdef statement for a Kconfig symbol other -than strings in C to determine whether the symbol is enabled or disabled. So -long as the symbol is in ANY sourced Kconfig file, it will be defined. Even if -the symbol is only inside of an if/endif block where the if expression evaluates -as false, the symbol STILL gets defined in the config.h file (though not in the -.config file). - -Use \#if IS_ENABLED(CONFIG_*) to be sure (it returns false for undefined symbols -and defined-to-0 symbols alike). - - - -### Symbols with prompts use defaults *ONLY* when initially created or enabled. - -Symbols with a prompt which may be user-modified are NOT updated to default -values when changing between platforms or modifying other symbols. There are -only two times the default values are used: -1. When a config is initially created. -2. When a dependency which had previously kept the symbol from being active - changes to allowing it to be active. - -Because of this, starting with a saved .config for one platform and updating it -for another platform can lead to very different results than creating a platform -from scratch. - - - -### Symbols with no prompt will be the default value (unless 'select' is used). - -Symbols that do not have a prompt will always use the first valid default value -specified in Kconfig. They cannot be updated, even if they are modified in a -saved .config file. As always, a 'select' statement overrides any specified -'default' or 'depends on' statement. - - -## Differences between coreboot's Kconfig and other Kconfig implementations. - -- coreboot has added the glob operator '*' for the 'source' keyword. -- coreboot’s Kconfig always defines variables except for strings. In other - Kconfig implementations, bools set to false/0/no are not defined. -- IS_ENABLED() is ‘false’ for undefined variables and ‘0’ variables. In Linux - (where the macro comes from) it’s ‘true’ as soon as the variable is defined. -- coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to - error out if there are any issues in the Kconfig files. In the Linux kernel, - Kconfig will generate a warning, but will still output an updated .config or - config.h file. - - -## Kconfig Editor Highlighting - -#### vim: - -vim has syntax highlighting for Kconfig built in (or at least as a part of -vim-common), but most editors do not. - - -#### ultraedit: - -https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew - - - -#### atom: - -https://github.com/martinlroth/language-kconfig - - -## Syntax Checking: - -The Kconfig utility does some basic syntax checking on the Kconfig tree. -Running "make silentoldconfig" will show any errors that the Kconfig utility -sees. - -### util/kconfig_lint - -Because the Kconfig utility is relatively forgiving, and ignores issues that a -developer might be interested in, kconfig_lint, another Kconfig checker has been -written. - -The file kconfig_lint and its associated readme can be found in the coreboot -utils/lint directory. It is useful for parsing the Kconfig tree, and for -showing warnings, errors, and notes about coreboot’s Kconfig files. - - - kconfig_lint - -o|--output=file Set output filename - -p|--print Print full output - -e|--errors_off Don't print warnings or errors - -w|--warnings_off Don't print warnings - -n|--notes Show minor notes - --path=dir Path to top level kconfig - -c|--config=file Filename of config file to load - -G|--no_git_grep Use standard grep tools instead of git grep - - -The -p option is very useful for debugging Kconfig issues, because it reads all -of the Kconfig files in the order that the Kconfig tools would read them, and -prints it out, along with where each line came from and which menu it appears -in. - -## License: -This work is licensed under the Creative Commons Attribution 4.0 International -License. To view a copy of this license, visit -https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative -Commons, PO Box 1866, Mountain View, CA 94042, USA. - -Code examples snippets are licensed under GPLv2, and are used here under fair -use laws. diff --git a/Documentation/gerrit_guidelines.md b/Documentation/gerrit_guidelines.md deleted file mode 100644 index cf7d5e8c5a..0000000000 --- a/Documentation/gerrit_guidelines.md +++ /dev/null @@ -1,277 +0,0 @@ -coreboot Gerrit Etiquette and Guidelines -======================================== - -The following rules are the requirements for behavior in the coreboot -codebase in gerrit. These have mainly been unwritten rules up to this -point, and should be familiar to most users who have been active in -coreboot for a period of time. Following these rules will help reduce -friction in the community. - -Note that as with many rules, there are exceptions. Some have been noted -in the 'More Detail' section. If you feel there is an exception not listed -here, please discuss it in the mailing list to get this document updated. -Don't just assume that it's okay, even if someone on IRC says it is. - - -Summary: --------- -These are the expectations for committing, reviewing, and submitting code -into coreboot git and gerrit. While breaking individual rules may not have -immediate consequences, the coreboot leadership may act on repeated or -flagrant violations with or without notice. - -* Don't violate the licenses. -* Let non-trivial patches sit in a review state for at least 24 hours -before submission. -* Try to coordinate with platform maintainers when making changes to -platforms. -* If you give a patch a -2, you are responsible for giving concrete -recommendations for what could be changed to resolve the issue the patch -addresses. -* Don't modify other people's patches without their consent. -* Be respectful to others when commenting. -* Don’t submit patches that you know will break other platforms. - - -More detail: ------------- -* Don't violate the licenses. If you're submitting code that you didn't -write yourself, make sure the license is compatible with the license of the -project you're submitting the changes to. If you’re submitting code that -you wrote that might be owned by your employer, make sure that your -employer is aware and you are authorized to submit the code. For -clarification, see the Developer's Certificate of Origin in the coreboot -[Signed-off-by policy](https://www.coreboot.org/Development_Guidelines#Sign-off_Procedure). - -* Let non-trivial patches sit in a review state for at least 24 hours -before submission. Remember that there are coreboot developers in timezones -all over the world, and everyone should have a chance to contribute. -Trivial patches would be things like whitespace changes or spelling fixes. -In general, small changes that don’t impact the final binary output. The -24-hour period would start at submission, and would be restarted at any -update which significantly changes any part of the patch. Patches can be -'Fast-tracked' and submitted in under this 24 hour with the agreement of at -least 3 +2 votes. - -* Do not +2 patches that you authored or own, even for something as trivial -as whitespace fixes. When working on your own patches, it’s easy to -overlook something like accidentally updating file permissions or git -submodule commit IDs. Let someone else review the patch. An exception to -this would be if two people worked in the patch together. If both +2 the -patch, that is acceptable, as each is giving a +2 to the other's work. - -* Try to coordinate with platform maintainers and other significant -contributors to the code when making changes to platforms. The platform -maintainers are the users who initially pushed the code for that platform, -as well as users who have made significant changes to a platform. To find -out who maintains a piece of code, please use util/scripts/maintainers.go -or refer to the original author of the code in git log. - -* If you give a patch a -2, you are responsible for giving concrete -recommendations for what could be changed to resolve the issue the patch -addresses. If you feel strongly that a patch should NEVER be merged, you -are responsible for defending your position and listening to other points -of view. Giving a -2 and walking away is not acceptable, and may cause your - -2 to be removed by the coreboot leadership after no less than a week. A - notification that the -2 will be removed unless there is a response will - be sent out at least 2 days before it is removed. - -* Don't modify other people's patches unless you have coordinated this with -the owner of that patch. Not only is this considered rude, but your changes -could be unintentionally lost. An exception to this would be for patches -that have not been updated for more than 90 days. In that case, the patch -can be taken over if the original author does not respond to requests for -updates. Alternatively, a new patch can be pushed with the original -content, and both patches should be updated to reference the other. - -* Be respectful to others when commenting on patches. Comments should -be kept to the code, and should be kept in a polite tone. We are a -worldwide community and English is a difficult language. Assume your -colleagues are intelligent and do not intend disrespect. Resist the urge to -retaliate against perceived verbal misconduct, such behavior is not -conducive to getting patches merged. - -* Don’t submit code that you know will break other platforms. If your patch -affects code that is used by other platforms, it should be compatible with -those platforms. While it would be nice to update any other platforms, you -must at least provide a path that will allow other platforms to continue -working. - - -Recommendations for gerrit activity: ------------------------------------- -These guidelines are less strict than the ones listed above. These are more -of the “good idea” variety. You are requested to follow the below -guidelines, but there will probably be no actual consequences if they’re -not followed. That said, following the recommendations below will speed up -review of your patches, and make the members of the community do less work. - -* Each patch should be kept to one logical change, which should be -described in the title of the patch. Unrelated changes should be split out -into separate patches. Fixing whitespace on a line you’re editing is -reasonable. Fixing whitespace around the code you’re working on should be a -separate ‘cleanup’ patch. Larger patches that touch several areas are fine, -so long as they are one logical change. Adding new chips and doing code -cleanup over wide areas are two examples of this. - -* Test your patches before submitting them to gerrit. It's also appreciated -if you add a line to the commit message describing how the patch was -tested. This prevents people from having to ask whether and how the patch -was tested. Examples of this sort of comment would be ‘TEST=Built -platform’ or ‘Tested by building and booting platform’. Stating that the -patch was not tested is also fine, although you might be asked to do some -testing in cases where that would be reasonable. - -* Take advantage of the lint tools to make sure your patches don’t contain -trivial mistakes. By running ‘make gitconfig’, the lint-stable tools are -automatically put in place and will test your patches before they are -committed. As a violation of these tools will cause the jenkins build test -to fail, it’s to your advantage to test this before pushing to gerrit. - -* Don't submit patch trains longer than around 20 patches unless you -understand how to manage long patch trains. Long patch trains can become -difficult to handle and tie up the build servers for long periods of time -if not managed well. Rebasing a patch train over and over as you fix -earlier patches in the train can hide comments, and make people review the -code multiple times to see if anything has changed between revisions. When -pushing long patch trains, it is recommended to only push the full patch -train once - the initial time, and only to rebase three or four patches at -a time. - -* Run 'make what-jenkins-does' locally on patch trains before submitting. -This helps verify that the patch train won’t tie up the jenkins builders -for no reason if there are failing patches in the train. For running -parallel builds, you can specify the number of cores to use by setting the -the CPUS environment variable. Example: - make what-jenkins-does CPUS=8 - -* Use a topic when pushing a train of patches. This groups the commits -together so people can easily see the connection at the top level of -gerrit. Topics can be set for individual patches in gerrit by going into -the patch and clicking on the icon next to the topic line. Topics can also -be set when you push the patches into gerrit. For example, to push a set of -commits with the the i915-kernel-x60 set, use the command: - git push origin HEAD:refs/for/master/i915-kernel-x60 - -* If one of your patches isn't ready to be merged, make sure it's obvious -that you don't feel it's ready for merge yet. The preferred way to show -this is by marking in the commit message that it’s not ready until X. The -commit message can be updated easily when it’s ready to be pushed. -Examples of this are "WIP: title" or "[NEEDS_TEST]: title". Another way to -mark the patch as not ready would be to give it a -1 or -2 review, but -isn't as obvious as the commit message. These patches can also be pushed as -drafts as shown in the next guideline. - -* When pushing patches that are not for submission, these should be marked -as such. This can be done in the title ‘[DONOTSUBMIT]’, or can be pushed as -draft commits, so that only explicitly added reviewers will see them. These -sorts of patches are frequently posted as ideas or RFCs for the community -to look at. To push a draft, use the command: - git push origin HEAD:refs/drafts/master - -* Respond to anyone who has taken the time to review your patches, even if -it's just to say that you disagree. While it may seem annoying to address a -request to fix spelling or 'trivial' issues, it’s generally easy to handle -in gerrit’s built-in editor. If you do use the built-in editor, remember to -get that change to your local copy before re-pushing. It's also acceptable -to add fixes for these sorts of comments to another patch, but it's -recommended that that patch be pushed to gerrit before the initial patch -gets submitted. - -* Consider breaking up large individual patches into smaller patches -grouped by areas. This makes the patches easier to review, but increases -the number of patches. The way you want to handle this is a personal -decision, as long as each patch is still one logical change. - -* If you have an interest in a particular area or mainboard, set yourself -up as a ‘maintainer’ of that area by adding yourself to the MAINTAINERS -file in the coreboot root directory. Eventually, this should automatically -add you as a reviewer when an area that you’re listed as a maintainer is -changed. - -* Submit mainboards that you’re working on to the board-status repo. This -helps others and shows that these mainboards are currently being -maintained. At some point, boards that are not up to date in the -board-status repo will probably end up getting removed from the coreboot -master branch. - -* Abandon patches that are no longer useful, or that you don’t intend to -keep working on to get submitted. - -* Bring attention to patches that you would like reviewed. Add reviewers, -ask for reviewers on IRC or even just rebase it against the current -codebase to bring it to the top of the gerrit list. If you’re not sure who -would be a good reviewer, look in the MAINTAINERS file or git history of -the files that you’ve changed, and add those people. - -* Familiarize yourself with the coreboot [commit message -guidelines](https://www.coreboot.org/Git#Commit_messages), before pushing -patches. This will help to keep annoying requests to fix your commit -message to a minimum. - -* If there have been comments or discussion on a patch, verify that the -comments have been addressed before giving a +2. If you feel that a comment -is invalid, please respond to that comment instead of just ignoring it. - -* Be conscientious when reviewing patches. As a reviewer who approves (+2) -a patch, you are responsible for the patch and the effect it has on the -codebase. In the event that the patch breaks things, you are expected to -be actively involved in the cleanup effort. This means you shouldn’t +2 a -patch just because you trust the author of a patch - Make sure you -understand what the implications of a patch might be, or leave the review -to others. Partial reviews, reviewing code style, for example, can be given -a +1 instead of a +2. This also applies if you think the patch looks good, -but may not have the experience to know if there may be unintended -consequences. - -* If there is still ongoing discussion to a patch, try to wait for a -conclusion to the discussion before submitting it to the tree. If you feel -that someone is just bikeshedding, maybe just state that and give a time -that the patch will be submitted if no new objections are raised. - -* When working with patch trains, for minor requests it’s acceptable to -create a fix addressing a comment in another patch at the end of the patch -train. This minimizes rebases of the patch train while still addressing the -request. For major problems where the change doesn’t work as intended or -breaks other platforms, the change really needs to go into the original -patch. - -* When bringing in a patch from another git repo, update the original -git/gerrit tags by prepending the lines with 'Original-'. Marking -the original text this way makes it much easier to tell what changes -happened in which repository. This applies to these lines, not the actual -commit message itself: - Commit-Id: - Change-Id: - Signed-off-by: - Reviewed-on: - Tested-by: - Reviewed-by: -The script 'util/gitconfig/rebase.sh' can be used to help automate this. -Other tags such as 'Commit-Queue' can simply be removed. - - -Expectations contributors should have: --------------------------------------- -* Don't expect that people will review your patch unless you ask them to. -Adding other people as reviewers is the easiest way. Asking for reviews for -individual patches in the IRC channel, or by sending a direct request to an -individual through your favorite messenger is usually the best way to get a -patch reviewed quickly. - -* Don't expect that your patch will be submitted immediately after getting -a +2. As stated previously, non-trivial patches should wait at least 24 -hours before being submitted. That said, if you feel that your patch or -series of patches has been sitting longer than needed, you can ask for it -to be submitted on IRC, or comment that it's ready for submission in the -patch. This will move it to the top of the list where it's more likely to -be noticed and acted upon. - -* Reviews are about the code. It's easy to take it personally when someone -is criticising your code, but the whole idea is to get better code into our -codebase. Again, this also applies in the other direction: review code, -criticize code, but don’t make it personal. - - -Requests for clarification and suggestions for updates to these guidelines -should be sent to the coreboot mailing list at . diff --git a/Documentation/getting_started/build_system.md b/Documentation/getting_started/build_system.md new file mode 100644 index 0000000000..787c833d2b --- /dev/null +++ b/Documentation/getting_started/build_system.md @@ -0,0 +1,86 @@ +# The coreboot build system +(this document is still incomplete and will be filled in over time) + +## General operation +The coreboot build system is based on GNU make but extends it significantly +to the point of providing its own custom language. +The overhead of learning this new syntax is (hopefully) offset by its lower +complexity. + +The build system is defined in the toplevel `Makefile` and `toolchain.inc` +and is supposed to be generic (and is in fact used with a number of other +projects). Project specific configuration should reside in files called +`Makefile.inc`. + +In general, the build system provides a number of "classes" that describe +various parts of the build. These cover the various build targets in coreboot +such as the stages, subdirectories with more source code, and the general +addition of files. + +Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used +by filling in a variable of that name followed by `-y` (eg. `romstage-y`, +`subdirs-y`, `cbfs-files-y`). +The `-y` suffix allows a simple interaction with our Kconfig build +configuration system: Kconfig options are available as variables starting +with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty. + +This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to +`class` depending on the choice for `FOO`. + +## classes +Classes can be defined as required. `subdirs` is handled internally since +it's parsed per subdirectory to add further directories to the rule set. + +TODO: explain how to create new classes and how to evaluate them. + +### subdirs +`subdirs` contains subdirectories (relative to the current directory) that +should also be handled by the build system. The build system expects these +directories to contain a file called `Makefile.inc`. + +Subdirectories are not read at the point where the `subdirs` statement +resides but later, after the current directory is handled (and potentially +others, too). + +### cbfs-files +This class is used to add files to the final CBFS image. Since several more +options need to be maintained than can comfortably fit in that single +variable, additional variables are used. + +`cbfs-files-y` contains the file name used in the CBFS image (called `foo` +here). Additional options are added in `foo-$(option)` variables. The +supported options are: + +* `file`: The on-disk file to add as `foo` (required) +* `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary` + (required) +* `compression`: Can be `none` or `lzma` (default: none) +* `position`: An absolute position constraint for the placement of the file + (default: none) +* `align`: Minimum alignment for the file (default: none) +* `options`: Additional cbfstool options (default: none) + +`position` and `align` are mutually exclusive. + +#### FMAP region support +With the addition of FMAP flash partitioning support to coreboot, there was a +need to extend the specification of files to provide more precise control +which regions should contain which files, and even change some flags based on +the region. + +Since FMAP policies depend on features using FMAP, that's kept separate from +the cbfs-files class. + +The `position` and `align` options for file `foo` can be overwritten for a +region `REGION` using `foo-REGION-position` and `foo-REGION-align`. + +The regions that each file should end in can be defined by overriding a +function called `regions-for-file` that's called as +`$(call regions-for-file,$(filename))` and should return a comma-separated +list of regions, such as `REGION1,REGION2,REGION3`. + +The default implementation just returns `COREBOOT` (the default region) for +all files. + +vboot provides its own implementation of `regions-for-file` that can be used +as reference in `src/vboot/Makefile.inc`. diff --git a/Documentation/getting_started/gerrit_guidelines.md b/Documentation/getting_started/gerrit_guidelines.md new file mode 100644 index 0000000000..cf7d5e8c5a --- /dev/null +++ b/Documentation/getting_started/gerrit_guidelines.md @@ -0,0 +1,277 @@ +coreboot Gerrit Etiquette and Guidelines +======================================== + +The following rules are the requirements for behavior in the coreboot +codebase in gerrit. These have mainly been unwritten rules up to this +point, and should be familiar to most users who have been active in +coreboot for a period of time. Following these rules will help reduce +friction in the community. + +Note that as with many rules, there are exceptions. Some have been noted +in the 'More Detail' section. If you feel there is an exception not listed +here, please discuss it in the mailing list to get this document updated. +Don't just assume that it's okay, even if someone on IRC says it is. + + +Summary: +-------- +These are the expectations for committing, reviewing, and submitting code +into coreboot git and gerrit. While breaking individual rules may not have +immediate consequences, the coreboot leadership may act on repeated or +flagrant violations with or without notice. + +* Don't violate the licenses. +* Let non-trivial patches sit in a review state for at least 24 hours +before submission. +* Try to coordinate with platform maintainers when making changes to +platforms. +* If you give a patch a -2, you are responsible for giving concrete +recommendations for what could be changed to resolve the issue the patch +addresses. +* Don't modify other people's patches without their consent. +* Be respectful to others when commenting. +* Don’t submit patches that you know will break other platforms. + + +More detail: +------------ +* Don't violate the licenses. If you're submitting code that you didn't +write yourself, make sure the license is compatible with the license of the +project you're submitting the changes to. If you’re submitting code that +you wrote that might be owned by your employer, make sure that your +employer is aware and you are authorized to submit the code. For +clarification, see the Developer's Certificate of Origin in the coreboot +[Signed-off-by policy](https://www.coreboot.org/Development_Guidelines#Sign-off_Procedure). + +* Let non-trivial patches sit in a review state for at least 24 hours +before submission. Remember that there are coreboot developers in timezones +all over the world, and everyone should have a chance to contribute. +Trivial patches would be things like whitespace changes or spelling fixes. +In general, small changes that don’t impact the final binary output. The +24-hour period would start at submission, and would be restarted at any +update which significantly changes any part of the patch. Patches can be +'Fast-tracked' and submitted in under this 24 hour with the agreement of at +least 3 +2 votes. + +* Do not +2 patches that you authored or own, even for something as trivial +as whitespace fixes. When working on your own patches, it’s easy to +overlook something like accidentally updating file permissions or git +submodule commit IDs. Let someone else review the patch. An exception to +this would be if two people worked in the patch together. If both +2 the +patch, that is acceptable, as each is giving a +2 to the other's work. + +* Try to coordinate with platform maintainers and other significant +contributors to the code when making changes to platforms. The platform +maintainers are the users who initially pushed the code for that platform, +as well as users who have made significant changes to a platform. To find +out who maintains a piece of code, please use util/scripts/maintainers.go +or refer to the original author of the code in git log. + +* If you give a patch a -2, you are responsible for giving concrete +recommendations for what could be changed to resolve the issue the patch +addresses. If you feel strongly that a patch should NEVER be merged, you +are responsible for defending your position and listening to other points +of view. Giving a -2 and walking away is not acceptable, and may cause your + -2 to be removed by the coreboot leadership after no less than a week. A + notification that the -2 will be removed unless there is a response will + be sent out at least 2 days before it is removed. + +* Don't modify other people's patches unless you have coordinated this with +the owner of that patch. Not only is this considered rude, but your changes +could be unintentionally lost. An exception to this would be for patches +that have not been updated for more than 90 days. In that case, the patch +can be taken over if the original author does not respond to requests for +updates. Alternatively, a new patch can be pushed with the original +content, and both patches should be updated to reference the other. + +* Be respectful to others when commenting on patches. Comments should +be kept to the code, and should be kept in a polite tone. We are a +worldwide community and English is a difficult language. Assume your +colleagues are intelligent and do not intend disrespect. Resist the urge to +retaliate against perceived verbal misconduct, such behavior is not +conducive to getting patches merged. + +* Don’t submit code that you know will break other platforms. If your patch +affects code that is used by other platforms, it should be compatible with +those platforms. While it would be nice to update any other platforms, you +must at least provide a path that will allow other platforms to continue +working. + + +Recommendations for gerrit activity: +------------------------------------ +These guidelines are less strict than the ones listed above. These are more +of the “good idea” variety. You are requested to follow the below +guidelines, but there will probably be no actual consequences if they’re +not followed. That said, following the recommendations below will speed up +review of your patches, and make the members of the community do less work. + +* Each patch should be kept to one logical change, which should be +described in the title of the patch. Unrelated changes should be split out +into separate patches. Fixing whitespace on a line you’re editing is +reasonable. Fixing whitespace around the code you’re working on should be a +separate ‘cleanup’ patch. Larger patches that touch several areas are fine, +so long as they are one logical change. Adding new chips and doing code +cleanup over wide areas are two examples of this. + +* Test your patches before submitting them to gerrit. It's also appreciated +if you add a line to the commit message describing how the patch was +tested. This prevents people from having to ask whether and how the patch +was tested. Examples of this sort of comment would be ‘TEST=Built +platform’ or ‘Tested by building and booting platform’. Stating that the +patch was not tested is also fine, although you might be asked to do some +testing in cases where that would be reasonable. + +* Take advantage of the lint tools to make sure your patches don’t contain +trivial mistakes. By running ‘make gitconfig’, the lint-stable tools are +automatically put in place and will test your patches before they are +committed. As a violation of these tools will cause the jenkins build test +to fail, it’s to your advantage to test this before pushing to gerrit. + +* Don't submit patch trains longer than around 20 patches unless you +understand how to manage long patch trains. Long patch trains can become +difficult to handle and tie up the build servers for long periods of time +if not managed well. Rebasing a patch train over and over as you fix +earlier patches in the train can hide comments, and make people review the +code multiple times to see if anything has changed between revisions. When +pushing long patch trains, it is recommended to only push the full patch +train once - the initial time, and only to rebase three or four patches at +a time. + +* Run 'make what-jenkins-does' locally on patch trains before submitting. +This helps verify that the patch train won’t tie up the jenkins builders +for no reason if there are failing patches in the train. For running +parallel builds, you can specify the number of cores to use by setting the +the CPUS environment variable. Example: + make what-jenkins-does CPUS=8 + +* Use a topic when pushing a train of patches. This groups the commits +together so people can easily see the connection at the top level of +gerrit. Topics can be set for individual patches in gerrit by going into +the patch and clicking on the icon next to the topic line. Topics can also +be set when you push the patches into gerrit. For example, to push a set of +commits with the the i915-kernel-x60 set, use the command: + git push origin HEAD:refs/for/master/i915-kernel-x60 + +* If one of your patches isn't ready to be merged, make sure it's obvious +that you don't feel it's ready for merge yet. The preferred way to show +this is by marking in the commit message that it’s not ready until X. The +commit message can be updated easily when it’s ready to be pushed. +Examples of this are "WIP: title" or "[NEEDS_TEST]: title". Another way to +mark the patch as not ready would be to give it a -1 or -2 review, but +isn't as obvious as the commit message. These patches can also be pushed as +drafts as shown in the next guideline. + +* When pushing patches that are not for submission, these should be marked +as such. This can be done in the title ‘[DONOTSUBMIT]’, or can be pushed as +draft commits, so that only explicitly added reviewers will see them. These +sorts of patches are frequently posted as ideas or RFCs for the community +to look at. To push a draft, use the command: + git push origin HEAD:refs/drafts/master + +* Respond to anyone who has taken the time to review your patches, even if +it's just to say that you disagree. While it may seem annoying to address a +request to fix spelling or 'trivial' issues, it’s generally easy to handle +in gerrit’s built-in editor. If you do use the built-in editor, remember to +get that change to your local copy before re-pushing. It's also acceptable +to add fixes for these sorts of comments to another patch, but it's +recommended that that patch be pushed to gerrit before the initial patch +gets submitted. + +* Consider breaking up large individual patches into smaller patches +grouped by areas. This makes the patches easier to review, but increases +the number of patches. The way you want to handle this is a personal +decision, as long as each patch is still one logical change. + +* If you have an interest in a particular area or mainboard, set yourself +up as a ‘maintainer’ of that area by adding yourself to the MAINTAINERS +file in the coreboot root directory. Eventually, this should automatically +add you as a reviewer when an area that you’re listed as a maintainer is +changed. + +* Submit mainboards that you’re working on to the board-status repo. This +helps others and shows that these mainboards are currently being +maintained. At some point, boards that are not up to date in the +board-status repo will probably end up getting removed from the coreboot +master branch. + +* Abandon patches that are no longer useful, or that you don’t intend to +keep working on to get submitted. + +* Bring attention to patches that you would like reviewed. Add reviewers, +ask for reviewers on IRC or even just rebase it against the current +codebase to bring it to the top of the gerrit list. If you’re not sure who +would be a good reviewer, look in the MAINTAINERS file or git history of +the files that you’ve changed, and add those people. + +* Familiarize yourself with the coreboot [commit message +guidelines](https://www.coreboot.org/Git#Commit_messages), before pushing +patches. This will help to keep annoying requests to fix your commit +message to a minimum. + +* If there have been comments or discussion on a patch, verify that the +comments have been addressed before giving a +2. If you feel that a comment +is invalid, please respond to that comment instead of just ignoring it. + +* Be conscientious when reviewing patches. As a reviewer who approves (+2) +a patch, you are responsible for the patch and the effect it has on the +codebase. In the event that the patch breaks things, you are expected to +be actively involved in the cleanup effort. This means you shouldn’t +2 a +patch just because you trust the author of a patch - Make sure you +understand what the implications of a patch might be, or leave the review +to others. Partial reviews, reviewing code style, for example, can be given +a +1 instead of a +2. This also applies if you think the patch looks good, +but may not have the experience to know if there may be unintended +consequences. + +* If there is still ongoing discussion to a patch, try to wait for a +conclusion to the discussion before submitting it to the tree. If you feel +that someone is just bikeshedding, maybe just state that and give a time +that the patch will be submitted if no new objections are raised. + +* When working with patch trains, for minor requests it’s acceptable to +create a fix addressing a comment in another patch at the end of the patch +train. This minimizes rebases of the patch train while still addressing the +request. For major problems where the change doesn’t work as intended or +breaks other platforms, the change really needs to go into the original +patch. + +* When bringing in a patch from another git repo, update the original +git/gerrit tags by prepending the lines with 'Original-'. Marking +the original text this way makes it much easier to tell what changes +happened in which repository. This applies to these lines, not the actual +commit message itself: + Commit-Id: + Change-Id: + Signed-off-by: + Reviewed-on: + Tested-by: + Reviewed-by: +The script 'util/gitconfig/rebase.sh' can be used to help automate this. +Other tags such as 'Commit-Queue' can simply be removed. + + +Expectations contributors should have: +-------------------------------------- +* Don't expect that people will review your patch unless you ask them to. +Adding other people as reviewers is the easiest way. Asking for reviews for +individual patches in the IRC channel, or by sending a direct request to an +individual through your favorite messenger is usually the best way to get a +patch reviewed quickly. + +* Don't expect that your patch will be submitted immediately after getting +a +2. As stated previously, non-trivial patches should wait at least 24 +hours before being submitted. That said, if you feel that your patch or +series of patches has been sitting longer than needed, you can ask for it +to be submitted on IRC, or comment that it's ready for submission in the +patch. This will move it to the top of the list where it's more likely to +be noticed and acted upon. + +* Reviews are about the code. It's easy to take it personally when someone +is criticising your code, but the whole idea is to get better code into our +codebase. Again, this also applies in the other direction: review code, +criticize code, but don’t make it personal. + + +Requests for clarification and suggestions for updates to these guidelines +should be sent to the coreboot mailing list at . diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md new file mode 100644 index 0000000000..b23e89d701 --- /dev/null +++ b/Documentation/getting_started/index.md @@ -0,0 +1,6 @@ +# Getting Started + +* [Build System](build_system.md) +* [Submodules](submodules.md) +* [Kconfig](kconfig.md) +* [Gerrit Guidelines](gerrit_guidelines.md) diff --git a/Documentation/getting_started/kconfig.md b/Documentation/getting_started/kconfig.md new file mode 100644 index 0000000000..7b436ce80a --- /dev/null +++ b/Documentation/getting_started/kconfig.md @@ -0,0 +1,1235 @@ +# Kconfig in coreboot + +## Overview +Kconfig is a tool used in coreboot, Linux, and many other projects as the main +configuration mechanism. In coreboot, it allows a developer both to select +which platform to build and to modify various features within the platform. The +Kconfig language was developed as a way to configure the Linux kernel, and is +still maintained as a part of the Linux kernel tree. Starting in Linux 2.5.45, +the ncurses based menuconfig was added, which is still used as the main +configuration front end in coreboot today. + +The official Kconfig source and documentation is kept at kernel.org: + +- [Kconfig source](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig) +- [Kconfig Language Documentation](https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt) + +The advantage to using Kconfig is that it allows users to easily select the +high level features of the project to be enabled or disabled at build time. +Ultimately the Kconfig tool generates a list of values which are used by the +source code and Makefiles of the project. This allows the source files to +select features, and allows the build to determine which files should be +compiled and linked to the rom. + + +## Kconfig targets in Make +The Kconfig program in coreboot is built from source in util/kconfig. There are +various targets in the makefile to build Kconfig in different ways. These give +the user control over how to build the platform + + +### Front end configuration targets +These are the make targets that would be used to update the configuration of +the platform. +- config - Text mode configuration tool, asks each configuration option in turn. + This does actually run in coreboot, but it is recommended that this not be + used as there is no way to save a partial config. +- gconfig - Graphical configuration tool based on GTK+ 2.0. +- menuconfig - Text mode, menu driven configuration tool. +- nconfig - Text mode, menu driven configuration tool. +- xconfig - Graphical front end based on QT. + + +### Targets that update config files +These options are used to update the coreboot config files, typically .config. +The target file can be changed with variables in the environment or on the make +command line. + +- defconfig - This generates a config based on another config file. Use the + environment variable KBUILD_DEFCONFIG to specify the base config file. +- oldconfig - Displays the answers to all configuration questions as it + generates the config.h file. If an interactive question is found that does + not have an answer yet, it stops and queries the user for the desired value. +- olddefconfig - Generates a config, using the default value for any symbols not + listed in the .config file. +- savedefconfig - Creates a ‘mini-config’ file, stripping out all of the symbols + that were left as default values. This is very useful for debugging, and is + how config files should be saved. +- silentoldconfig - This evaluates the .config file the same way that the + oldconfig target does, but does not print out each question as it is + evaluated. It still stops to query the user if an option with no answer in + the .config file is found. + + +### Targets not typically used in coreboot +- localmodconfig, localnoconfig, randconfig, allyesconfig, allnoconfig - These + are all used to generate various Kconfig files for testing. + + +### Environment Variables that affect Kconfig +These variables are typically set in the makefiles or on the make command line. + +#### Variables added to the coreboot Kconfig source +These variables were added to Kconfig specifically for coreboot and are not +included in the Linux version. + +- COREBOOT_BUILD_DIR=path for temporary files. This is used by coreboot’s + abuild tool. + +- KCONFIG_STRICT=value. Define to enable warnings as errors. This is enabled + in coreboot, and should not be changed. + +- KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file + (build/config.h). This is enabled in coreboot, and should not be changed. + + +#### Variables used to control the input and output config files +- KBUILD_DEFCONFIG=inputname of the defconfig file. This defaults to + ‘configs/defconfig’ and is used by the ‘defconfig’ target. + +- DEFCONFIG=output name of the defconfig file. This defaults to ‘defconfig’ + and is used by ‘savedefconfig’ target as the output filename. + +- DOTCONFIG=name of the .config file. This defaults to '.config' and is used + by most config type targets. + + +#### Variables used by the makefiles for controlling Kconfig +- Kconfig=root Kconfig file. This is set to 'src/Kconfig' in the coreboot + makefile. + +- KCONFIG_CONFIG=input config file. coreboot sets this to $(DOTCONFIG). + +- KCONFIG_AUTOHEADER=path and filename of autoconf.h file. coreboot sets this + to $(obj)/config.h. + +- KCONFIG_DEPENDENCIES=”kbuild dependency file". This defaults to + auto.conf.cmd and outputs the name of all of the Kconfig files used. + +- KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”. + coreboot sets this to $(obj)/config. + +#### Used only for ‘make menuconfig’ +- MENUCONFIG_MODE=single_menu. Set to "single_menu" to enable. All other + values disable the option. This makes submenus appear below the menu option + instead of opening a new screen. + +- MENUCONFIG_COLOR=<theme>. This sets the color theme for the menu from + these options: + + - mono => selects colors suitable for monochrome displays. + - blackbg => selects a color scheme with black background. + - classic => theme with blue background. The classic look. + - bluetitle => an LCD friendly version of classic. (default). + + +#### Used only for ‘make nconfig’ + +- NCONFIG_MODE=single_menu + + Submenus appear below the menu option instead of opening a new screen. + + +#### Unused in coreboot + +Although these variables are not used by coreboot, their values should be left +at the default values. Other values may have unexpected effects on the +codebase. + +- KCONFIG_SEED=randconfig seed value. +- KCONFIG_PROBABILITY=randconfig percent to set to y. +- KCONFIG_NOSILENTUPDATE=value. Define to prevent silent updates to .config + file. +- KCONFIG_OVERWRITECONFIG=value. Define to prevent breaking a .config symlink. +- KCONFIG_TRISTATE=filename of tristate.conf file. +- SRCTREE=path to src directory. +- KCONFIG_AUTOCONFIG=path and filename of the auto.conf file. + + coreboot sets this to $(obj)/auto.conf. Although this value is actually + set by coreboot, the resulting file is not used. + +- CONFIG_=prefix for Kconfig output symbols. + + coreboot expects this to *NOT* be set. + + + +## Kconfig Language + +The Kconfig language has about 30 keywords, some overloaded, and some with the +same meaning. Whitespace may have specific meaning, for example in the 'help' +keyword. There are 8 logical operators for use in expressions, which allow +values to be set based on other values. + + +### Terminology + +- Symbols - There are two types of symbols, "constant" and “non-constant”. + - Constant symbols are alphanumeric values used in expressions for + comparison. The Kconfig language specification says that these must be + surrounded by single or double quotes. + - Non-constant symbols are the 'config' values that are output into the + saved .config, auto.conf and config.h files. Non-constant symbols are + typically defined with the 'config' keyword, although they can also be + defined with the 'choice' keyword. These symbols may be used in a file's + expressions before they are defined. Valid characters for non-constant + symbols are any combination of alphanumeric characters, underscore. + Although “1234” is accepted as a symbol name, as is “o_o”, convention is + to use all uppercase words that are descriptive of the symbol's use so + they make sense when turned into CONFIG_NAME #defines. + +- Expressions - An expression is a logical evaluation. It can be as simple as + a static 'y' or 'n', or can be a symbol. Alternatively, expressions can be + complex evaluations of multiple symbols using the various logical operators. + The Kconfig language allows these logical evaluations in several places. The + most common use for complex expressions is following 'if' or ‘depends on’ + keywords, but they can also be used to set the value for a prompt or default + values. + +- Types - Each Kconfig symbol is one of the following types: bool, hex, int, + string, or tristate. The tristate type is not used for coreboot, leaving just + four types. As noted in the keyword summaries, a symbol must have a consistent + type anywhere it is defined. Also, Kconfig will simply not display a symbol + that has no type defined. A warning will be displayed in the terminal where + menuconfig was run if this happens: + _src/Kconfig:25:warning: config symbol defined without type_. + +- Prompts - Input prompts are the text associated with the symbols which shown + to the user. The Kconfig language definition does not require surrounding the + prompt’s text with quotes, however it is recommended that quotes be used for + maximum compatibility. + +- Menu Entries - These keyword blocks create the symbols and questions that are + visible in the front end. + + +## Keywords + +### bool + +The 'bool' keyword assigns a boolean type to a symbol. The allowable values for +a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt +string which makes the symbol editable in one of the configuration front ends. + + +##### Usage: +bool \[prompt\] \[if <expr>\] + + +##### Example: + config ANY_TOOLCHAIN + bool "Allow building with any toolchain" + default n + depends on COMPILER_GCC + + +##### Notes: +- Putting the prompt after the 'bool' keyword is the same as using a 'prompt' + keyword later. See the 'prompt' keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. +- Boolean symbols do not need a default and will default to ‘n’. + + +##### Restrictions: + +- This keyword must be within a symbol definition block, started by the + 'config' keyword. + +-------------------------------------------------------------------------------- + +### choice + +This creates a selection list of one or more boolean symbols. For bools, only +one of the symbols can be selected, and one will be be forced to be selected, +either by a ‘default’ statement, or by selecting the first config option if +there is no default value listed. + +##### Usage: +choice \[symbol\] +- \[prompt\] +- \[default\] + + +##### Example: + choice TESTCHOICE + prompt "Test choice" + default TESTCHOICE2 if TESTCHOICE_DEFAULT_2 + default TESTCHOICE3 + + config TESTCHOICE1 + bool "Choice 1" + config TESTCHOICE2 + bool "Choice 2" + config TESTCHOICE3 + bool "Choice 3" + config TESTCHOICE4 + bool "Choice 4" if TESTCHOICE_SHOW_4 + endchoice + + config TESTCHOICE_DEFAULT_2 + def_bool y + + config TESTCHOICE_SHOW_4 + def_bool n + + config TESTSTRING + string + default “String #1” if TESTCHOICE1 + default “String #2” if TESTCHOICE2 + default “String #4” if TESTCHOICE3 + default “String #4” if TESTCHOICE4 + default “” + + +##### Notes: +- If no symbol is associated with a choice, then you can not have multiple + definitions of that choice. If a symbol is associated to the choice, then + you may define the same choice (ie. with the same entries) in another place. + Any selection in either location will update both choice menu selections. In + coreboot, the value of the symbol is always 1. +- As shown in the example above, the choice between bools can be used to set + the default for a non-bool type. This works best when the non-bool type + does not have an input prompt. + + +##### Restrictions: +- Symbols used for 'choice' entries must have input prompts defined using the + 'prompt' keyword. +- Symbols used in 'choice' entries may not be enabled with a 'select' + statement, they can be defaulted using a second Kconfig symbol however. + +-------------------------------------------------------------------------------- + +### comment + +This keyword defines a line of text that is displayed to the user in the +configuration frontend and is additionally written to the output files. + + +##### Usage: +comment <prompt> +- \[depends on\] + + +##### Example: + + if CONSOLE_SERIAL + comment "I/O mapped, 8250-compatible" + depends on DRIVERS_UART_8250IO + endif + + +##### Notes: +- Comments are only valid outside of config blocks, but can be within menu and + if blocks. + +-------------------------------------------------------------------------------- + +### config + +This is the keyword that starts a block defining a Kconfig symbol. The symbol +modifiers follow the 'config' statement. + +##### Usage: +config <symbol> + +- \[bool | def_bool | int | hex | string\] +- \[depends on\] +- \[prompt\] +- \[help\] +- \[range\] +- \[select\] + + +##### Example: + config SEABIOS_PS2_TIMEOUT + prompt "PS/2 keyboard timeout" if PAYLOAD_SEABIOS + default 0 + depends on PAYLOAD_SEABIOS + int + help + Some PS/2 keyboard controllers don't respond to commands + immediately after powering on. This specifies how long + SeaBIOS will wait for the keyboard controller to become + ready before giving up. + + +##### Notes: +- Non-coreboot projects also use the 'tristate' and 'def_tristate' types. +- Ends at the next Kconfig keyword that is not valid inside the config block: + + menu | endmenu | if | endif | choice | config | source | comment + +-------------------------------------------------------------------------------- + +### default + +The ‘default’ keyword assigns a value to a symbol in the case where no preset +value exists, i.e. the symbol is not present and assigned in .config. If there +is no preset value, and no ‘default’ keyword, the user will be asked to enter a +valid value when building coreboot. + + +##### Usage: +default <expr> \[if <expr>\] + + +##### Example: + config GENERATE_MP_TABLE + prompt "Generate an MP table" if HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC + bool + default HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC + help + Generate an MP table (conforming to the Intel + MultiProcessor specification 1.4) for this board. + + +##### Notes: +- Kconfig defaults for symbols without a prompt *NEVER* affect existing legal + symbol definitions in a .config file. The default only affects the symbol if + there is no valid definition in a config file. This is a frequent source of + confusion. It’s covered again in the Tips section below. +- The first valid 'default' entry for a symbol is always used. Any further + 'default' statements for a symbol are ignored. This means that the order of + Kconfig files is very important as the earlier files get to set the defaults + first. They should be sourced in the order from most specific (mainboard + Kconfig files) to the most generic (architecture-specific Kconfig files). +- If there is no 'default' entry for a symbol, it gets set to 'n', 0, 0x0, or + “” depending on the type, however the 'bool' type is the only type that + should be left without a default value. + +-------------------------------------------------------------------------------- + +### def_bool + +‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to +boolean. It lets you set the type and default value at the same time, instead +of setting the type and the prompt at the same time. It's typically used for +symbols that don't have prompts. + + +##### Usage: +def_bool <expr> \[if <expr>\] + + +##### Example: + config EC_GOOGLE_CHROMEEC_LPC + depends on EC_GOOGLE_CHROMEEC && ARCH_X86 + def_bool y + select SERIRQ_CONTINUOUS_MODE + help + Google Chrome EC via LPC bus. + + +##### Notes: +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the + 'config' keyword. + +-------------------------------------------------------------------------------- + +### depends on + +This defines a dependency for a menu entry, including symbols and comments. It +behaves the same as surrounding the menu entry with an if/endif block. If the +‘depends on’ expression evaluates to false, the 'prompt' value will not be +printed, and defaults will not be set based on this block. + + +##### Usage: +depends on <expr> + + +##### Example: + config COMMON_CBFS_SPI_WRAPPER + bool + default n + depends on SPI_FLASH + depends on !ARCH_X86 + help + Use common wrapper to interface CBFS to SPI bootrom. + + +##### Notes: +- Symbols that have multiple ‘depends on’ sections as above are equivalent to a + single ‘depends on’ statement with sections joined by &&. So the above is + the same as “depends on SPI_FLASH && ! ARCH_X86”. + +-------------------------------------------------------------------------------- + +### endchoice + +This ends a choice block. See the 'choice' keyword for more information and an +example. + +-------------------------------------------------------------------------------- + +### endif + +This ends a block started by the 'if' keyword. See the 'if' keyword for more +information and an example. + +-------------------------------------------------------------------------------- + +### endmenu + +This ends a menu block. See the 'menu' keyword for more information and an +example. + +-------------------------------------------------------------------------------- + +### help + +The 'help' keyword defines the subsequent block of text as help for a config or +choice block. The help block is started by the 'help' keyword on a line by +itself, and the indentation level of the next line controls the end of the help +block. The help ends on the next non-blank line that has an indentation level +less than the indentation level of the first line following the 'help' keyword. + +##### Usage: +help <help text> + + +##### Example: + config COMPILER_GCC + bool "GCC" + help + Use the GNU Compiler Collection (GCC) to build coreboot. For details + see http://gcc.gnu.org. + + +##### Notes: +- Identical to the '---help---' keyword which isn’t used in coreboot. +- Other keywords are allowed inside the help block, and are not recognized as + keywords so long as the indentation rules are followed, even if they start a + line. + + +##### Restrictions: +- Only used for 'config' and 'choice' keywords. + +-------------------------------------------------------------------------------- + +### hex + +This is another symbol type specifier, specifying an unsigned integer value +formatted as hexadecimal. + +##### Usage: +hex <expr> \[if <expr>\] + + +##### Example: + config INTEL_PCH_UART_CONSOLE_NUMBER + hex "Serial IO UART number to use for console" + default 0x0 + depends on INTEL_PCH_UART_CONSOLE + + +##### Notes: +- Kconfig doesn’t complain if you don’t start the default value for a hex + symbol with ‘0x’, but not doing so will lead to issues. It will update 10 + to 0x10 without warning the user. +- Putting the prompt text after the 'hex' keyword is the same as using a + 'prompt' keyword later. See the 'prompt' keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the + 'config' keyword. +- 'hex' type symbols must have a 'default' entry set. + +-------------------------------------------------------------------------------- + +### if + +The 'if' keyword is overloaded, used in two different ways. The first definition +enables and disables various other keywords, and follows the other keyword +definition. This usage is shown in each of the other keywords' usage listings. + +The second usage of the 'if' keyword is part of an if/endif block. Most items +within an if/endif block are not evaluated, while others, such as the 'source' +keyword, ignore the existence of the if/endif block completely. Symbols defined +within an if/endif block are still created, although their default values are +ignored - all values are set to 'n'. + + +##### Usage: +if <expr> + +- \[config\] +- \[choice\] +- \[comment\] +- \[menu\] + +endif + + +##### Example: + if ARCH_X86 + + config SMP + bool + default y if MAX_CPUS != 1 + default n + help + This option is used to enable certain functions to make + coreboot work correctly on symmetric multi processor (SMP) systems. + endif + +##### Restrictions: +- Corresponding ‘if’ and ‘endif’ statements must exist in the same file. + +-------------------------------------------------------------------------------- + +### int + +A type setting keyword, defines a symbol as an integer, accepting only signed +numeric values. The values can be further restricted with the ‘range’ keyword. + + +##### Usage: +int <expr> \[if <expr>\] + + +##### Example: + config PRE_GRAPHICS_DELAY + int "Graphics initialization delay in ms" + default 0 + help + On some systems, coreboot boots so fast that connected + monitors (mostly TVs) won't be able to wake up fast enough + to talk to the VBIOS. On those systems we need to wait for a + bit before executing the VBIOS. + + +##### Notes: +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' + keyword. +- 'int' type symbols must have a default value set. + +-------------------------------------------------------------------------------- + +### mainmenu + +The 'mainmenu' keyword sets the title or title bar of the configuration front + end, depending on how the configuration program decides to use it. It can only + be specified once and at the very beginning of the top level Kconfig file, + before any other statements. + + +##### Usage: +mainmenu <prompt> + +##### Example: +mainmenu "coreboot configuration" + +##### Restrictions: +- Must be the first statement in the top level Kconfig. +- Must only be used once in the entire Kconfig tree. + +-------------------------------------------------------------------------------- + +### menu + +The 'menu' and 'endmenu' keywords tell the configuration front end that the +enclosed statements are part of a group of related pieces. + + +##### Usage: +menu <prompt> + +- \[choice\] +- \[config\] +- \[menu\] +- \[if/endif\] + +endmenu + + +##### Example: + menu "On-Chip Device Power Down Control" + config TEMP_POWERDOWN + bool "Temperature sensor power-down" + + config SATA_POWERDOWN + bool "SATA power-down" + + config ADC_POWERDOWN + bool "ADC power-down" + + config PCIE0_POWERDOWN + bool "PCIE0 power-down" + + config MAC_POWERDOWN + bool "MAC power-down" + + config USB1_POWERDOWN + bool "USB2.0 Host Controller 1 power-down" + + config IDE_POWERDOWN + bool "IDE power-down" + + endmenu + +##### Restrictions: +- Must be closed by a corresponding ‘endmenu’ keyword in the same file. + +-------------------------------------------------------------------------------- + +### prompt + +The 'prompt' keyword sets the text displayed for a config symbol or choice in +configuration front end. + + +##### Usage: +prompt <prompt> \[if <expr>\] + + +##### Example: + config REALMODE_DEBUG + prompt "Enable debug messages for option ROM execution" + bool + default n + depends on PCI_OPTION_ROM_RUN_REALMODE + depends on DEFAULT_CONSOLE_LOGLEVEL_7 || DEFAULT_CONSOLE_LOGLEVEL_8 + help + This option enables additional x86emu related debug + messages. Note: This option will increase the time to emulate a ROM. + + If unsure, say N. + + +##### Notes: +- The same rules apply for menu entries defined by the 'prompt' keyword and + other prompt types such as those defined by the 'int' or 'string' keywords. +- Redefining the prompt text in multiple instances of config symbols is allowed. + Only the current prompt statement for a particular entry will be displayed by + the front end in any given location. This means that multiple mainboards can + set different prompt values for a symbol, and it would appear differently in + each mainboard’s menu. The symbol can even have multiple entries in the same + menu with different prompts if desired. For example, both of these would get + printed, and changing either entry would change the other. + + config PROMPT_TEST + string "Prompt value 1" + + config PROMPT_TEST + prompt "Prompt value 2" + +- Although not required, it's recommended that you use quotes around prompt + statements. +* If the prompt is redefined inside the SAME config entry, you will get a + warning: + _warning: prompt redefined_. + For example, this is not allowed: + + config PROMPT_TEST + string "Prompt value 1" + prompt "Prompt value 2" +-------------------------------------------------------------------------------- + +### range + +This sets the allowable minimum and maximum entries for hex or int type config +symbols. + + +##### Usage: +range <symbol> <symbol> \[if <expr>\] + + +##### Example: + config TEST1 + hex "test 1" + range 0x0 0x10 + + +##### Notes: +- Only the first definition of a range is used for any symbol. Further + definitions will be ignored without warning. + +-------------------------------------------------------------------------------- + +### select + +The ‘select’ keyword is used within a bool type config block. In coreboot (and +other projects that don't use modules), the 'select' keyword can force an +unassociated bool type symbol to 'y'. When the symbol for the config block is +‘y’, the ‘select’ action is taken. Otherwise the bool is unaffected. + + +##### Usage: +select <symbol> \[if <expr>\] + + +##### Example: + config TPM + bool + default n + select LPC_TPM if ARCH_X86 + select I2C_TPM if ARCH_ARM + select I2C_TPM if ARCH_ARM64 + help + Enable this option to enable TPM support in coreboot. + If unsure, say N. + +##### Notes: +- Using the 'select' keyword can create logical contradictions in Kconfig, which + will create warnings and fail to save the .config. Following is an example of + an obviously invalid configuration, where selecting BOOLTEST violates the + ‘depends on’ of BOOLTEST2: + + config BOOLTEST + bool "bool Test" + select BOOLTEST2 + + config BOOLTEST2 + bool "Bool Test 2" + depends on !BOOLTEST + +##### Restrictions: +- The ‘select’ keyword only works on bool type symbols. +- Symbols created inside of choice blocks cannot be selected, and should be + enabled by using default values instead. + +-------------------------------------------------------------------------------- + +### source + +The 'source' keyword functions much the same as an 'include' statement in c. +This pulls one or more files into Kconfig at the location of the 'source' +command. This statement is always parsed - there is no way to conditionally +source a file. coreboot has modified the source statement slightly to handle +directory globbing. The '*' character will match with any directory. + + +##### Usage: +source <prompt> + + +##### Example: + + choice + prompt "Mainboard vendor" + default VENDOR_EMULATION + + source "src/mainboard/*/Kconfig.name" + + endchoice + + source "src/mainboard/*/Kconfig" + + +##### Notes: +- As with all prompt values, the 'source' prompt may be enclosed in single or + double quotes, or left without any quotes. Using quotes is highly recommended + however. +- The 'source' keyword loads files relative to the working directory where the + Kconfig command was run. For coreboot, this is the root coreboot directory, so + all source commands in the src directory need to start with ‘src/’. +- In coreboot's Kconfig, if a sourced file does not exist, the statement is + simply ignored. This is different than other versions of Kconfig. +- 'source' pulls a file into the Kconfig tree at the location of the keyword. + This allows for files containing small bits of the Kconfig tree to be pulled + into a larger construct. A restriction on this is that the starting/ending + keyword pairs must be within the same file - ‘endif’ cannot appear in a + different file than the ‘if’ statement that it ends. The same is true of + menu/endmenu and choice/endchoice pairs. + +The coreboot Kconfig structure uses this along with globbing to build up the +mainboard directory. Each mainboard’s Kconfig.name file contains just two +statements that generate a list of all the platform names: + + config BOARD_AMD_NORWICH + bool "Norwich" + + +##### Restrictions: +- 'source' keywords always load in the specified file or files. There is no way + to optionally pull in a file. Putting an if/endif block around a source + command does not affect the source command, although it does affect the + content. To avoid confusion, use if/endif blocks inside sourced files to + remove their content if necessary. + +-------------------------------------------------------------------------------- + +### string + +The last of the symbol type assignment keywords. 'string' allows a text value to +be entered. + + +##### Usage: +string <expr> \[if <expr>\] + + +##### Example: + config BOOTBLOCK_SOUTHBRIDGE_INIT + string + default "southbridge/amd/pi/hudson/bootblock.c" + + config HUDSON_GEC_FWM_FILE + string "GEC firmware path and filename" + depends on HUDSON_GEC_FWM + + +##### Notes: +- Putting the prompt after the 'string' keyword is the same as using a 'prompt' +keyword later. See the prompt keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'string'_. +- Some characters may not get interpreted correctly when inside a string entry + depending on how they are used - inside a C file, inside a Makefile, passed + through a Makefile to a C file, or something else. It may be necessary to + escape the characters at times. Because this is very dependent upon how the + symbol is actually used, a definitive guide cannot be given here. +- 'string' type variables do NOT need a default, and will default to the + value “”. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' + keyword. + +-------------------------------------------------------------------------------- + + + + +## Keywords not used in coreboot at the time of writing: + +- allnoconfig_y: +- defconfig_list +- def_tristate +- env +- ---help--- +- menuconfig +- modules +- optional +- option +- tristate +- visible if + + +## Build files generated by Kconfig + +### build/config.h + +The config.h file is a very basic header file made up of a list of #define +statements: + + #define SYMBOL NAME XXX + + +##### Symbol types: +- bool, int, and hex types - Every symbol of one of these types created in the + Kconfig tree is defined. It doesn’t matter whether they’re in an if/endif + block, or have a ‘depends on’ statement - they ALL end up being defined in + this file. +- String - Only string types that actually have a value associated with them + are defined. + +The config.h file uses 0 and 1 to represent Kconfig's 'n' and 'y' values +respectively. String values are placed inside double quotes. + +The name of the file is controlled by the $KCONFIG_AUTOHEADER environment +variable, which is set to $(obj)/config.h by the coreboot makefiles. + +The prefix used for the symbols is controlled by the $CONFIG_ environment +variable. This is not set in coreboot, which uses the default CONFIG_ prefix +for all of its symbols. + +The coreboot makefile forces the config.h file to be included into all coreboot +C files. This is done in Makefile.inc on the compiler command line using the +“-include $(obj)/config.h” command line option. + +Example of various symbol types in the config.h file: + + #define CONFIG_BOOTBLOCK_SOURCE "bootblock_simple.c" # String + #define CONFIG_CBFS_SIZE 0x00300000 # Hex + #define CONFIG_TTYS0_BAUD 115200 # Int + #define CONFIG_HAVE_ACPI_TABLES 1 # Bool enabled + #define CONFIG_EXPERT 0 # Bool disabled + #define CONFIG_NORTHBRIDGE_INTEL_I440LX 0 # Bool excluded + + +### .config + +The .config file in the root directory is used as the input file, but also by +the makefiles to set variable values. The main difference is that it does not +contain all of the symbols. It excludes symbols defined in an if/endif block +whose expression evaluated as false. Note that the symbol +CONFIG_NORTHBRIDGE_INTEL_I440LX shown in the config.h example above is not +present in the .config file. + +In addition, the .config file below contains the 'comment' prompt text from the +Kconfig, separating the blocks. + + ## General setup ## + CONFIG_BOOTBLOCK_SOURCE="bootblock_simple.c" # String + CONFIG_CBFS_SIZE=0x00300000 # Hex + CONFIG_TTYS0_BAUD=115200 # Int + CONFIG_HAVE_ACPI_TABLES=y # Bool enabled + # CONFIG_EXPERT is not set # Bool disabled + +This file is included directly by the makefile, and sets the CONFIG symbols so +that they are available during the build process. + + +### build/auto.conf + +Although the controlling variable for the auto.conf filename, +KCONFIG_AUTOCONFIG, is set in the coreboot makefiles, the auto.conf file itself +is not used by coreboot. This file has the same syntax and structure as the +.config file, but contains all symbols in the Kconfig tree, including those that +are not enabled, or are excluded by if/endif blocks, or the 'depends on' +keyword. The kconfig tool could be updated to not generate this file, but since +it's not hurting anything, it's still being generated. + + + +## Defconfig or Miniconfig files + +Miniconfig files are the standard .config files with all of the symbols which +are set to their default values stripped out. These files are very useful for +debugging your config, as well as being the best way to store your .config file. +If you store your config as a full config file, it will be much harder to +maintain. Any Kconfig symbols with updated default values will retain their old +values, and any symbols which have been removed will still remain in the file. +Storing full config files just generally leads to a lot more maintenance than +storing miniconfig files. + +The easiest way to generate the miniconfig file is by running + + make savedefconfig DOTCONFIG=.config DEFCONFIG=[output file] + +DEFCONFIG defaults to ‘defconfig’, DOTCONFIG defaults to ‘.config’. + + +To turn the miniconfig back into a full config file, use one of the two targets: + + make olddefconfig DOTCONFIG=[input/output file] + +or + + make defconfig KBUILD_DEFCONFIG=[input file] DOTCONFIG=[output file] + +In both of these cases, DOTCONFIG defaults to .config. + + + +## Editing and updating saved .config files + + +### Don’t save full config files + +Save miniconfig files, as mentioned in the previous section. + + +### Disable values with ‘# CONFIG_SYMBOL is not set’ + +A common mistake when trying to disable a value is to edit the .config file and +change it from ‘CONFIG_SYMBOL=y’ to ‘CONFIG_SYMBOL=n’, but this doesn’t +correctly disable the symbol. If the default value for the symbol is ‘n’ to +begin with, this isn’t an issue - the symbol just gets ignored, and the default +value is used. The problem is where the default for the symbol is ‘y’. When +the bad entry in the .config file gets ignored, the value is set back to ‘y’, +leading to much frustration. + +Always disable the Kconfig symbols in the .config file with the syntax: + + # CONFIG_SYMBOL is not set + +### Only the LAST instance of a symbol is used + +When reading a saved .config file, Kconfig uses the LAST instance of a symbol +that it comes across, and ignores any previous instances. This can be used to +override symbols in a saved .config file by appending the new value to a config +file. + +For example: + +A .config file that contains these two lines: + + # CONFIG_BOOLTEST is not set + CONFIG_BOOLTEST=y + +After running ‘make olddefconfig’, ends up with the value: + + CONFIG_BOOLTEST=y + +A case where this can be used is by a making a script to create two versions of +a coreboot rom for a single platform. The first ROM could be built with serial +console disabled, and the second ROM, built as a debug version, could have +serial console enabled by overriding the "CONFIG_CONSOLE_SERIAL" symbol, and +setting it to enabled. + +## General Kconfig Tips and Notes + +### Default values for config options + +The FIRST valid default that the Kconfig parser comes across will be used for +each symbol. This means that the organization of the tree is very important. +The structure should go from most specific at the top of the Kconfig tree to the +most general later in the tree. In coreboot, the mainboard directories get +loaded first, as they are sourced very early in the src/Kconfig file. Chipset +Kconfig files get sourced later, and the architecture specific Kconfig files get +sourced even later. This allows the mainboards to set their defaults early, +overriding the default values set in chipset or architecture. + +Due to this mechanism, a default defined early cannot be changed by a default +set in a later Kconfig file. There are ways around this, involving 'depends on' +statements, but they add additional variables which are generally just used +internal to Kconfig. + + +### Select statement usage + +The 'select' keyword forces the value of a symbol with a bool type to 'y'. It +overrides any dependencies of the symbol, so using it carelessly can lead to +unpredictable results. + + + +### All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code + +All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code if they +are in a sourced Kconfig - do NOT use #ifdef CONFIG_SYMBOL + +String symbols are the exception. All others (int, hex, etc.) are always +defined in config.h. Never use an #ifdef statement for a Kconfig symbol other +than strings in C to determine whether the symbol is enabled or disabled. So +long as the symbol is in ANY sourced Kconfig file, it will be defined. Even if +the symbol is only inside of an if/endif block where the if expression evaluates +as false, the symbol STILL gets defined in the config.h file (though not in the +.config file). + +Use \#if IS_ENABLED(CONFIG_*) to be sure (it returns false for undefined symbols +and defined-to-0 symbols alike). + + + +### Symbols with prompts use defaults *ONLY* when initially created or enabled. + +Symbols with a prompt which may be user-modified are NOT updated to default +values when changing between platforms or modifying other symbols. There are +only two times the default values are used: +1. When a config is initially created. +2. When a dependency which had previously kept the symbol from being active + changes to allowing it to be active. + +Because of this, starting with a saved .config for one platform and updating it +for another platform can lead to very different results than creating a platform +from scratch. + + + +### Symbols with no prompt will be the default value (unless 'select' is used). + +Symbols that do not have a prompt will always use the first valid default value +specified in Kconfig. They cannot be updated, even if they are modified in a +saved .config file. As always, a 'select' statement overrides any specified +'default' or 'depends on' statement. + + +## Differences between coreboot's Kconfig and other Kconfig implementations. + +- coreboot has added the glob operator '*' for the 'source' keyword. +- coreboot’s Kconfig always defines variables except for strings. In other + Kconfig implementations, bools set to false/0/no are not defined. +- IS_ENABLED() is ‘false’ for undefined variables and ‘0’ variables. In Linux + (where the macro comes from) it’s ‘true’ as soon as the variable is defined. +- coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to + error out if there are any issues in the Kconfig files. In the Linux kernel, + Kconfig will generate a warning, but will still output an updated .config or + config.h file. + + +## Kconfig Editor Highlighting + +#### vim: + +vim has syntax highlighting for Kconfig built in (or at least as a part of +vim-common), but most editors do not. + + +#### ultraedit: + +https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew + + + +#### atom: + +https://github.com/martinlroth/language-kconfig + + +## Syntax Checking: + +The Kconfig utility does some basic syntax checking on the Kconfig tree. +Running "make silentoldconfig" will show any errors that the Kconfig utility +sees. + +### util/kconfig_lint + +Because the Kconfig utility is relatively forgiving, and ignores issues that a +developer might be interested in, kconfig_lint, another Kconfig checker has been +written. + +The file kconfig_lint and its associated readme can be found in the coreboot +utils/lint directory. It is useful for parsing the Kconfig tree, and for +showing warnings, errors, and notes about coreboot’s Kconfig files. + + + kconfig_lint + -o|--output=file Set output filename + -p|--print Print full output + -e|--errors_off Don't print warnings or errors + -w|--warnings_off Don't print warnings + -n|--notes Show minor notes + --path=dir Path to top level kconfig + -c|--config=file Filename of config file to load + -G|--no_git_grep Use standard grep tools instead of git grep + + +The -p option is very useful for debugging Kconfig issues, because it reads all +of the Kconfig files in the order that the Kconfig tools would read them, and +prints it out, along with where each line came from and which menu it appears +in. + +## License: +This work is licensed under the Creative Commons Attribution 4.0 International +License. To view a copy of this license, visit +https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative +Commons, PO Box 1866, Mountain View, CA 94042, USA. + +Code examples snippets are licensed under GPLv2, and are used here under fair +use laws. diff --git a/Documentation/getting_started/submodules.md b/Documentation/getting_started/submodules.md new file mode 100644 index 0000000000..631e351303 --- /dev/null +++ b/Documentation/getting_started/submodules.md @@ -0,0 +1,46 @@ +Use of git submodules in coreboot +================================= +coreboot uses git submodules to keep certain parts of the tree separate, +with two major use cases: + +First, we use a vendor tool by NVIDIA for systems based on their SoC +and since they publish it through git, we can just import it into our +tree using submodules. + +Second, lots of boards these days require binaries and we want to keep +them separate from coreboot proper to clearly delineate shiny Open Source +from ugly blobs. +Since we don't want to impose blobs on users who really don't need them, +that repository is only downloaded and checked out on explicit request. + +Handling submodules +------------------- +For the most part, submodules should be automatically checked out on the +first execution of the coreboot Makefile. + +To manually fetch all repositories (eg. when you want to prepare the tree +for archiving, or to use it without network access), run + + $ git submodule update --init --checkout + +This also checks out the binaries below `3rdparty/` + +Mirroring coreboot +------------------ +When running a coreboot mirror to checkout from, for full operation, you +should also mirror the blobs and nvidia-cbootimage repository, and place +them in the same directory as the coreboot repository mirror. + +That is, when residing in coreboot's repository, `cd ../blobs.git` +should move you to the blobs repository. + +With that, no matter what the URL of your coreboot repository is, the +git client (of a sufficiently new version) is able to pick up the other +repositories transparently. + +Minimum requirements +-------------------- +git needs to be able to handle relative paths to submodule repositories, +and it needs to know about non-automatic submodules. + +For these features, we require git version 1.7.6.1 or newer. diff --git a/Documentation/index.md b/Documentation/index.md index a3cda52550..afe892da6a 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -1,5 +1,4 @@ -Welcome to coreboot's documentation! -==================================== +# Welcome to the coreboot documentation This is the developer documentation for [coreboot](https://coreboot.org). It is built from Markdown files in the @@ -8,16 +7,14 @@ directory in the source code. Contents: -* [Lesson 2: Submitting a patch to coreboot.org](Lesson2.md) -* [Gerrit Etiquette and Guidelines](gerrit_guidelines.md) -* [coreboot's build system](build_system.md) -* [Kconfig in coreboot](core/Kconfig.md) -* [Use of git submodules in coreboot](submodules.md) +* [Getting Started](getting_started/index.md) +* [Rookie Guide](lessons/index.md) * [Timestamps](timestamp.md) * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md) * [ABI data consumption](abi-data-consumption.md) * [GPIO toggling in ACPI AML](acpi/gpio.md) * [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md) -* [Sandy Bridge Raminit](Intel/NativeRaminit/Sandybridge.md) +* [Northbridge-specific documentation](northbridge/index.md) +* [System on Chip-specific documentation](soc/index.md) * [Mainboard-specific documentation](mainboard/index.md) * [SuperIO-specific documentation](superio/index.md) diff --git a/Documentation/lessons/index.md b/Documentation/lessons/index.md new file mode 100644 index 0000000000..6540e8c4fa --- /dev/null +++ b/Documentation/lessons/index.md @@ -0,0 +1,4 @@ +# Rookie Guide + +* [Lesson 1: Starting from scratch](lesson1.md) +* [Lesson 2: Submitting a patch to coreboot.org](lesson2.md) diff --git a/Documentation/lessons/lesson1.md b/Documentation/lessons/lesson1.md new file mode 100644 index 0000000000..0a10ba3723 --- /dev/null +++ b/Documentation/lessons/lesson1.md @@ -0,0 +1,168 @@ +coreboot lesson 1 - Starting from scratch +========================================= + +From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for +a very basic build: + +Download, configure, and build coreboot +--------------------------------------- + +### Step 1 - Install tools and libraries needed for coreboot + $ sudo apt-get install -y bison build-essential curl flex git gnat-5 libncurses5-dev m4 zlib1g-dev + +### Step 2 - Download coreboot source tree + $ git clone https://review.coreboot.org/coreboot + $ cd coreboot + +### Step 3 - Build the coreboot toolchain +Please note that this can take a significant amount of time + + $ make crossgcc-i386 CPUS=$(nproc) + +Also note that you can possibly use your system toolchain, but the results are +not reproducible, and may have issues, so this is not recommended. See step 5 +to use your system toolchain. + +### Step 4 - Build the payload - coreinfo + $ make -C payloads/coreinfo olddefconfig + $ make -C payloads/coreinfo + +### Step 5 - Configure the build + +* ##### Configure your mainboard + $ make menuconfig + select 'Mainboard' menu + Beside 'Mainboard vendor' should be '(Emulation)' + Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4' + select < Exit > +These should be the default selections, so if anything else was set, run +`make distclean` to remove your old config file and start over. + +* ##### Optionally use your system toolchain (Again, not recommended) + select 'General Setup' menu + select 'Allow building with any toolchain' + select < Exit > + +* ##### Select the payload + select 'Payload' menu + select 'Add a Payload' + choose 'An Elf executable payload' + select 'Payload path and filename' + enter 'payloads/coreinfo/build/coreinfo.elf' + select < Exit > + select < Exit > + select < Yes > + +##### check your configuration (optional step): + + $ make savedefconfig + $ cat defconfig + +There should only be two lines (or 3 if you're using the system toolchain): + + CONFIG_PAYLOAD_ELF=y + CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf" + +### Step 6 - build coreboot + $ make + +At the end of the build, you should see: + + Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4) + +This means your build was successful. The output from the build is in the build +directory. build/coreboot.rom is the full rom file. + +Test the image using QEMU +------------------------- + +### Step 7 - Install QEMU + $ sudo apt-get install -y qemu + +### Step 8 - Run QEMU +Start QEMU, and point it to the ROM you just built: + + $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio + +You should see the serial output of coreboot in the original console window, and +a new window will appear running the coreinfo payload. + +Summary +------- + +### Step 1 summary - Install tools and libraries needed for coreboot +You installed the minimum additional requirements for ubuntu to download and +build coreboot. Ubuntu already has most of the other tools that would be +required installed by default. + +* `build-essential` is the basic tools for doing builds. It comes pre-installed +on some Ubuntu flavors, and not on others. +* `git` is needed to download coreboot from the coreboot git repository. +* `libncurses5-dev` is needed to build the menu for 'make menuconfig' +* `m4, bison, curl, flex, gnat-5, zlib1g-dev` are needed to build the coreboot +toolchain. + +If you started with a different distribution, you might need to install many +other items which vary by distribution. + +### Step 2 summary - Download coreboot source tree +This will download a 'read-only' copy of the coreboot tree. This just means +that if you made changes to the coreboot tree, you couldn't immediately +contribute them back to the community. To pull a copy of coreboot that would +allow you to contribute back, you would first need to sign up for an account on +gerrit. + +### Step 3 summary - Build the coreboot toolchain. +This builds one of the coreboot cross-compiler toolchains for X86 platforms. +Because of the variability of compilers and the other required tools between +the various operating systems that coreboot can be built on, coreboot supplies +and uses its own cross-compiler toolchain to build the binaries that end up as +part of the coreboot ROM. The toolchain provided by the operating system (the +'host toolchain') is used to build various tools that will run on the local +system during the build process. + +### Step 4 summary - Build the payload +To actually do anything useful with coreboot, you need to build a payload to +include in the rom. The idea behind coreboot is that it does the minimum amount +possible before passing control of the machine to a payload. There are various +payloads such as grub or SeaBIOS that are typically used to boot the operating +system. Instead, we used coreinfo, a small demonstration payload that allows the +user to look at various things such as memory and the contents of coreboot's +cbfs - the pieces that make up the coreboot rom. + +### Step 5 summary - Configure the build +This step configures coreboot's build options using the menuconfig interface to +Kconfig. Kconfig is the same configuration program used by the linux kernel. It +allows you to enable, disable, and change various values to control the coreboot +build process, including which mainboard(motherboard) to use, which toolchain to +use, and how the runtime debug console should be presented and saved. +Anytime you change mainboards in Kconfig, you should always run `make distclean` +before running `make menuconfig`. Due to the way that Kconfig works, values will +be kept from the previous mainboard if you skip the clean step. This leads to a +hybrid configuration which may or may not work as expected. + +### Step 6 summary - Build coreboot +You may notice that a number of other pieces are downloaded at the beginning of +the build process. These are the git submodules used in various coreboot builds. +By default, the BLOBS submodule is not downloaded. This git submodule may be +required for other builds for microcode or other binaries. To enable downloading +this submodule, select the option "Allow use of binary-only repository" in the +"General Setup" menu of Kconfig +This attempts to build the coreboot rom. The rom file itself ends up in the +build directory as 'coreboot.rom'. At the end of the build process, the build +displayed the contents of the rom file. + +### Step 7 summary - Install QEMU +QEMU is a processor emulator which we can use to show coreboot + +### Step 8 summary - Run QEMU +Here's the command line broken down: +* `qemu-system-x86_64` +This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to +ISA bridge. +* `-bios build/coreboot.rom` +Use the bios rom image that we just built. If this is left off, the standard +SeaBIOS image that comes with QEMU is used. +* `-serial stdio` +Send the serial output to the console. This allows you to view the coreboot +debug output. diff --git a/Documentation/lessons/lesson2.md b/Documentation/lessons/lesson2.md new file mode 100644 index 0000000000..ec929c8014 --- /dev/null +++ b/Documentation/lessons/lesson2.md @@ -0,0 +1,281 @@ +# coreboot Lesson 2: Submitting a patch to coreboot.org + +## Part 1: Setting up an account at coreboot.org + +If you already have an account, skip to Part 2. + +Otherwise, go to in your preferred web browser. +Select **Register** in the upper right corner. + +Select the appropriate sign-in. For example, if you have a Google account, +select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your +username for the account will be the username of the account you used to +sign-in with. (ex. your Google username). + +## Part 2a: Set up RSA Private/Public Key + +If you prefer to use an HTTP password instead, skip to Part 2b. + +For the most up-to-date instructions on how to set up SSH keys with Gerrit go to + +and follow the instructions there. Then, skip to Part 3. + +Additionally, that section of the Web site provides explanation on starting +an ssh-agent, which may be particularly helpful for those who anticipate +frequently uploading changes. + +If you instead prefer to have review.coreboot.org specific instructions, +follow the steps below. Note that this particular section may have the +most up-to-date instructions. + +If you do not have an RSA key set up on your account already (as is the case +with a newly created account), follow the instructions below; otherwise, +doing so could overwrite an existing key. + +In the upper right corner, select your name and click on **Settings**. +Select **SSH Public Keys** on the left-hand side. + +In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa". + +Make a passphrase -- remember this phrase. It will be needed whenever you use +this RSA Public Key. **Note:** You might want to use a short password, or +forego the password altogether as you will be using it very often. + +Open "id_rsa.pub", copy all contents and paste into the textbox under +"Add SSH Public Key" in the https://review.coreboot.org webpage. + +## Part 2b: Setting up an HTTP Password + +Alternatively, instead of using SSH keys, you can use an HTTP password. To do so, +after you select your name and click on **Settings** on the left-hand side, rather +than selecting **SSH Public Keys**, select **HTTP Password**. + +Click **Generate Password**. This should fill the "Password" box with a password. Copy +the password, and add the following to your $HOME/.netrc file: + + machine review.coreboot.org login YourUserNameHere password YourPasswordHere + +where YourUserNameHere is your username, and YourPasswordHere is the password you +just generated. + +## Part 3: Clone coreboot and configure it for submitting patches + +Go to the **Projects** tab in the upper left corner and select **List**. +From the dropdown menu that appears, select "coreboot". + +If you are using SSH keys, select **ssh** from the tabs under "Project coreboot" +and run the command that appears. This should prompt you for your id_rsa passphrase, +if you previously set one. + +If you are using HTTP, instead, select **http** from the tabs under "Project coreboot" +and run the command that appears + +After it finishes cloning, "cd coreboot" will take you into the local +git repository. Run "make gitconfig" to set up the hooks and configurations. +For example, you will be asked to run the following commands to set your +username and email. + + git config --global user.name "Your Name" + git config --global user.email "Your Email" + +## Part 4: Submit a commit + +An easy first commit to make is fixing existing checkpatch errors and warnings +in the source files. To see errors that are already present, build the files in +the repository by running 'make lint' in the coreboot directory. Alternatively, +if you want to run 'make lint' on a specific directory, run: + + for file in $(git ls-files | grep src/amd/quadcore); do \ + util/lint/checkpatch.pl --file $file --terse; done + +where is the filepath of the directory (ex. src/cpu/amd/car). + +Any changes made to files under the src directory are made locally, +and can be submitted for review. + +Once you finish making your desired changes, use the command line to stage +and submit your changes. An alternative and potentially easier way to stage +and submit commits is to use git cola, a graphical user interface for git. For +instructions on how to do so, skip to Part 4b. + +## Part 4a: Using the command line to stage and submit a commit + +To use the command line to stage a commit, run + + git add + +where `filename` is the name of your file. + +To commit the change, run + + git commit -s + +**Note:** The -s adds a signed-off-by line by the committer. Your commit should be +signed off with your name and email (i.e. **Your Name** ****, based on +what you set with git config earlier). + +Running git commit first checks for any errors and warnings using lint. If +there are any, you must go back and fix them before submitting your commit. +You can do so by making the necessary changes, and then staging your commit again. + +When there are no errors or warnings, your default text editor will open. +This is where you will write your commit message. + +The first line of your commit message is your commit summary. This is a brief +one-line description of what you changed in the files using the template +below: + +: Short description +*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors* +**Note:** It is good practice to use present tense in your descriptions +and do not punctuate your summary. + +Then hit Enter. The next paragraph should be a more in-depth explanation of the +changes you've made to the files. Again, it is good practice to use present +tense. +*ex. Fix space prohibited between function name and open parenthesis, +line over 80 characters, unnecessary braces for single statement blocks, +space required before open brace errors and warnings.* + +When you have finished writing your commit message, save and exit the text +editor. You have finished committing your change. If, after submitting your +commit, you wish to make changes to it, running "git commit --amend" allows +you to take back your commit and amend it. + +When you are done with your commit, run 'git push' to push your commit to +coreboot.org. **Note:** To submit as a draft, use +'git push origin HEAD:refs/drafts/master' Submitting as a draft means that +your commit will be on coreboot.org, but is only visible to those you add +as reviewers. + +## Part 4b: Using git cola to stage and submit a commit + +If git cola is not installed on your machine, see +https://git-cola.github.io/downloads.html for download instructions. + +After making some edits to src files, rather than run "git add," run +'git cola' from the command line. You should see all of the files +edited under "Modified". + +In the textbox labeled "Commit summary" provide a brief one-line +description of what you changed in the files according to the template +below: + +: Short description +*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors* +**Note:** It is good practice to use present tense in your descriptions +and do not punctuate your short description. + +In the larger text box labeled 'Extended description...' provide a more +in-depth explanation of the changes you've made to the files. Again, it +is good practice to use present tense. +*ex. Fix space prohibited between function name and open parenthesis, +line over 80 characters, unnecessary braces for single statement blocks, +space required before open brace errors and warnings.* + +Then press Enter two times to move the cursor to below your description. +To the left of the text boxes, there is an icon with an downward arrow. +Press the arrow and select "Sign Off." Make sure that you are signing off +with your name and email (i.e. **Your Name** ****, based on what +you set with git config earlier). + +Now, review each of your changes and mark either individual changes or +an entire file as Ready to Commit by marking it as 'Staged'. To do +this, select one file from the 'Modified' list. If you only want to +submit particular changes from each file, then highlight the red and +green lines for your changes, right click and select 'Stage Selected +Lines'. Alternatively, if an entire file is ready to be committed, just +double click on the file under 'Modified' and it will be marked as +Staged. + +Once the descriptions are done and all the edits you would like to +commit have been staged, press 'Commit' on the right of the text +boxes. + +If the commit fails due to persisting errors, a text box will appear +showing the errors. You can correct these errors within 'git cola' by +right-clicking on the file in which the error occurred and selecting +'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and +'Stage' the corrected file again. It might be necessary to refresh +'git cola' in order for the file to be shown under 'Modified' again. +Note: Be sure to add any other changes that haven't already been +explained in the extended description. + +When ready, select 'Commit' again. Once all errors have been satisfied +and the commit succeeds, move to the command line and run 'git push'. +**Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master' +Submitting as a draft means that your commit will be on coreboot.org, but is +only visible to those you add as reviewers. + +## Part 5: Getting your commit reviewed + +Your commits can now be seen on review.coreboot.org if you select “My” +and click on “Changes” and can be reviewed by others. Your code will +first be reviewed by build bot (Jenkins), which will either give you a warning +or verify a successful build; if so, your commit will receive a +1. Other +users may also give your commit +1. For a commit to be merged, it needs +to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users +can give a +2. + +## Part 6 (optional): bash-git-prompt + +To help make it easier to understand the state of the git repository +without running 'git status' or 'git log', there is a way to make the +command line show the status of the repository at every point. This +is through bash-git-prompt. + +Instructions for installing this are found at: +https://github.com/magicmonty/bash-git-prompt +**Note:** Feel free to search for different versions of git prompt, +as this one is specific to bash. + +Alternatively, follow the instructions below: +Run the following two commands in the command line: + + cd + git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt --depth=1 + +**Note:** cd will change your directory to your home directory, so the +git clone command will be run there. + +Finally, open the ~/.bashrc file and append the following two lines: + + GIT_PROMPT_ONLY_IN_REPO=1 + source ~/.bash-git-prompt/gitprompt.sh + +Now, whenever you are in a git repository, it will continuously display +its state. + +There also are additional configurations that you can change depending on your +preferences. If you wish to do so, look at the "All configs for .bashrc" section +on https://github.com/magicmonty/bash-git-prompt. Listed in that section are +various lines that you can copy, uncomment and add to your .bashrc file to +change the configurations. Example configurations include avoid fetching remote +status, and supporting versions of Git older than 1.7.10. + +## Appendix: Miscellaneous Advice + +### Updating a commit after running git push: + +Suppose you would like to update a commit that has already been pushed to the +remote repository. If the commit you wish to update is the most recent +commit you have made, after making your desired changes, stage the files +(either using git add or in git cola), and amend the commit. To do so, +if you are using the command line, run "git commit --amend." If you are +using git cola, click on the gear icon located on the upper left side under +**Commit** and select **Amend Last Commit** in the drop down menu. Then, stage +the files you have changed, commit the changes, and run git push to push the +changes to the remote repository. Your change should be reflected in Gerrit as +a new patch set. + +If, however, the commit you wish to update is not the most recent commit you +have made, you will first need to checkout that commit. To do so, find the +URL of the commit on and go to that page; if +the commit is one that you previously pushed, it can be found by selecting +**My** and then **Changes** in the upper left corner. To checkout this commit, +in the upper right corner, click on **Download**, and copy the command listed +next to checkout by clicking **Copy to clipboard**. Then, run the copied +command in your coreboot repository. Now, the last commit should be the most +recent commit to that patch; to update it, make your desired changes, stage +the files, then amend and push the commit using the instructions in the above +paragraph. \ No newline at end of file diff --git a/Documentation/mainboard/hp/compaq_8200_sff.md b/Documentation/mainboard/hp/compaq_8200_sff.md index 9d6a0e7f50..3e83e25060 100644 --- a/Documentation/mainboard/hp/compaq_8200_sff.md +++ b/Documentation/mainboard/hp/compaq_8200_sff.md @@ -60,19 +60,19 @@ as otherwise there's not enough space near the flash. ## Technology ```eval_rst -+------------------+--------------------------------------+ -| Northbridge | Sandy Bridge | -+------------------+--------------------------------------+ -| Southbridge | bd82x6x | -+------------------+--------------------------------------+ -| CPU | model_206ax | -+------------------+--------------------------------------+ -| SuperIO | :doc:`../../superio/nuvoton/npcd378` | -+------------------+--------------------------------------+ -| EC | | -+------------------+--------------------------------------+ -| Coprocessor | Intel ME | -+------------------+--------------------------------------+ ++------------------+--------------------------------------------------+ +| Northbridge | :doc:`../../northbridge/intel/sandybridge/index` | ++------------------+--------------------------------------------------+ +| Southbridge | bd82x6x | ++------------------+--------------------------------------------------+ +| CPU | model_206ax | ++------------------+--------------------------------------------------+ +| SuperIO | :doc:`../../superio/nuvoton/npcd378` | ++------------------+--------------------------------------------------+ +| EC | | ++------------------+--------------------------------------------------+ +| Coprocessor | Intel ME | ++------------------+--------------------------------------------------+ ``` [Compaq 8200 Elite SFF]: https://support.hp.com/us-en/document/c03414707 diff --git a/Documentation/northbridge/index.md b/Documentation/northbridge/index.md new file mode 100644 index 0000000000..79700785af --- /dev/null +++ b/Documentation/northbridge/index.md @@ -0,0 +1,7 @@ +# Northbridge-specific documentation + +This section contains documentation about coreboot on specific northbridges. + +## Vendor + +- [Intel](intel/index.md) diff --git a/Documentation/northbridge/intel/index.md b/Documentation/northbridge/intel/index.md new file mode 100644 index 0000000000..6cca1daf7a --- /dev/null +++ b/Documentation/northbridge/intel/index.md @@ -0,0 +1,7 @@ +# Intel Northbridge-specific documentation + +This section contains documentation about coreboot on specific Intel Northbridges. + +## Platforms + +- [Sandy Bridge](sandybridge/index.md) diff --git a/Documentation/northbridge/intel/sandybridge/index.md b/Documentation/northbridge/intel/sandybridge/index.md new file mode 100644 index 0000000000..815abcefb5 --- /dev/null +++ b/Documentation/northbridge/intel/sandybridge/index.md @@ -0,0 +1,7 @@ +# Intel Sandy Bridge-specific documentation + +This section contains documentation about coreboot on specific Intel "Sandy Bridge" northbridge. + +## Topics + +- [Native Ram Initialization](nri.md) diff --git a/Documentation/northbridge/intel/sandybridge/nri.md b/Documentation/northbridge/intel/sandybridge/nri.md new file mode 100644 index 0000000000..1b07ba48eb --- /dev/null +++ b/Documentation/northbridge/intel/sandybridge/nri.md @@ -0,0 +1,135 @@ +# Sandy Bridge Raminit + +## Introduction + +This documentation is intended to document the closed source memory controller +hardware for Intel 2nd Gen (Sandy Bride) and 3rd Gen (Ivy Bridge) core-i CPUs. + +The memory initialization code has to take care of lots of duties: +1. Selection of operating frequency +* Selection of common timings +* Applying frequency specific compensation values +* Read training of all populated channels +* Write training of all populated channels +* Adjusting delay networks of address and command signals +* DQS training of all populated channels +* Programming memory map +* Report DRAM configuration +* Error handling + +## Definitions +```eval_rst ++---------+-------------------------------------------------------------------+------------+--------------+ +| Symbol | Description | Units | Valid region | ++=========+===================================================================+============+==============+ +| SCK | DRAM system clock cycle time | s | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| tCK | DRAM system clock cycle time | 1/256th ns | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| DCK | Data clock cycle time: The time between two SCK clock edges | s | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) | ++---------+-------------------------------------------------------------------+------------+--------------+ +| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| REFCK | Reference clock, either 100 or 133 | Mhz | 100, 133 | ++---------+-------------------------------------------------------------------+------------+--------------+ +| MULT | DRAM PLL multiplier | | [3-12] | ++---------+-------------------------------------------------------------------+------------+--------------+ +| XMP | Extreme Memory Profiles | | | ++---------+-------------------------------------------------------------------+------------+--------------+ +``` + +## (Inoffical) register documentation +- [Sandy Bride - Register documentation](nri_registers.md) + +## Frequency selection +- [Sandy Bride - Frequency selection](nri_freq.md) + +## Read training +- [Sandy Bride - Read training](nri_read.md) + +### SMBIOS type 17 +The SMBIOS specification allows to report the memory configuration in use. +On GNU/Linux you can run `# dmidecode -t 17` to view it. +Example output of dmidecode: + +``` +Handle 0x0045, DMI type 17, 34 bytes + Memory Device + Array Handle: 0x0042 + Error Information Handle: Not Provided + Total Width: 64 bits + Data Width: 64 bits + Size: 8192 MB + Form Factor: DIMM + Set: None + Locator: ChannelB-DIMM0 + Bank Locator: BANK 2 + Type: DDR3 + Type Detail: Synchronous + Speed: 933 MHz + Manufacturer: 0420 + Serial Number: 00000000 + Asset Tag: 9876543210 + Part Number: F3-1866C9-8GSR + Rank: 2 + Configured Clock Speed: 933 MHz +``` +The memory frequency printed by dmidecode is the active memory frequency. It's +**not** the double datarate and it's **not** the one encoded maximum frequency +in each DIMM's SPD. + +> **Note:** This feature is available since coreboot 4.4 + +### MRC cache +The name *MRC cache* might be missleading as in case of *Native ram init* +there's no MRC, but for historical reasons it's still named *MRC cache*. +The MRC cache is part of flash memory that is writeable by coreboot. +At the end of the boot process coreboot will write the RAM training results to +flash for future use, as RAM training is time intensive. Storing the results +allows to boot faster on normal boot and allows to support S3 resume, +as the RAM training results can't be stored in RAM (you need to configure +the memory controller first to access RAM). + +The MRC cache needs to be invalidated in case the memory configuration has +been changed. To detect a changed memory configuration the CRC16 of each DIMM +is stored to MRC cache. +> **Note:** This feature is available since coreboot 4.4 + +### Error handling +As of writing the only supported error handling is to disable the failing +channel and restart the memory training sequence. It's very likely to succeed, +as memory channels operate independent of each other. +In case no DIMM could be initilized coreboot will halt. The screen will stay +black until you power of your device. On some platforms there's additional +feedback to indicate such an event. + +If you find `dmidecode -t 17` to report only half of the memory installed, +it's likely that a fatal memory init failure had happened. +It is assumed, that a working board with less physical memory, is much better, +than a board that doesn't boot at all. + +> **Note:** This feature is available since coreboot 4.5 + +Try to swap memory modules and or try to use a different vendor. If nothing +helps you could have a look at capter [Debuggin] or report a ticket +at [ticket.coreboot.org]. Please provide a full RAM init log, +that has been captured using EHCI debug. + +To enable extensive RAM training logging enable the Kconfig option +`DEBUG_RAM_SETUP` +#### Lenovo Thinkpads +Lenovo Thinkpads do have an additional feature to indicate that RAM init has +failed and coreboot has died (it calls die() on fatal error, thus the name). +The Kconfig options +`H8_BEEP_ON_DEATH` +`H8_FLASH_LEDS_ON_DEATH` +enable blinking LEDs and enable a beep to indicate death. + +> **Note:** This feature is available since coreboot 4.7 + +## Debugging +It's recommended to use an external debugger, such as serial or EHCI debug +dongle. In case of failing memory init the board might not boot at all, +preventing you from using CBMEM. diff --git a/Documentation/northbridge/intel/sandybridge/nri_freq.md b/Documentation/northbridge/intel/sandybridge/nri_freq.md new file mode 100644 index 0000000000..d8b73b3aec --- /dev/null +++ b/Documentation/northbridge/intel/sandybridge/nri_freq.md @@ -0,0 +1,165 @@ +# Frequency selection + +## Introduction +This chapter explains the frequency selection done on Sandybride and Ivybridge. + +## Definitions +```eval_rst ++---------+-------------------------------------------------------------------+------------+--------------+ +| Symbol | Description | Units | Valid region | ++=========+===================================================================+============+==============+ +| SCK | DRAM system clock cycle time | s | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| tCK | DRAM system clock cycle time | 1/256th ns | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| DCK | Data clock cycle time: The time between two SCK clock edges | s | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 | ++---------+-------------------------------------------------------------------+------------+--------------+ +| MULT | DRAM PLL multiplier | | [3-12] | ++---------+-------------------------------------------------------------------+------------+--------------+ +| XMP | Extreme Memory Profiles | | | ++---------+-------------------------------------------------------------------+------------+--------------+ +``` +## SPD +The [SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect") +located on every DIMM is factory program with various timings. One of them +specifies the maximum clock frequency the DIMM should be used with. The +operating frequency is stores as fixed point value (tCK), rounded to the next +smallest supported operating frequency. Some +[SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect") +contains additional and optional +[XMP](https://de.wikipedia.org/wiki/Extreme_Memory_Profile "Extreme Memory Profile") +data, that stores so called "performance" modes, that advertises higher clock +frequencies. + +## XMP profiles +At time of writing coreboot's raminit is able to parse XMP profile 1 and 2. +Only **XMP profile 1** is being used in case it advertises: +* 1.5V operating voltage +* The channel's installed DIMM count doesn't exceed the XMP coded limit + +In case the XMP profile doesn't fullfill those limits, the regular SPD will be +used. +> **Note:** XMP Profiles are supported since coreboot 4.4. + +It is possible to ignore the max DIMM count limit set by XMP profiles. +By activating Kconfig option `NATIVE_RAMINIT_IGNORE_XMP_MAX_DIMMS` it is +possible to install two DIMMs per channel, even if XMP tells you not to do. + +> **Note:** Ignoring XMP Profiles limit is supported since coreboot 4.7. + +## Soft fuses +Every board manufacturer does program "soft" fuses to indicate the maximum +DRAM frequency supported. However, those fuses don't set a limit in hardware +and thus are called "soft" fuses, as it is possible to ignore them. + +> **Note:** Ignoring the fuses might cause system instability ! + +On Sandy Bride *CAPID0_A* is being read, and on Ivybridge *CAPID0_B* is being +read. coreboot reads those registers and honors the limit in case the Kconfig +option `CONFIG_NATIVE_RAMINIT_IGNORE_MAX_MEM_FUSES` wasn't set. +Power users that want to let their RAM run at DRAM's "stock" frequency need to +enable the Kconfig symbol. + +It is possible to override the soft fuses limit by using a board-specific +[devicetree](#devicetree) setting. + +> **Note:** Ignoring max mem freq. fuses is supported since coreboot 4.7. + +## Hard fuses +"Hard" fuses are programmed by Intel and limit the maximum frequency that can +be used on a given CPU/board/chipset. At time of writing there's no register +to read this limit, before trying to set a given DRAM frequency. The memory PLL +won't lock, indicating that the chosen memory multiplier isn't available. In +this case coreboot tries the next smaller memory multiplier until the PLL will +lock. + +## Devicetree +The devicetree register `max_mem_clock_mhz` overrides the "soft" fuses set +by the board manufacturer. + +By using this register it's possible to force a minimum operating frequency. + +## Reference clock +While Sandybride supports 133 MHz reference clock (REFCK), Ivy Bridge also +supports 100 MHz reference clock. The reference clock is multiplied by the DRAM +multiplier to select the DRAM frequency (SCK) by the following formula: + + REFCK * MULT = 1 / DCK + +> **Note:** Since coreboot 4.6 Ivy Bridge supports 100MHz REFCK. + +## Sandy Bride's supported frequencies +```eval_rst ++------------+-----------+------------------+-------------------------+---------------+ +| SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment | ++============+===========+==================+=========================+===============+ +| 400 | DDR3-800 | 3 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 533 | DDR3-1066 | 4 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 666 | DDR3-1333 | 5 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 800 | DDR3-1600 | 6 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 933 | DDR3-1866 | 7 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 1066 | DDR3-2166 | 8 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +``` + +## Ivybridge's supported frequencies +```eval_rst ++------------+-----------+------------------+-------------------------+---------------+ +| SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment | ++============+===========+==================+=========================+===============+ +| 400 | DDR3-800 | 3 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 533 | DDR3-1066 | 4 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 666 | DDR3-1333 | 5 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 800 | DDR3-1600 | 6 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 933 | DDR3-1866 | 7 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 1066 | DDR3-2166 | 8 | 133 MHz | | ++------------+-----------+------------------+-------------------------+---------------+ +| 700 | DDR3-1400 | 7 | 100 MHz | '1 | ++------------+-----------+------------------+-------------------------+---------------+ +| 800 | DDR3-1600 | 8 | 100 MHz | '1 | ++------------+-----------+------------------+-------------------------+---------------+ +| 900 | DDR3-1800 | 9 | 100 MHz | '1 | ++------------+-----------+------------------+-------------------------+---------------+ +| 1000 | DDR3-2000 | 10 | 100 MHz | '1 | ++------------+-----------+------------------+-------------------------+---------------+ +| 1100 | DDR3-2200 | 11 | 100 MHz | '1 | ++------------+-----------+------------------+-------------------------+---------------+ +| 1200 | DDR3-2400 | 12 | 100 MHz | '1 | ++------------+-----------+------------------+-------------------------+---------------+ +``` +> '1: since coreboot 4.6 + +## Multiplier selection +coreboot select the maximum frequency to operate at by the following formula: +``` +if devicetree's max_mem_clock_mhz > 0: + freq_max := max_mem_clock_mhz +else: + freq_max := soft_fuse_max_mhz + +for i in SPDs: + freq_max := MIN(freq_max, ddr_spd_max_mhz[i]) +``` + +As you can see, by using DIMMs with different maximum DRAM frequencies, the +slowest DIMMs' frequency will be selected, to prevent over-clocking it. + +The selected frequency gives the PLL multiplier to operate at. In case the PLL +locks (see Take me to [Hard fuses](#hard_fuses)) the frequency will be used for +all DIMMs. At this point it's not possible to change the multiplier again, +until the system has been powered off. In case the PLL doesn't lock, the next +smaller multiplier will be used until a working multiplier will be found. diff --git a/Documentation/northbridge/intel/sandybridge/nri_read.md b/Documentation/northbridge/intel/sandybridge/nri_read.md new file mode 100644 index 0000000000..0496657b3f --- /dev/null +++ b/Documentation/northbridge/intel/sandybridge/nri_read.md @@ -0,0 +1,153 @@ +# Read training + +## Introduction + +This chapter explains the read training sequence done on Sandy Bride and +Ivy Bridge memory initialization. + +Read training is done to compensate the skew between DQS and SCK and to find +the smallest supported roundtrip delay. + +Every board does have a vendor depended routing topology, and can be equip +with any combination of DDR3 memory modules, that introduces different +skew between the memory lanes. With DDR3 a "Fly-By" routing topology +has been introduced, that makes the biggest part of DQS-SCK skew. +The memory code measures the actual skew and actives delay gates, +that will "compensate" the skew. + +When in read training the DRAM and the controller are placed in a special mode. +On every read instruction the DRAM outputs a predefined pattern and the memory +controller samples the DQS after a given delay. As the pattern is known, the +actual delay of every lane can be measured. + +The values programmed in read training effect DRAM-to-MC transfers only ! + +## Definitions +```eval_rst ++---------+-------------------------------------------------------------------+------------+--------------+ +| Symbol | Description | Units | Valid region | ++=========+===================================================================+============+==============+ +| SCK | DRAM system clock cycle time | s | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| tCK | DRAM system clock cycle time | 1/256th ns | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| DCK | Data clock cycle time: The time between two SCK clock edges | s | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) | ++---------+-------------------------------------------------------------------+------------+--------------+ +| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 | ++---------+-------------------------------------------------------------------+------------+--------------+ +| MULT | DRAM PLL multiplier | | [3-12] | ++---------+-------------------------------------------------------------------+------------+--------------+ +| XMP | Extreme Memory Profiles | | | ++---------+-------------------------------------------------------------------+------------+--------------+ +| DQS | Data Strobe signal used to sample all lane's DQ signals | | | ++---------+-------------------------------------------------------------------+------------+--------------+ +``` +## Hardware +The hardware does have delay logic blocks that can delay the DQ / DQS of a +lane/rank by one or multiple clock cylces and it does have delay logic blocks +that can delay the signal by a multiple of 1/64th DCK per lane. + +All delay values can be controlled via software by writing registers in the +MCHBAR. + +## IO phase + +The IO phase can be adjusted in [0-512) * 1/64th DCK. Incrementing it by 64 is +the same as Incrementing IO delay by 1. + +## IO delay +Delays the DQ / DQS signal by one or multiple clock cycles. + +### Roundtrip time +The roundtrip time is the time the memory controller waits for data arraving +after a read has been issued. Due to clock-domain crossings, multiple +delay instances and phase interpolators, the signal runtime to DRAM and back +to memory controller defaults to 55 DCKs. The real roundtrip time has to be +measured. + +After a read command has been issued, a counter counts down until zero has been +reached and activates the input buffers. + +The following pictures shows the relationship between those three values. +The picture was generated from 16 IO delay values times 64 timA values. +The highest IO delay was set on the right-hand side, while the last block +on the left-hand side has zero IO delay. + +#### roundtrip 55 DCKs +![timA for lane0 - lane3, roundtrip 55][timA_lane0-3_rt55] + +[timA_lane0-3_rt55]: timA_lane0-3_rt55.png + +#### roundtrip 54 DCKs +![timA for lane0 - lane3, roundtrip 54][timA_lane0-3_rt54] + +[timA_lane0-3_rt54]: timA_lane0-3_rt54.png + + +#### roundtrip 53 DCKs +![timA for lane0 - lane3, roundtrip 53][timA_lane0-3_rt53] + +[timA_lane0-3_rt53]: timA_lane0-3_rt53.png + +As you can see the signal has some jitter as every sample was taken in a +different loop iteration. The result register only contains a single bit per +lane. + +## Algorithm +### Steps +The algorithm finds the roundtrip time, IO delay and IO phase. The IO phase +will be adjusted to match the falling edge of the preamble of each lane. +The roundtrip time is adjusted to an minimal value, that still includes the +preamble. + +### Synchronize to data phase + +The first measurement done in read-leveling samples all DQS values for one +phase [0-64) * 1/64th DCK. It then searches for the middle of the low data +symbol and adjusts timA to the found phase and thus the following measurements +will be aligned to the low data symbol. +The code assumes that the initial roundtrip time causes the measurement to be +in the alternating pattern data phase. + +### Finding the preamble +After adjusting the IO phase to the middle of one data symbol the preamble will +be located. Unlike the data phase, which is an alternating pattern (010101...), +the preamble consists of two high data cycles. + +The code decrements the IO delay/RTT and samples the DQS signal with timA +untouched. As it has been positioned in the middle of the data symbol, it'll +read as either "low" or "high". + +If it's "low" we are still in the data phase. +If it's "high" we have found the preamble. + +The roundtrip time and IO delay will be adjusted until all lanes are aligned. +The resulting IO delay is visible in the picture below. + +**roundtrip time: 49 DCKs, IO delay (at blue point): 6 DCKs** +![timA for lane0 - lane3, finding minimum roundtrip time][timA_lane0-3_discover_420x] + +[timA_lane0-3_discover_420x]: timA_lane0-3_discover_420x.png + +**Note: The sampled data has been shifted by timA. The preamble is now +in phase.** + +## Fine adjustment + +As timA still points the middle of the data symbol an offset of 32 is added. +It now points the falling edge of the preamble. +The fine adjustment is to reduce errors introduced by jitter. The phase is +adjusted from `timA - 25` to `timA + 25` and the DQS signal is sampled 100 +times. The fine adjustment finds the middle of each rising edge (it's actual +the falling edge of the preamble) to get the final IO phase. You can see the +result in the picture below. + +![timA for lane0 - lane3, fine adjustment][timA_lane0-3_adjust_fine] + +[timA_lane0-3_adjust_fine]: timA_lane0-3_adjust_fine.png + +Lanes 0 - 2 will be adjusted by a phase of -10, while lane 3 is already correct. diff --git a/Documentation/northbridge/intel/sandybridge/nri_registers.md b/Documentation/northbridge/intel/sandybridge/nri_registers.md new file mode 100644 index 0000000000..601157c464 --- /dev/null +++ b/Documentation/northbridge/intel/sandybridge/nri_registers.md @@ -0,0 +1,2174 @@ +# Inoffical Documentation of Intel MCHBAR register space. + +The MCHBAR can be enabled by using register 0x48 of PCI(0:0:0) device. + +This documentation is incomplete and might be incorrect. +Please handle with care ! + +**MCHBAR + 0x4** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x10** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x14** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x18** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x1c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x20** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x24** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x28** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x2c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x204** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x210** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x214** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x218** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x21c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x220** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x224** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x228** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x22c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x404** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x410** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x414** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x418** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x41c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x420** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x424** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x428** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x42c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x604** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x610** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x614** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x618** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x61c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x620** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x624** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x628** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x62c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x804** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x810** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x814** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x818** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x81c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x820** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x824** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x828** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x82c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 4 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa04** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa10** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa14** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa18** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa1c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa20** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa24** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa28** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xa2c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 5 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc04** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc10** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc14** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 0:5| Rank 0 CLK phase shift, low | ++-----------+------------------------------------------------------------------+ +| 6:11| Rank 1 CLK phase shift, low | ++-----------+------------------------------------------------------------------+ +| 12:17| Rank 2 CLK phase shift, low | ++-----------+------------------------------------------------------------------+ +| 18:23| Rank 3 CLK phase shift, low | ++-----------+------------------------------------------------------------------+ +| 24:27| Rankmap to enable clock crossover on | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc18** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 0 | Rank 0 CLK phase shift, high | ++-----------+------------------------------------------------------------------+ +| 1 | Rank 1 CLK phase shift, high | ++-----------+------------------------------------------------------------------+ +| 2 | Rank 2 CLK phase shift, high | ++-----------+------------------------------------------------------------------+ +| 3 | Rank 3 CLK phase shift, high | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc1c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc20** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc24** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc28** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xc2c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 6 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe04** + +*Width:* 64 Bit + +*Desc:* Lane training result Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:63| Training result, each bit corresponds to one of the 64 settings | +| | of IO delay | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe10** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 0 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe14** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 1 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe18** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 2 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe1c** + +*Width:* 32 Bit + +*Desc:* Read delay settings, Rank 3 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 6:11| DQS phase shift on rising edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +| 16:18| IO delay in DCKs | ++-----------+------------------------------------------------------------------+ +| 20:25| DQS phase shift on falling edge in 1/64 DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe20** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 0 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe24** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 1 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe28** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 2 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0xe2c** + +*Width:* 24 Bit + +*Desc:* Write delay settings, Rank 3 Register, Channel 0, lane 7 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| DQ IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 8:13| DQS IO phase shift in 1/64th DCKs | ++-----------+------------------------------------------------------------------+ +| 15:17| DQS IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +| 20 | DQ IO phase shift in DCKs | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x1810** + +*Width:* 32 Bit + +*Desc:* COMP1 Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 9:11| ODT | ++-----------+------------------------------------------------------------------+ +| 21:23| CLK drive up | ++-----------+------------------------------------------------------------------+ +| 27:29| CTRL drive up | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x320c** + +*Width:* 32 Bit + +*Desc:* Command crossover enable Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:5| CLK phase, low | ++-----------+------------------------------------------------------------------+ +| 12 | CLK phase, high | ++-----------+------------------------------------------------------------------+ +| 14 | Enable hardware | ++-----------+------------------------------------------------------------------+ +| 17 | Enable on slot 1 | ++-----------+------------------------------------------------------------------+ +| 27 | Enable on slot 2 | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x3714** + +*Width:* 32 Bit + +*Desc:* COMP2 Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:31| COMP2 value | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4000** + +*Width:* 24 Bit + +*Desc:* TC_DBP - Timing of DDR - Bin Parameter Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:3| tRCD | ++-----------+------------------------------------------------------------------+ +| 4:7| tRP | ++-----------+------------------------------------------------------------------+ +| 8:11| CAS | ++-----------+------------------------------------------------------------------+ +| 12:15| CWL | ++-----------+------------------------------------------------------------------+ +| 16:19| tRAS | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4004** + +*Width:* 32 Bit + +*Desc:* TC_RAP - Timing of DDR - Regular Access Parameters Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:3| tRRD | ++-----------+------------------------------------------------------------------+ +| 4:7| tRTP | ++-----------+------------------------------------------------------------------+ +| 8:11| CKE | ++-----------+------------------------------------------------------------------+ +| 12:15| WTR | ++-----------+------------------------------------------------------------------+ +| 16:19| tFAW | ++-----------+------------------------------------------------------------------+ +| 24:27| tWR | ++-----------+------------------------------------------------------------------+ +| 29 | Command 3-state options | +| | - 0: Drive when channel is active, tri-state when inactive, | +| | - 1: Always drive command bus | ++-----------+------------------------------------------------------------------+ +| 30:31| CMD stretch, | +| | - 00b: 1N, | +| | - 10b: 2N, | +| | - 11b: 3N | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x400c** + +*Width:* 24 Bit + +*Desc:* OTHP ODT control Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:3| tXPDLL ? | ++-----------+------------------------------------------------------------------+ +| 5:7| tXP ? | ++-----------+------------------------------------------------------------------+ +| 16:17| ODT stretch | ++-----------+------------------------------------------------------------------+ +| 18:19| ODT stretch | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x401c** + +*Width:* 16 Bit + +*Desc:* OTHP Workaround (SandyBridge only) Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 12:13| ODT stretch | ++-----------+------------------------------------------------------------------+ +| 14:15| ODT stretch | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4024** + +*Width:* 32 Bit + +*Desc:* Rounttrip time Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:7| RTT Rank 0 DIMM 0 | ++-----------+------------------------------------------------------------------+ +| 8:15| RTT Rank 1 DIMM 0 | ++-----------+------------------------------------------------------------------+ +| 16:23| RTT Rank 0 DIMM 1 | ++-----------+------------------------------------------------------------------+ +| 24:31| RTT Rank 1 DIMM 1 | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4028** + +*Width:* 24 Bit + +*Desc:* SC_IO_LATENCY Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:3| IO latency Rank 0 DIMM 0 | ++-----------+------------------------------------------------------------------+ +| 4:7| IO latency Rank 1 DIMM 0 | ++-----------+------------------------------------------------------------------+ +| 8:11| IO latency Rank 0 DIMM 1 | ++-----------+------------------------------------------------------------------+ +| 12:15| IO latency Rank 1 DIMM 1 | ++-----------+------------------------------------------------------------------+ +| 16:21| Rount trip - I/O compensation | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4200** + +*Width:* 32 Bit + +*Desc:* RAM training queue, address Register, Channel 0, queue idx 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:15| Address | ++-----------+------------------------------------------------------------------+ +| 20:22| Bank address | ++-----------+------------------------------------------------------------------+ +| 24:25| Slotrank | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4204** + +*Width:* 32 Bit + +*Desc:* RAM training queue, address Register, Channel 0, queue idx 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:15| Address | ++-----------+------------------------------------------------------------------+ +| 20:22| Bank address | ++-----------+------------------------------------------------------------------+ +| 24:25| Slotrank | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4208** + +*Width:* 32 Bit + +*Desc:* RAM training queue, address Register, Channel 0, queue idx 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:15| Address | ++-----------+------------------------------------------------------------------+ +| 20:22| Bank address | ++-----------+------------------------------------------------------------------+ +| 24:25| Slotrank | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x420c** + +*Width:* 32 Bit + +*Desc:* RAM training queue, address Register, Channel 0, queue idx 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:15| Address | ++-----------+------------------------------------------------------------------+ +| 20:22| Bank address | ++-----------+------------------------------------------------------------------+ +| 24:25| Slotrank | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4220** + +*Width:* 8 Bit + +*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0 | !RAS | ++-----------+------------------------------------------------------------------+ +| 1 | !CAS | ++-----------+------------------------------------------------------------------+ +| 2 | !WE | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4224** + +*Width:* 8 Bit + +*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0 | !RAS | ++-----------+------------------------------------------------------------------+ +| 1 | !CAS | ++-----------+------------------------------------------------------------------+ +| 2 | !WE | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4228** + +*Width:* 8 Bit + +*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0 | !RAS | ++-----------+------------------------------------------------------------------+ +| 1 | !CAS | ++-----------+------------------------------------------------------------------+ +| 2 | !WE | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x422c** + +*Width:* 8 Bit + +*Desc:* RAM training queue, command IO Register, Channel 0, queue idx 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0 | !RAS | ++-----------+------------------------------------------------------------------+ +| 1 | !CAS | ++-----------+------------------------------------------------------------------+ +| 2 | !WE | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4230** + +*Width:* 32 Bit + +*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 16:31| Clock cycles to wait after command | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4234** + +*Width:* 32 Bit + +*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 1 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 16:31| Clock cycles to wait after command | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4238** + +*Width:* 32 Bit + +*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 2 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 16:31| Clock cycles to wait after command | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x423c** + +*Width:* 32 Bit + +*Desc:* RAM training queue, cooldown Register, Channel 0, queue idx 3 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 16:31| Clock cycles to wait after command | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4284** + +*Width:* 24 Bit + +*Desc:* RAM training queue, cooldown Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0 | Start executing DRAM command queue | ++-----------+------------------------------------------------------------------+ +| 16:19| (Number of queued commands - 1) * 4 | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4298** + +*Width:* 40 Bit + +*Desc:* TC - Refresh parameters Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:15| tREFI, average period between refresh in DCLK cycles | ++-----------+------------------------------------------------------------------+ +| 16:24| tRFC, Time of refresh, from beginning of refresh until next ACT | +| | or refresh is allowed in DCLK cycles | ++-----------+------------------------------------------------------------------+ +| 25:32| tREFIx9, Maximum time allowed between refreshes to a rank. | +| | Should be programmed to 8.9 * tREFI / 1024 | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x42a4** + +*Width:* 32 Bit + +*Desc:* SRFTP Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:11| tXSDLL | ++-----------+------------------------------------------------------------------+ +| 12:15| tXS_offset | ++-----------+------------------------------------------------------------------+ +| 16:25| tZQOPER | ++-----------+------------------------------------------------------------------+ +| 28:31| tMOD | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4c20** + +*Width:* 32 Bit + +*Desc:* Scheduler parameters Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:31| scheduler parameters | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4cb0** + +*Width:* 16 Bit + +*Desc:* PM - Power-down configuration, Broadcast Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:7| PDWN_idle_counter, This defines the rank indle period in DCLK | +| | cycles that causes power-down entrance. The minimum value | +| | should be greater then or equal to the worst roundtrip time | +| | plus burst length. | ++-----------+------------------------------------------------------------------+ +| 8:10| PDWN_mode, selects the mode of power-down: | +| | - 0x0: No power down, | +| | - 0x1: APD, | +| | - 0x2: PPD, | +| | - 0x3: APD+PPD, | +| | - 0x4: Reserved, | +| | - 0x5: Reserved, | +| | - 0x6: PPD-DLLoff, | +| | - 0x7: APD+PPD+DLLof | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4e80** + +*Width:* 32 Bit + +*Desc:* Power mode preset Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:31| Power mode preset | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4e94** + +*Width:* 16 Bit + +*Desc:* TC - Refresh parameters Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:7| OREF_RI, Rank idle period that defines an oppertunity for | +| | refresh | ++-----------+------------------------------------------------------------------+ +| 8:11| Refresh_HP_WM, tREFI count level that turns the refresh | +| | priority to high | ++-----------+------------------------------------------------------------------+ +| 12:15| Refresh_panic_WM, tREFI count level in which the refresh | +| | priority is panic | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x4e98** + +*Width:* 40 Bit + +*Desc:* TC - Refresh parameters Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:15| tREFI, average period between refresh in DCLK cycles | ++-----------+------------------------------------------------------------------+ +| 16:24| tRFC, Time of refresh, from beginning of refresh until next ACT | +| | or refresh is allowed in DCLK cycles | ++-----------+------------------------------------------------------------------+ +| 25:32| tREFIx9, Maximum time allowed between refreshes to a rank. | +| | Should be programmed to 8.9 * tREFI / 1024 | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5000** + +*Width:* 8 Bit + +*Desc:* Global channel size control Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:1| CH_A, defines the largest channel. | +| | - 00b: Channel 0, | +| | - 01b: Channel 1, | +| | - 10b: Channel 2 | ++-----------+------------------------------------------------------------------+ +| 2:3| CH_B, defines the mid-size channel. | +| | - 00b: Channel 0, | +| | - 01b: Channel 1, | +| | - 10b: Channel 2 | ++-----------+------------------------------------------------------------------+ +| 2:3| CH_C, defines the smallest channel. | +| | - 00b: Channel 0, | +| | - 01b: Channel 1, | +| | - 10b: Channel 2, CH_C is 10 if only 2 channels are supported | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5004** + +*Width:* 32 Bit + +*Desc:* Address Decode Register, Channel 0 + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:7| DIMMA size in 256 MB multiples | ++-----------+------------------------------------------------------------------+ +| 16 | DIMM A select (DAS) Slot to DIMM mapping, | +| | - 0: DIMMA, DIMMB, | +| | - 1: DIMMB, DIMMA | ++-----------+------------------------------------------------------------------+ +| 17 | DIMM A number of ranks | ++-----------+------------------------------------------------------------------+ +| 19 | DIMM A DRAM width x8 / x16 | ++-----------+------------------------------------------------------------------+ +| 8:15| DIMM B size in 256 MB multiples | ++-----------+------------------------------------------------------------------+ +| 18 | DIMM B number of ranks | ++-----------+------------------------------------------------------------------+ +| 20 | DIMM B DRAM width in 8x / x16 | ++-----------+------------------------------------------------------------------+ +| 21 | Rank interleave enable | ++-----------+------------------------------------------------------------------+ +| 22 | Enhanced interleave enable | ++-----------+------------------------------------------------------------------+ +| 26 | High order Rank interleave enable | ++-----------+------------------------------------------------------------------+ +| 27:29| High Order Rank interleave Address. Selects on of address bits | +| | 20-27 to use for high rank interleave | ++-----------+------------------------------------------------------------------+ +| 24:25| ECC, | +| | - 00b: No ECC active, | +| | - 01b: ECC is active on IO, | +| | - 11b: ECC is active on both IO and ECC logic | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5030** + +*Width:* 8 Bit + +*Desc:* Global DDR3 control Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 1 | DDR reset | ++-----------+------------------------------------------------------------------+ +| 2 | DCLK enable | ++-----------+------------------------------------------------------------------+ +| 5 | IO reset | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5034** + +*Width:* 32 Bit + +*Desc:* Version Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:31| MRC version | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5060** + +*Width:* 16 Bit + +*Desc:* PM - Self refresh config Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:15| Idle_timer, The value is used when the SREF_enable field is set | +| | and defines the # of cycles that there should not be any | +| | transaction in order to enter self-refresh. | ++-----------+------------------------------------------------------------------+ +| 16 | SR_Enable, enable self-refresh mechanism. Clear SREF_en and | +| | SREF_exit first. | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5084** + +*Width:* 24 Bit + +*Desc:* RCOMP status Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 16 | Busy | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5090** + +*Width:* 32 Bit + +*Desc:* ECC - Address compare for ECC error injection Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:31| Inject error when ECC_Inj_Addr_Compare[31:0] = ADDR[37:6] | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5094** + +*Width:* 32 Bit + +*Desc:* ECC - Address mask for ECC error injection Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:31| Inject error when ECC_inj_Addr_Compare[31:0] = | +| | ADDR[37:6] && ECC_Inj_Addr_Mask[31:0] | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5e00** + +*Width:* 32 Bit + +*Desc:* MC_BIOS_REQ Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:7| Selected multiplier: 100Mhz [7,12], 133Mhz [3,19] | ++-----------+------------------------------------------------------------------+ +| 8 | - 1: 100Mhz reference clock | +| | - 0: 133Mhz reference clock (IvyBridge only) | ++-----------+------------------------------------------------------------------+ +| 31 | PLL busy | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5e04** + +*Width:* 8 Bit + +*Desc:* MC_BIOS_DATA Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 0:7| Active multiplier: | +| | - 100Mhz [7,12], | +| | - 133Mhz [3,19] | ++-----------+------------------------------------------------------------------+ +``` + +**MCHBAR + 0x5f08** + +*Width:* 16 Bit + +*Desc:* RCOMP control Register + +```eval_rst ++-----------+------------------------------------------------------------------+ +| Bit | Description | ++===========+==================================================================+ +| 8 | Force RCOMP | ++-----------+------------------------------------------------------------------+ diff --git a/Documentation/northbridge/intel/sandybridge/timA_lane0-3_adjust_fine.png b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_adjust_fine.png new file mode 100644 index 0000000000..d72e4c6d84 Binary files /dev/null and b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_adjust_fine.png differ diff --git a/Documentation/northbridge/intel/sandybridge/timA_lane0-3_discover_420x.png b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_discover_420x.png new file mode 100644 index 0000000000..6f33217d1e Binary files /dev/null and b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_discover_420x.png differ diff --git a/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt53.png b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt53.png new file mode 100644 index 0000000000..191e792845 Binary files /dev/null and b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt53.png differ diff --git a/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt54.png b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt54.png new file mode 100644 index 0000000000..fa7f6089d0 Binary files /dev/null and b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt54.png differ diff --git a/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt55.png b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt55.png new file mode 100644 index 0000000000..7f2fa397dd Binary files /dev/null and b/Documentation/northbridge/intel/sandybridge/timA_lane0-3_rt55.png differ diff --git a/Documentation/soc/index.md b/Documentation/soc/index.md new file mode 100644 index 0000000000..ca50dc85fb --- /dev/null +++ b/Documentation/soc/index.md @@ -0,0 +1,7 @@ +# SOC-specific documentation + +This section contains documentation about coreboot on specific SOCs. + +## Vendor + +- [Intel](intel/index.md) diff --git a/Documentation/soc/intel/icelake/MultiProcessorInit.md b/Documentation/soc/intel/icelake/MultiProcessorInit.md new file mode 100644 index 0000000000..ab0b5135ed --- /dev/null +++ b/Documentation/soc/intel/icelake/MultiProcessorInit.md @@ -0,0 +1,85 @@ +# Intel Common Code Block Publishing EFI_MP_SERVICES_PPI + +## Introduction + +This documentation is intended to document the purpose for creating EFI service +Interface inside coreboot space to perform CPU feature programming on Application +Processors for Intel 9th Gen (Cannon Lake) and beyond CPUs. + +Today coreboot is capable enough to handle multi-processor initialization on IA platforms. + +The multi-processor initialization code has to take care of lots of duties: + +1. Bringing all cores out of reset +2. Load latest microcode on all cores +3. Sync latest MTRR snapshot between BSP and APs +4. Perform sets of CPU feature programming + * CPU Power & Thermal Management + * Overclocking + * Intel Trusted Execution Technology + * Intel Software Guard Extensions + * Intel Processor Trace etc. + +This above CPU feature programming lists are expected to grow with current and future +CPU complexity and there might be some cases where certain feature programming mightbe +closed source in nature. + +Platform code might need to compromise on those closed source nature of CPU programming +if we don't plan to provide an alternate interface which can be used by coreboot to +get-rid of such close source CPU programming. + +## Proposal + +As coreboot is doing CPU multi-processor initialization for IA platform before FSP-S +initialization and having all possible information about cores in terms of maximum number +of cores, APIC ids, stack size etc. It’s also possible for coreboot to extend its own +support model and create a sets of APIs which later can be used by FSP to run CPU feature +programming using coreboot published APIs. + +Due to the fact that FSP is using EFI infrastructure and need to relying on install/locate +PPI to perform certain API call, hence coreboot has to created MP services APIs known as +EFI_MP_SERVICES_PPI as per PI specification volume 1, section 8.3.9. +More details here: [PI_Spec_1_6] + +### coreboot to publish EFI_MP_SERVICES_PPI APIs + +```eval_rst ++------------------------------+------------------------------------------------------------------+ +| API | Description | ++==============================+==================================================================+ +| PeiGetNumberOfProcessors | Get the number of CPU's. | ++------------------------------+------------------------------------------------------------------+ +| PeiGetProcessorInfo | Get information on a specific CPU. | ++------------------------------+------------------------------------------------------------------+ +| PeiStartupAllAPs | Activate all of the application processors. | ++------------------------------+------------------------------------------------------------------+ +| PeiStartupThisAP | Activate a specific application processor. | ++------------------------------+------------------------------------------------------------------+ +| PeiSwitchBSP | Switch the boot strap processor. | ++------------------------------+------------------------------------------------------------------+ +| PeiEnableDisableAP | Enable or disable an application processor. | ++------------------------------+------------------------------------------------------------------+ +| PeiWhoAmI | Identify the currently executing processor. | ++------------------------------+------------------------------------------------------------------+ +``` + +## Code Flow + +Here is proposed design flow with coreboot has implemented EFI_MP_SERVICES_PPI API and FSP will make +use of the same to perform some CPU feature programming. + +**coreboot-FSP MP init flow** +![coreboot-fsp mp init flow][coreboot_publish_mp_service_api] + +[coreboot_publish_mp_service_api]: coreboot_publish_mp_service_api.png + +## Benefits +1. coreboot was using SkipMpInit=1 which will skip entire FSP CPU feature programming. +With proposed model, coreboot will make use of SkipMpInit=0 which will allow to run all +Silicon recommended CPU programming. +2. CPU feature programming inside FSP will be more transparent than before as it’s using +coreboot interfaces to execute those programming. +3. coreboot will have more control over running those feature programming as API optimization +handled by coreboot. + +[PI_Spec_1_6]: http://www.uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf diff --git a/Documentation/soc/intel/icelake/coreboot_publish_mp_service_api.png b/Documentation/soc/intel/icelake/coreboot_publish_mp_service_api.png new file mode 100644 index 0000000000..5836140c53 Binary files /dev/null and b/Documentation/soc/intel/icelake/coreboot_publish_mp_service_api.png differ diff --git a/Documentation/soc/intel/icelake/index.md b/Documentation/soc/intel/icelake/index.md new file mode 100644 index 0000000000..b4f512ca05 --- /dev/null +++ b/Documentation/soc/intel/icelake/index.md @@ -0,0 +1,7 @@ +# Intel Ice Lake SOC-specific documentation + +This section contains documentation about coreboot on specific Intel "Ice Lake" SOCs. + +## Multiprocessor Init + +- [Multiprocessor Init](MultiProcessorInit.md) diff --git a/Documentation/soc/intel/index.md b/Documentation/soc/intel/index.md new file mode 100644 index 0000000000..5ac5125cfc --- /dev/null +++ b/Documentation/soc/intel/index.md @@ -0,0 +1,7 @@ +# Intel SOC-specific documentation + +This section contains documentation about coreboot on specific Intel SOCs. + +## Platforms + +- [Ice Lake/9th Gen Core-i series](icelake/index.md) diff --git a/Documentation/submodules.md b/Documentation/submodules.md deleted file mode 100644 index 631e351303..0000000000 --- a/Documentation/submodules.md +++ /dev/null @@ -1,46 +0,0 @@ -Use of git submodules in coreboot -================================= -coreboot uses git submodules to keep certain parts of the tree separate, -with two major use cases: - -First, we use a vendor tool by NVIDIA for systems based on their SoC -and since they publish it through git, we can just import it into our -tree using submodules. - -Second, lots of boards these days require binaries and we want to keep -them separate from coreboot proper to clearly delineate shiny Open Source -from ugly blobs. -Since we don't want to impose blobs on users who really don't need them, -that repository is only downloaded and checked out on explicit request. - -Handling submodules -------------------- -For the most part, submodules should be automatically checked out on the -first execution of the coreboot Makefile. - -To manually fetch all repositories (eg. when you want to prepare the tree -for archiving, or to use it without network access), run - - $ git submodule update --init --checkout - -This also checks out the binaries below `3rdparty/` - -Mirroring coreboot ------------------- -When running a coreboot mirror to checkout from, for full operation, you -should also mirror the blobs and nvidia-cbootimage repository, and place -them in the same directory as the coreboot repository mirror. - -That is, when residing in coreboot's repository, `cd ../blobs.git` -should move you to the blobs repository. - -With that, no matter what the URL of your coreboot repository is, the -git client (of a sufficiently new version) is able to pick up the other -repositories transparently. - -Minimum requirements --------------------- -git needs to be able to handle relative paths to submodule repositories, -and it needs to know about non-automatic submodules. - -For these features, we require git version 1.7.6.1 or newer. -- cgit v1.2.3