Documentation: x86 add sleep state and minimal memory setup

Document how to add the sleep state and minimal memory setup.

TEST=None

Change-Id: Ibebeef34269dbf2366f1bea6d734f6bade4e4028
Signed-off-by: Lee Leahy <leroy.p.leahy@intel.com>
Reviewed-on: https://review.coreboot.org/13446
Tested-by: build bot (Jenkins)
Reviewed-by: Martin Roth <martinroth@google.com>

3 files changed, 190 insertions, 0 deletions

diff --git a/Documentation/Intel/Board/board.html b/Documentation/Intel/Board/board.html
index d50ff4e74f..47d329515d 100644
--- a/Documentation/Intel/Board/board.html
+++ b/Documentation/Intel/Board/board.html
@@ -15,6 +15,7 @@
 <ol>
   <li><a href="#RequiredFiles">Required Files</a></li>
   <li>Enable <a href="#SerialOutput">Serial Output</a></li>
+  <li>Load the <a href="#SpdData">Memory Timing Data</a></li>
 </ol>
 
 
@@ -101,6 +102,84 @@
 </ol>
 
 
+<hr>
+<h1><a name="SpdData">Memory Timing Data</a></h1>
+<p>
+  Memory timing data is located in the flash.  This data is in the format of
+  <a target="_blank" href="https://en.wikipedia.org/wiki/Serial_presence_detect">serial presence detect</a>
+  (SPD) data.
+  Use the following steps to load the SPD data:
+</p>
+<ol>
+  <li>Edit Kconfig to add the DISPLAY_SPD_DATA" value which enables the
+    display of the SPD data being passed to MemoryInit
+  </li>
+  <li>Create an "spd" subdirectory</li>
+  <li>Create an spd/spd.c file for the SPD implementation
+    <ol type="A">
+      <li>Implement the mainboard_fill_spd_data routine
+        <ol type="i">
+          <li>Read the SPD data either from the spd.bin file or using I2C or SMBUS</li>
+          <li>Fill in the pei_data structure with SPD data for each of the DIMMs</li>
+          <li>Set the DIMM channel configuration</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li>Add an .spd.hex file containing the memory timing data to the spd subdirectory</li>
+  <li>Create spd/Makefile.inc
+    <ol type="A">
+      <li>Add spd.c to romstage</li>
+      <li>Add the .spd.hex file to SPD_SOURCES</li>
+    </ol>
+  </li>
+  <li>Edit Makefile.inc to add the spd subdirectory</li>
+  <li>Edit romstage.c
+    <ol type="A">
+      <li>Call mainboard_fill_spd_data</li>
+      <li>Add mainboard_memory_init_params to copy the SPD and DRAM
+        configuration data from the pei_data structure into the UPDs
+        for MemoryInit
+      </li>
+    </ol>
+  </li>
+  <li>Edit devicetree.cb
+    <ol type="A">
+      <li>Include the UPD parameters for MemoryInit except for:
+        <ul>
+          <li>Address of SPD data</li>
+          <li>DRAM configuration set above</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>A working FSP
+    <a target="_blank" href="../fsp1_1.html#MemoryInit">MemoryInit</a>
+    routine is required to complete debugging</li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x34:
+        - Just after entering
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
+      </li>
+      <li>0x36:
+        - Just before displaying the
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l106">UPD parameters</a>
+        for FSP MemoryInit
+      </li>
+      <li>0x92: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l219">POST_FSP_MEMORY_INIT</a>
+        - Just before calling FSP
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l125">MemoryInit</a>
+      </li>
+      <li>0x37:
+        - Just after returning from FSP
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l127">MemoryInit</a>
+      </li>
+    </ol>
+  </li>
+  <li>Continue debugging with CONFIG_DISPLAY_HOBS enabled until TempRamExit is called</li>
+</ol>
+
 
 <hr>
 <p>Modified: 31 January 2016</p>
diff --git a/Documentation/Intel/SoC/soc.html b/Documentation/Intel/SoC/soc.html
index 0b0615d049..b5daac8fb5 100644
--- a/Documentation/Intel/SoC/soc.html
+++ b/Documentation/Intel/SoC/soc.html
@@ -22,6 +22,8 @@
   <li><a href="#Romstage">Romstage</a>
     <ol type="A">
       <li>Enable <a href="#SerialOutput">Serial Output"</a></li>
