Documentation: add Intel Broadwell

Change-Id: I0b1c29162a64030b5c100368f2471702e22b8311
Signed-off-by: Iru Cai <mytbk920423@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/54744
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>

3 files changed, 49 insertions, 0 deletions

diff --git a/Documentation/soc/intel/broadwell/blobs.md b/Documentation/soc/intel/broadwell/blobs.md
new file mode 100644
index 0000000000..b9f99afe66
--- /dev/null
+++ b/Documentation/soc/intel/broadwell/blobs.md
@@ -0,0 +1,41 @@
+# Blobs used in Intel Broadwell boards
+
+All Broadwell boards supported by coreboot require two proprietary blobs.
+In a coreboot image of a Broadwell board, the blobs are named `mrc.bin` and
+`refcode` in CBFS.
+
+`mrc.bin` is run in romstage to initialize the memory. It is placed at a fixed
+address in CBFS and is loaded at a fixed address in memory.
+
+`refcode` is run in ramstage to initialize the system agent and the PCH. It is
+a relocatable ELF object.
+
+## Obtaining the blobs
+
+Both `mrc.bin` and `refcode` can be obtained from a coreboot image of a Broadwell
+board, for example a Purism Librem 13 v1 coreboot image from [MrChromebox].
+
+    cbfstool coreboot_*.rom extract -f broadwell-mrc.bin -n mrc.bin
+    cbfstool coreboot_*.rom extract -m x86 -f broadwell-refcode.elf -n fallback/refcode
+
+## SPD Addresses
+
+The SPD addresses in Broadwell `pei_data` struct are similar to [Haswell].
+
+## Intel GbE support
+
+Unlike Haswell boards, the `pei_data` struct of Broadwell doesn't have `gbe_enable`
+field. For boards with an Intel GbE device, a modification of `refcode` is needed,
+otherwise `refcode` will disable the Intel GbE device and the OS cannot find it
+in the list of PCI devices.
+
+## Use Broadwell SoC code for Haswell ULT boards
+
+Haswell ULT boards can use Broadwell SoC code. To use Broadwell code for Haswell ULT
+boards, `devicetree.cb` file and `pei_data` code need to be ported to Broadwell, and
+build the code with Broadwell `mrc.bin` and `refcode` instead of using Haswell `mrc.bin`.
+
+Broadwell SoC code doesn't support non-ULT Haswell or non-ULT Broadwell boards.
+
+[MrChromebox]: https://mrchromebox.tech/
+[Haswell]: ../../../northbridge/intel/haswell/mrc.bin.md
diff --git a/Documentation/soc/intel/broadwell/index.md b/Documentation/soc/intel/broadwell/index.md
new file mode 100644
index 0000000000..11a3ce1058
--- /dev/null
+++ b/Documentation/soc/intel/broadwell/index.md
@@ -0,0 +1,7 @@
+# Intel Broadwell documentation
+
+This section describes the Intel Broadwell SoC.
+
+## Proprietary blobs
+
+- [mrc.bin and refcode](blobs.md)
diff --git a/Documentation/soc/intel/index.md b/Documentation/soc/intel/index.md
index 71e427ebef..8da9cacc6e 100644
--- a/Documentation/soc/intel/index.md
+++ b/Documentation/soc/intel/index.md
@@ -6,6 +6,7 @@ This section contains documentation about coreboot on specific Intel SOCs.
 
 - [Common code development strategy](code_development_model/code_development_model.md)
 - [FSP](fsp/index.md)
+- [Broadwell](broadwell/index.md)
 - [Ice Lake/9th Gen Core-i series](icelake/index.md)
 - [MP Initialization](mp_init/mp_init.md)
 - [Microcode Updates](microcode.md)