Change in coreboot[master]: [WIP]Documentation: Add Intel microcode update mechanism

[Patrick Rudolph (Code Review)]

Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/36539 )

Change subject: [WIP]Documentation: Add Intel microcode update mechanism
......................................................................

[WIP]Documentation: Add Intel microcode update mechanism

Document microcode updates and how secure microcode updates are done in
GNU/Linux.
Propose how to do microcode updates in coreboot.

Change-Id: I78350fc81cb0de7b0b2d9cbd8537e6b3815916c0
Signed-off-by: Patrick Rudolph 
---
M Documentation/soc/intel/index.md
A Documentation/soc/intel/microcode/index.md
2 files changed, 111 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/39/36539/1

diff --git a/Documentation/soc/intel/index.md b/Documentation/soc/intel/index.md
index f30ff9a..1cf8548 100644
--- a/Documentation/soc/intel/index.md
+++ b/Documentation/soc/intel/index.md
@@ -2,6 +2,10 @@

This section contains documentation about coreboot on specific Intel SOCs.

+## Common
+
+- [Microcode updates](microcode/index.md)
+
 ## Platforms

- [Common code development strategy](code_development_model/code_development_model.md)
diff --git a/Documentation/soc/intel/microcode/index.md b/Documentation/soc/intel/microcode/index.md
new file mode 100644
index 0000000..b7f5949
--- /dev/null
+++ b/Documentation/soc/intel/microcode/index.md
@@ -0,0 +1,107 @@
+# Microcode updates on Intel CPUs
+
+## What are microcodes?
+
+```eval_rst
+Microcode is a computer hardware technique that interposes a layer of
+organisation between the CPU hardware and the programmer-visible
+instruction set architecture of the computer. [#1]_
+```
+
+In coreboot the microcode updates are stored in files in the CBFS and
+are used to update the CPU microcode at runtime using a special instruction.
+
+## How does a microcode update look like?
+
+The microcode update is a binary provided by Intel consisting out of
+a header and data.
+The header holds the processor signature for which the update is
+intented and additional metadata.
+For detailed information check the [Intel SDM] 253668-060US Chapter 9.11.1
+
+## When are mirocode updates done?
+
+Microcode updates are stored in the CPU's SRAM and thus needs to be loaded
+after a hard reset. However loading microcode updates is done multiple times
+in coreboot's boot sequence.
+
+On some CPUs it's neccessary to do an microcode update before:
+* Cache-As-RAM is enabled
+* Legacy Intel TXT FIT boot is run
+* MultiProcessor-Init is run
+
+On some CPUs it's neccessary to do an microcode update after:
+* SMM setup was done
+* SGX setup was done
+
+## How to do microcode updates?
+
+The following chapter is based multiple sources and testing due to lack of clear
+documentation.
+
+In order to safely update microcode on any generation the GNU/Linux kernel
+"late loading mechanism" takes a conservative approach and obeys the following
+rules:
+
+```eval_rst
+* All physical CPU cores must be updated with the same microcode version [#2]_
+* Caches need to be flushed on certain CPUs prior to microcode update [#3]_
+* The sibling thread must be idle while a microcode update is ongoing [#4]_
+* All other APs on the same package should be idle (or in Wait-for-SIPI) [#5]_
+* The microcode update is done sequentially [#6]_
+```
+
+The downside of this approach is that it's very slow.
+
+It seems to be possible to run microcode updates in parallel on APs on specific
+CPUs.
+
+## How to do microcode updates in coreboot ramstage?
+
+*TBD*
+
+Proposal:
+1. Run microcode update sequential by default
+2. Flush caches in non CAR environment before running a microcode update
+3. Switch to parallel microcode update after extensive testing (10000 boot cycles)
+
+For parallel microcde update:
+1. On Intel HT enabled CPUs spinlock the slibing thread of a logical core
+2. On Intel HT enabled CPUs only update one thread of a physical core
+3. Synchronize microcode loading. This will make sure no other computational work
+   is being done while an update occurs (thus no Wait-for-SIPI).
+
+## Intel Hyper-Threading enabled CPUs
+
+```eval_rst
+According to Intel SDM a Hyper-Threading enabled core shares the microcode unit
+between the logical CPU cores [#4]_. Intel NetBurst CPUs must not attempt to
+update the microcode on both logical cores at the same time, this is safe for
+newer CPU generations.
+```
+
+## Where to obtain the microcode updates?
+
+The microcode update files can be found on Intel's [Github Microcode].
+
+## References
+- [Wikipedia microcode]
+- [Github Microcode]
+- [Intel SDM]
+
+-------------
+```eval_rst
+.. [#1] Kent, Allen; Williams, James G. (April 5, 1993). `Encyclopedia of Computer Science and Technology: Volume 28 http://https://books.google.com/books?id=EjWV8J8CQEYC`_
+.. [#2] `Intel SDM Document 253668-060US`_ Chapter 9.11.6.3 "Update in a System Supporting Intel Hyper-Threading Technology"
+.. [#3] GNU/Linux commit by Ashok Raj `https://lore.kernel.org/patchwork/patch/890717/`_
+.. [#4] `Intel SDM Document 253668-060US`_ Chapter 8.8.5 "Microcode Update Resources"
+.. [#5] GNU/Linux commit by Ashok Raj `https://lore.kernel.org/patchwork/patch/890713/`_
+.. [#6] `Intel SDM Document 253668-060US`_ Chapter 9.11.6.3 "Update in a System Supporting Intel Hyper-Threading Technology"
+
+.. _Intel SDM Document 253668-060US: https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-3...
+
+```
+
+[Wikipedia microcode]: https://en.wikipedia.org/wiki/Microcode
+[Github Microcode]: https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files
+[Intel SDM]: https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-3...

[Angel Pons (Code Review)]

Angel Pons has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/36539 )

Change subject: [WIP]Documentation: Add Intel microcode update mechanism
......................................................................

Patch Set 1:

(2 comments)

https://review.coreboot.org/c/coreboot/+/36539/1/Documentation/soc/intel/mic... 
File Documentation/soc/intel/microcode/index.md:

https://review.coreboot.org/c/coreboot/+/36539/1/Documentation/soc/intel/mic... 
PS1, Line 42: generation the GNU/Linux kernel
I would replace this part with: generation, Linux's

https://review.coreboot.org/c/coreboot/+/36539/1/Documentation/soc/intel/mic... 
PS1, Line 69: slibing
sibiling

[Arthur Heymans (Code Review)]

Arthur Heymans has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/36539 )

Change subject: [WIP]Documentation: Add Intel microcode update mechanism
......................................................................

Patch Set 1:

(1 comment)

Sounds good.

https://review.coreboot.org/c/coreboot/+/36539/1/Documentation/soc/intel/mic... 
File Documentation/soc/intel/microcode/index.md:

https://review.coreboot.org/c/coreboot/+/36539/1/Documentation/soc/intel/mic... 
PS1, Line 42: In order to safely update microcode on any generation the GNU/Linux kernel
            : "late loading mechanism" takes a conservative approach and obeys the following
            : rules:
sidenote: From my own experience with core/core2 CPU's, doing MCU on the BSP in CAR breaks CAR and I made the same assumption for late targets like sandybridge where microcode is updated on the BSP in the romcc bootblock (so before CAR setup), hence the assembly version 'microcode_asm.S' to migrate to C_ENVIRONMENT_BOOTBLOCK.

[M] Change in coreboot[master]: [WIP]Documentation: Add Intel microcode update mechanism

[Martin L Roth (Code Review)]

Martin L Roth has abandoned this change. ( https://review.coreboot.org/c/coreboot/+/36539?usp=email )

Change subject: [WIP]Documentation: Add Intel microcode update mechanism
......................................................................

Abandoned

This patch has not been touched in over 12 months. Anyone who wants to take over work on this patch, please feel free to restore it and do any work needed to get it merged. If you create a new patch based on this work, please credit the original author.