Documentation: Add the x86 FSP Binary

Document how to add the FSP binary to the SPI flash image.

TEST=None

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

3 files changed, 155 insertions, 0 deletions

diff --git a/Documentation/Intel/SoC/soc.html b/Documentation/Intel/SoC/soc.html
index 84206823a9..679e022f64 100644
--- a/Documentation/Intel/SoC/soc.html
+++ b/Documentation/Intel/SoC/soc.html
@@ -18,6 +18,7 @@
   <li><a href="#Descriptor">Start Booting</a></li>
   <li><a href="#EarlyDebug">Early Debug</a></li>
   <li><a href="#Bootblock">Bootblock</a></li>
+  <li><a href="#TempRamInit">TempRamInit</a></li>
 </ol>
 
 
@@ -196,6 +197,94 @@ mv build/coreboot.rom.new build/coreboot.rom
 
 
 <hr>
+<h1><a name="TempRamInit">TempRamInit</a></h1>
+<p>
+  Enable the call to TempRamInit in two stages:
+</p>
+<ol>
+  <li>Finding the FSP binary in the read-only CBFS region</li>
+  <li>Call TempRamInit</li>
+</ol>
+
+
+<h2>Find FSP Binary</h2>
+<p>
+Use the following steps to locate the FSP binary:
+</p>
+<ol>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/Kconfig file
+    <ol type="A">
+      <li>Add "select USE_GENERIC_FSP_CAR_INC" to enable the use of
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc">src/drivers/intel/fsp1_1/cache_as_ram.inc</a>
+      </li>
+      <li>Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common
+        specifically building
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/soc/intel/common/util.c">util.c</a>
+      </li>
+    </ol>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>Alternating 0xba and 0x01 - The FSP image was not found</li>
+    </ol>
+  </li>
+  <li>Add the <a target="_blank" href="../fsp1_1.html#FspBinary">FSP binary file</a> to the flash image</li>
+  <li>Set the following Kconfig values:
+    <ul>
+      <li>CONFIG_FSP_LOC to the FSP base address specified in the previous step</li>
+      <li>CONFIG_FSP_IMAGE_ID_STRING</li>
+    </ul>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>Alternating 0xbb and 0x02 - TempRamInit executed, no CPU microcode update found</li>
+    </ol>
+  </li>
+</ol>
+
+
+<h2>Calling TempRamInit</h2>
+<p>
+Use the following steps to debug the call to TempRamInit:
+</p>
+<ol>
+  <li>Add the CPU microcode update file
+    <ol type="A">
+      <li>Add the microcode file with the following command
+<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t microcode -n cpu_microcode_blob.bin -b &lt;base address&gt; -f cpu_microcode_blob.bin</code></pre>
+      </li>
+      <li>Set the Kconfig values
+        <ul>
+          <li>CONFIG_CPU_MICROCODE_CBFS_LOC set to the value from the previous step</li>
+          <li>CONFIG_CPU_MICROCODE_CBFS_LEN</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>0x2A - Just before calling
+        <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">cache_as_ram_main</a>
+        which is the start of the verstage code which may be part of romstage
+      </li>
+    </ol>
+  </li>
+</ol>
+
+
+<hr>
 <p>Modified: 31 January 2016</p>
   </body>
 </html>
\ No newline at end of file
diff --git a/Documentation/Intel/development.html b/Documentation/Intel/development.html
index 68a52c8c98..2b23b39e23 100644
--- a/Documentation/Intel/development.html
+++ b/Documentation/Intel/development.html
@@ -70,9 +70,62 @@
   <li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li>
   <li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li>
   <li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li>
+  <li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li>
 </ol>
 
 
+
+<hr>
+<table border="1">
+  <tr bgcolor="#c0ffc0">
+    <th colspan=3><h1>Features</h1></th>
+  </tr>
+  <tr bgcolor="#c0ffc0">
+    <th>SoC</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>Cache-as-RAM</td>
+    <td>
+      <a target="_blank" href="SoC/soc.html#TempRamInit">Find</a>
+      FSP binary:
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l38">cache_as_ram.inc</a><br>
+      Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a>
+      called from
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">cache_as_ram.inc</a><br>
+      Disable: FSP 1.1 TempRamExit called from
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
+    </td>
+    <td>FindFSP: POST code 0x90
+      (<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
+      is displayed<br>
+      Enable: POST code
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
+      is displayed<br>
+      Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit
+    </td>
+  </tr>
+  <tr bgcolor="#c0ffc0">
+    <th>FSP</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>TempRamInit</td>
+    <td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td>
+    <td>FSP binary found: POST code 0x90
+      (<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
+      is displayed<br>
+      TempRamInit successful: POST code
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
+      is displayed<br>
+    </td>
+  </tr>
+</table>
+
+
+
 <hr>
 <p>Modified: 31 January 2016</p>
   </body>
diff --git a/Documentation/Intel/fsp1_1.html b/Documentation/Intel/fsp1_1.html
index e08be830ff..456db802a8 100644
--- a/Documentation/Intel/fsp1_1.html
+++ b/Documentation/Intel/fsp1_1.html
@@ -14,6 +14,7 @@
 </p>
 <ol>
   <li><a href="#RequiredFiles">Required Files</a></li>
+  <li>Add the <a href="#FspBinary">FSP Binary File</a> to the coreboot File System</li>
 </ol>
 
 <p>
@@ -45,6 +46,18 @@
 
 
 <hr>
+<h1><a name="FspBinary">Add the FSP Binary File to coreboot File System</a></h1>
+<p>
+  Add the FSP binary to the coreboot flash image using the following command:
+</p>
+<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t fsp -n fsp.bin -b &lt;base address&gt; -f fsp.bin</code></pre>
+<p>
+  This command relocates the FSP binary to the 4K byte aligned location in CBFS so that the
+  FSP code for TempRamInit may be executed in place.
+</p>
+
+
+<hr>
 <p>Modified: 31 January 2016</p>
   </body>
 </html>
\ No newline at end of file