+      <li>Get the <a href="#PreviousSleepState">Previous Sleep State</a></li>
+      <li>Add the <a href="#MemoryInit">MemoryInit</a> Support</li>
     </ol>
   </li>
 </ol>
@@ -328,6 +330,57 @@ Use the following steps to debug the call to TempRamInit:
 </ol>
 
 
+<h2><a name="PreviousSleepState">Determine Previous Sleep State</a></h2>
+<p>
+  The following steps implement the code to get the previous sleep state:
+</p>
+<ol>
+  <li>Implement the fill_power_state routine which determines the previous sleep state</li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x32:
+        - Just after entering
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l99">romstage_common</a>
+      </li>
+      <li>0x33 - Just after calling
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l113">soc_pre_ram_init</a>
+      </li>
+      <li>0x34:
+        - Just after entering
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
+      </li>
+    </ol>
+</ol>
+
+
+<h2><a name="MemoryInit">MemoryInit Support</a></h2>
+<p>
+  The following steps implement the code to support the FSP MemoryInit call:
+</p>
+<ol>
+  <li>Add the chip.h header file to define the UPD values which get passed
+    to MemoryInit.  Skip the values containing SPD addresses and DRAM
+    configuration data which is determined by the board.
+    <p>
+      <b>Build Note</b>: The src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/devicetree.cb
+      file specifies the default values for these parameters.  The build
+      process creates the static.c module which contains the config data
+      structure containing these values.
+    </p>
+  </li>
+  <li>Edit romstage/romstage.c
+    <ol type="A">
+      <li>Implement the romstage/romstage.c/soc_memory_init_params routine to
+        copy the values from the config structure into the UPD structure
+      </li>
+      <li>Implement the soc_display_memory_init_params routine to display
+        the updated UPD parameters by calling fsp_display_upd_value
+      </li>
+    </ol>
+  </li>
+</ol>
+
+
 <hr>
 <p>Modified: 31 January 2016</p>
   </body>
diff --git a/Documentation/Intel/development.html b/Documentation/Intel/development.html
index b90fa96567..0cd2bd59b7 100644
--- a/Documentation/Intel/development.html
+++ b/Documentation/Intel/development.html
@@ -82,6 +82,18 @@
     </ol>
   </li>
   <li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li>
+  <li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li>
+  <li>Enable DRAM:
+    <ol type="A">
+      <li>Implement the SoC
+        <a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a>
+        Support
+      </li>
+      <li>Implement the board support to read the
+        <a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a>
+      </li>
+    </ol>
+  </li>
 </ol>
 
 
@@ -125,6 +137,32 @@
     <th>Testing</th>
   </tr>
   <tr>
+    <td>DRAM</td>
+    <td>
+      Load SPD data: src/soc/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/spd/<a target="_blank" href="Board/board.html#SpdData">spd.c</a><br>
+      UPD Setup:
+      <ul>
+        <li>src/soc&lt;Vendor&gt;//&lt;Chip Family&gt;/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li>
+        <li>src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li>
+      </ul>
+      FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l126">raminit.c</a>
+    </td>
+    <td>Select the following Kconfig values
+      <ul>
+        <li>DISPLAY_HOBS</li>
+        <li>DISPLAY_UPD_DATA</li>
+      </ul>
+      Testing successful if:
+      <ul>
+        <li>MemoryInit UPD values are correct</li>
+        <li>MemoryInit returns 0 (success) and</li>
+        <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
+          is not displayed
+        </li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
     <td>Serial Port</td>
     <td>
       SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br>
@@ -150,6 +188,26 @@
       is displayed<br>
     </td>
   </tr>
+  <tr>
+    <td>MemoryInit</td>
+    <td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br>
+      <a target="_blank" href="Board/board.html#SpdData">Board</a> support<br>
+    </td>
+    <td>Select the following Kconfig values
+      <ul>
+        <li>DISPLAY_HOBS</li>
+        <li>DISPLAY_UPD_DATA</li>
+      </ul>
+      Testing successful if:
+      <ul>
+        <li>MemoryInit UPD values are correct</li>
+        <li>MemoryInit returns 0 (success) and</li>
+        <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
+          is not displayed
+        </li>
+      </ul>
+    </td>
+  </tr>
 </table>