Alexander Couzens has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/35438 )
Change subject: LinuxBoot: fix `make clean` for linux builds
......................................................................
LinuxBoot: fix `make clean` for linux builds
The kernel_dir variable was never correct, because targets/linux.mk
is using build directories based on the version e.g. kernel_4.19.73.
Change-Id: I749200bd32d86303ae02903afd96f730ac36b307
Signed-off-by: Alexander Couzens <lynxis(a)fe80.eu>
---
M payloads/external/LinuxBoot/Makefile
1 file changed, 1 insertion(+), 2 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/38/35438/1
diff --git a/payloads/external/LinuxBoot/Makefile b/payloads/external/LinuxBoot/Makefile
index 5840e8e..8b81c8a 100644
--- a/payloads/external/LinuxBoot/Makefile
+++ b/payloads/external/LinuxBoot/Makefile
@@ -14,7 +14,6 @@
##
project_dir=linuxboot
-kernel_dir=$(project_dir)/kernel
unexport $(COREBOOT_EXPORTS)
@@ -65,7 +64,7 @@
linuxboot: kernel initramfs_compressed
clean:
- if [ -d "$(kernel_dir)" ]; then rm -rf $(kernel_dir); fi
+ rm -rf $(project_dir)/kernel*
rm -f $(project_dir)/u-root
rm -f $(project_dir)/initramfs*
--
To view, visit https://review.coreboot.org/c/coreboot/+/35438
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I749200bd32d86303ae02903afd96f730ac36b307
Gerrit-Change-Number: 35438
Gerrit-PatchSet: 1
Gerrit-Owner: Alexander Couzens <lynxis(a)fe80.eu>
Gerrit-MessageType: newchange
Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/35739 )
Change subject: soc/intel/common/block: Update microcode for each core
......................................................................
soc/intel/common/block: Update microcode for each core
On Hyper-Threading enabled platform update the microcde only once
for each core, not for each thread.
Follow Intel Software Developer Guidelines as the added comment
also states.
Change-Id: I72804753e567a137a5648ca6950009fed332531b
Signed-off-by: Patrick Rudolph <patrick.rudolph(a)9elements.com>
---
M src/soc/intel/common/block/cpu/mp_init.c
1 file changed, 20 insertions(+), 1 deletion(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/39/35739/1
diff --git a/src/soc/intel/common/block/cpu/mp_init.c b/src/soc/intel/common/block/cpu/mp_init.c
index 2c5061f..e7689cf 100644
--- a/src/soc/intel/common/block/cpu/mp_init.c
+++ b/src/soc/intel/common/block/cpu/mp_init.c
@@ -26,6 +26,7 @@
#include <intelblocks/fast_spi.h>
#include <intelblocks/mp_init.h>
#include <intelblocks/msr.h>
+#include <cpu/intel/common/common.h>
#include <soc/cpu.h>
static const void *microcode_patch;
@@ -44,7 +45,24 @@
static void init_one_cpu(struct device *dev)
{
soc_core_init(dev);
- intel_microcode_load_unlocked(microcode_patch);
+
+ /*
+ * Update just on the first CPU in the core. Other siblings
+ * get the update automatically according to Document: 253668-060US
+ * Intel SDM Chapter 9.11.6.3
+ * "Update in a System Supporting Intel Hyper-Threading Technology"
+ * Intel Hyper-Threading Technology has implications on the loading of the
+ * microcode update. The update must be loaded for each core in a physical
+ * processor. Thus, for a processor supporting Intel Hyper-Threading
+ * Technology, only one logical processor per core is required to load the
+ * microcode update. Each individual logical processor can independently
+ * load the update. However, MP initialization must provide some mechanism
+ * (e.g. a software semaphore) to force serialization of microcode update
+ * loads and to prevent simultaneous load attempts to the same core.
+ */
+ if (!intel_ht_sibling()) {
+ intel_microcode_load_unlocked(microcode_patch);
+ }
}
static struct device_operations cpu_dev_ops = {
@@ -141,6 +159,7 @@
if (CONFIG(USE_INTEL_FSP_MP_INIT))
return;
+ /* Update microcode on BSP */
microcode_patch = intel_microcode_find();
intel_microcode_load_unlocked(microcode_patch);
--
To view, visit https://review.coreboot.org/c/coreboot/+/35739
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I72804753e567a137a5648ca6950009fed332531b
Gerrit-Change-Number: 35739
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <patrick.rudolph(a)9elements.com>
Gerrit-MessageType: newchange
Christoph Pomaska has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/34905 )
Change subject: mb/supermicro/x10slm-f: Add new superio support to board's Kconfig
......................................................................
mb/supermicro/x10slm-f: Add new superio support to board's Kconfig
Since the superio support code didnt exist when the board was ported,
the Kconfig was not modified yet to add support for the BMC-chip.
This commit fixes the missing Kconfig entry.
Change-Id: I4f89c2ddcc00327e01d0a83fc13cfa862e6abd70
Signed-off-by: Christoph Pomaska <c.pomaska(a)hosting.de>
---
M src/mainboard/supermicro/x10slm-f/Kconfig
1 file changed, 4 insertions(+), 3 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/05/34905/1
diff --git a/src/mainboard/supermicro/x10slm-f/Kconfig b/src/mainboard/supermicro/x10slm-f/Kconfig
index 3945c09..6effff2 100644
--- a/src/mainboard/supermicro/x10slm-f/Kconfig
+++ b/src/mainboard/supermicro/x10slm-f/Kconfig
@@ -20,15 +20,16 @@
def_bool y
select BOARD_ROMSIZE_KB_16384
select CPU_INTEL_HASWELL
- select DRIVERS_ASPEED_AST2050 # Supports AST2400 too.
+ select SOUTHBRIDGE_INTEL_LYNXPOINT
select HAVE_ACPI_RESUME
select HAVE_ACPI_TABLES
select HAVE_OPTION_TABLE
select HAVE_CMOS_DEFAULT
select NORTHBRIDGE_INTEL_HASWELL
select SERIRQ_CONTINUOUS_MODE
- select SOUTHBRIDGE_INTEL_LYNXPOINT
- select SUPERIO_NUVOTON_NCT6776
+ select DRIVERS_ASPEED_AST2050 # Supports AST2400 too.
+ select SUPERIO_ASPEED_AST2400 # The board's BMC
+ select SUPERIO_NUVOTON_NCT6776 # the board's superio
select SUPERIO_NUVOTON_NCT6776_COM_A
config CBFS_SIZE
--
To view, visit https://review.coreboot.org/c/coreboot/+/34905
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I4f89c2ddcc00327e01d0a83fc13cfa862e6abd70
Gerrit-Change-Number: 34905
Gerrit-PatchSet: 1
Gerrit-Owner: Christoph Pomaska <github(a)aufmachen.jetzt>
Gerrit-MessageType: newchange
Arthur Heymans has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/36126 )
Change subject: Documentation: Add cache as ram documentation
......................................................................
Documentation: Add cache as ram documentation
This add documentation around coreboot's history of CAR usage.
The history is reconstructed from articles and git/svn history,
but should provide a good overview of the challenges and solutions
coreboot came up with to deal with early code execution on X86
platforms.
The technical details about CAr will come in follow-up patch and are
marked as TODO for now.
Change-Id: I964d59a6bd210f3d4d06220d2ec7166110ab2cf3
Signed-off-by: Arthur Heymans <arthur(a)aheymans.xyz>
---
A Documentation/cpu/index.md
A Documentation/cpu/x86/car.md
M Documentation/index.md
3 files changed, 171 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/26/36126/1
diff --git a/Documentation/cpu/index.md b/Documentation/cpu/index.md
new file mode 100644
index 0000000..d9f063f
--- /dev/null
+++ b/Documentation/cpu/index.md
@@ -0,0 +1,5 @@
+# CPU-specific documentation
+
+This section contains documentation about coreboot on specific CPU.
+
+* [A gentle introduction to Cache-as-Ram on X86](x86/car.md)
diff --git a/Documentation/cpu/x86/car.md b/Documentation/cpu/x86/car.md
new file mode 100644
index 0000000..3d2983e
--- /dev/null
+++ b/Documentation/cpu/x86/car.md
@@ -0,0 +1,165 @@
+# A gentle introduction to Cache-as-Ram on X86
+
+This explains a bit of history on CAR in coreboot, how it works
+and then finally give a more in depth overview at the steps of
+how it is set up on Intel CPUs.
+
+## Glossary
+
+- Cache-as-RAM/CAR: Using not memory mapped CPU cache as execution
+ environment.
+- XIP: Execute in place on a memory mapped medium
+- SRAM: Static Random Access Memory, here: memory mapped memory
+ that needs no initialization.
+- ROMCC: A C compiler using only the CPU registers.
+
+## Cache-as-Ram, the basics
+
+When an X86 platforms boot, it starts in a pretty bare environment.
+The first instruction is fetched from the top of the boot medium,
+which on most x86 platforms is memory mapped below 4G (in 32bit
+protected mode). Not only do they start in 16bit 'real' mode,
+most of the hardware starts uninitialized. This includes the dram
+controller. Another thing about X86 platforms is that they generally
+don't feature SRAM, static RAM. SRAM for this purpose of this text is
+a small region of ram that is available without any initialization.
+Without RAM this leaves the system with just CPU registers and a
+memory mapped boot medium of which code can be executed in place (XIP)
+to initialize the hardware.
+
+For simple dram controllers that environment is just fine and
+initializing the dram controller in assembly code without using a
+stack is very doable. Modern systems however require complex
+initialization procedures and writing that in assembly would be either
+too hard or simply impossible. To overcome this limitation a technique
+called Cache-as-Ram exists. It allows to use the CPU's Cache-as-Ram.
+This in turn makes it possible to write the early initialization code
+in a higher level programming language compiled by a regular compiler,
+e.g. GCC. Typically only the stack is placed in Cache-as-Ram and the
+code is still executed in place, but copying code in the cache as ram
+and executing from there is also possible.
+
+For coreboot this means that with only a very small amount of assembly
+code to set up CAR, all the other code can written in C, which
+compared to writing assembly tremendously increases development speed
+and is much less error prone.
+
+## A bit of history on Cache-as-Ram in coreboot
+
+### Linux as a BIOS? The invention of romstage
+
+When LinuxBIOS, later coreboot, started out, the first naive attempt
+to run the Linux kernel instead of the legacy BIOS interface, was to
+jump straight to loading the kernel. This did not work at all, since
+dram was not working at that point. LinuxBIOS v1 therefore
+initialized the memory in assembly before it was able to load the
+kernel. This executed in place and would later become romstage. It
+turned that Linux needed other devices, like enumerated and have it's
+resources allocated, so yet another stage, ramstage, was called into
+life, but that's another story.
+
+### coreboot v2: romcc
+
+In 2003 AMD's K8 CPU's came out. Those CPU's featured an on die memory
+controller and also a new point to point BUS for CPU <-> CPU and
+CPU <-> IO controller (northbridge) devices. Writing support for
+these in assembly became difficult and a better solution was needed.
+This is where ROMCC came to the rescue in 2002. ROMCC is a 25K lines
+of code C compiler, written by Eric Biederman, that does not use a
+stack but uses CPU registers instead. Besides the 8 general purpose
+registers on x86 the MMX and SSE registers, respectively _%mm0_-_%mm7_
+and _%xmm0_-_%xmm7_, can be used to store data. ROMCC also converts
+all function calls to static inline functions. This has the
+disadvantage that a ROMCC compiled stage must be compiled in one go,
+linking is not possible. In practice you will see a lot of '#include
+_some_file.c_' which is quite unusual in C, because it makes the
+inclusion of files fragile. Given that limited amount
+'register-stack', it also imposes restrictions on how many levels of
+nested function can be achieved. One last issue with ROMCC is that
+no-one really dared touching that code, due to its size and complexity
+besides its original author.
+
+Coreboot used ROMCC in the following way: a bootblock written in both
+assembly to enter 32bit protected mode would use ROMCC compiled code
+to either jump to 'normal/romstage' or 'fallback/romstage' which in
+turn was also compiled with romstage.
+
+### Cache-as-Ram
+
+While ROMCC was eventually used for early initialization, prior to
+that development attempts were made to use the CPU's cache as RAM.
+This would allow to use regular GCC compiled and linked code to
+be used. The idea is to set up the CPU's cache to Write Back to a
+region, while disable cacheline filling or simply hope that no cache
+eviction or invalidation happens. Eric Biederman initially got CAR
+working, but with the advent of Intel Hyperthreading on the Pentium 4,
+on which CAR setup proved to be a little more difficult and he
+developed ROMCC instead.
+
+Around 2006 a lot was learned from coreboot v2 with its ROMCC usage
+and development on coreboot v3 was started. The decision was mode to
+not use ROMCC anymore and use Cache Memory for early stages. The
+results were good as init object code size is reduced by factor of
+four. So the code was smaller and faster at the same time.
+
+coreboot v4 sort of merged v2 and v3, so it was a mix of ROMCC compiled
+romstage and romstage with CAR.
+
+In 2014 Support for ROMCC compiled romstage was dropped.
+
+### Intel Apollolake, a new era: POSTCAR_STAGE and C_ENVIRONMENT_BOOTBLOCK
+
+In 2016 Intel released the ApolloLake architecture. This architecture
+is a weird duck in the X86 pool. It is the first Intel CPU to feature
+MMC as a boot medium and does not memory map it. It also features to
+the main CPU read only SRAM that is mapped right below 4G. The
+bootblock is copied to SRAM and executed. Given that the boot medium
+is not always memory mapped XIP is not an option. The solution is to
+set up CAR in the bootblock and copy the romstage in CAR. We call this
+C_ENVIRONMENT_BOOTBLOCK, because it runs GCC compiled code. Granted
+XIP is still possible on ApolloLake, but coreboot has to use Intel's
+blob, FSP-M, and it is linked to run in CAR, so a blob actually forced
+a nice feature in coreboot!
+
+Another issue arises with this setup. With romstage running from the
+read only boot medium, you can continue executing code (albeit without
+stack) to tear down the CAR and start executing code from 'real' RAM.
+On ApolloLake with romstage executing from CAR, tearing down CAR in
+there, would shooting in ones own foot, as our code would be gone
+in doing so. The solution was to tear down CAR in a separate stage,
+named 'postcar' stage. This provides a clean separation of programs
+and results in needing less linker scripts hacks in romstage. This
+solution was therefore adopted by many other platforms that still did
+XIP.
+
+### AMD Zen, 2019
+
+On AMD Zen the first CPU to come out of reset is the PSP and it
+initializes the dram before pulling out the main CPU out of reset.
+CAR won't be needed, nor used on this platform.
+
+### The future?
+
+For coreboot release 4.11, scheduled for october 2019, support for
+ROMCC in the bootblock will be dropped as will support for the messy
+tearing down of CAR in romstage as opposed to doing that in a separate
+stage.
+
+## In depth analysis
+
+### CAR setup
+
+TODO: MTRR, IPI/hyperthreaded, ROM Caching, Non-evict
+
+### Linker symbols
+
+TODO: sharing things over multiple CAR stages: car.ld
+
+### CAR teardown
+
+TODO: postcarstage, NO_CAR_GLOBAL_MIGRATION
+
+## References
+[2007, The Open Source BIOS is Ten An interview with the coreboot developers](http://www.h-online.com/open/features/The-Open-Source-BIOS-is-T…
+[A Framework for Using Processor Cache-as-Ram (CAR)](https://www.coreboot.org/images/6/6c/LBCar.pdf)
+[CAR: Using Cache-as-Ram in LinuxBIOS](https://www.coreboot.org/data/yhlu/cache_as_ram_lb_09142006.pdf)
diff --git a/Documentation/index.md b/Documentation/index.md
index 1c04ad3..85666cb 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -177,6 +177,7 @@
* [Display panel-specific documentation](gfx/display-panel.md)
* [Architecture-specific documentation](arch/index.md)
* [Platform independend drivers documentation](drivers/index.md)
+* [CPU-specific documentation](cpu/index.md)
* [Northbridge-specific documentation](northbridge/index.md)
* [System on Chip-specific documentation](soc/index.md)
* [Mainboard-specific documentation](mainboard/index.md)
--
To view, visit https://review.coreboot.org/c/coreboot/+/36126
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I964d59a6bd210f3d4d06220d2ec7166110ab2cf3
Gerrit-Change-Number: 36126
Gerrit-PatchSet: 1
Gerrit-Owner: Arthur Heymans <arthur(a)aheymans.xyz>
Gerrit-MessageType: newchange
Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/34709 )
Change subject: x86: Prevent Kconfig errors resulting in a brick
......................................................................
x86: Prevent Kconfig errors resulting in a brick
Always select USE_LEGACY_8254_TIMER if we know we have to.
Fixes boot failure (Linux kernel/GRUB2 hangs with no console output)
on X11SSH-TF using SeaBIOS as payload.
Change-Id: Ica0c20255f661dd61edc3a7d15646b7447c4658e
Signed-off-by: Patrick Rudolph <patrick.rudolph(a)9elements.com>
---
M payloads/external/GRUB2/Kconfig.name
M payloads/external/SeaBIOS/Kconfig.name
M src/device/Kconfig
M src/soc/intel/common/block/timer/Kconfig
4 files changed, 3 insertions(+), 1 deletion(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/09/34709/1
diff --git a/payloads/external/GRUB2/Kconfig.name b/payloads/external/GRUB2/Kconfig.name
index fe60d76..40629ad 100644
--- a/payloads/external/GRUB2/Kconfig.name
+++ b/payloads/external/GRUB2/Kconfig.name
@@ -1,6 +1,7 @@
config PAYLOAD_GRUB2
bool "GRUB2"
depends on ARCH_X86 || ARCH_ARM
+ select USE_LEGACY_8254_TIMER if SOC_INTEL_COMMON_BLOCK
help
Select this option if you want to build a coreboot image
with a GRUB2 payload. If you don't know what this is
diff --git a/payloads/external/SeaBIOS/Kconfig.name b/payloads/external/SeaBIOS/Kconfig.name
index bb1f30c..8f92997 100644
--- a/payloads/external/SeaBIOS/Kconfig.name
+++ b/payloads/external/SeaBIOS/Kconfig.name
@@ -1,6 +1,7 @@
config PAYLOAD_SEABIOS
bool "SeaBIOS"
depends on ARCH_X86
+ select USE_LEGACY_8254_TIMER if SOC_INTEL_COMMON_BLOCK
help
Select this option if you want to build a coreboot image
with a SeaBIOS payload. If you don't know what this is
diff --git a/src/device/Kconfig b/src/device/Kconfig
index e605bc2..ebf6bfb 100644
--- a/src/device/Kconfig
+++ b/src/device/Kconfig
@@ -86,6 +86,7 @@
bool "Run VGA Option ROMs"
depends on PCI && (ARCH_X86 || ARCH_PPC64) && !MAINBOARD_FORCE_NATIVE_VGA_INIT
select HAVE_VGA_TEXT_FRAMEBUFFER
+ select USE_LEGACY_8254_TIMER if SOC_INTEL_COMMON_BLOCK
help
Execute VGA Option ROMs in coreboot if found. This can be used
to enable PCI/AGP/PCI-E video cards when not using a SeaBIOS
diff --git a/src/soc/intel/common/block/timer/Kconfig b/src/soc/intel/common/block/timer/Kconfig
index a214ef0..66bf9cf 100644
--- a/src/soc/intel/common/block/timer/Kconfig
+++ b/src/soc/intel/common/block/timer/Kconfig
@@ -5,7 +5,6 @@
config USE_LEGACY_8254_TIMER
bool "Use Legacy 8254 Timer"
- default y if PAYLOAD_SEABIOS || VGA_ROM_RUN
default n
help
This sets the FSP UPD to enable Legacy 8254 clock gating. As per
--
To view, visit https://review.coreboot.org/c/coreboot/+/34709
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: Ica0c20255f661dd61edc3a7d15646b7447c4658e
Gerrit-Change-Number: 34709
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <patrick.rudolph(a)9elements.com>
Gerrit-MessageType: newchange
Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/32020
Change subject: [WIP]x86: Introduce the blobolator
......................................................................
[WIP]x86: Introduce the blobolator
This is a PoC to run arbitrary code and blobs inside an emulated
virtual machine using libx86emu, thus the name blobolator.
The libx86emu has been patched to the following:
* redirect IO to the host machine it's running on
* trace IO
* start in protected mode
* add mechanism to drop IO access
* add Kconfig to debug code it is running
Implemented features:
* Run ramstage in libx86emu
* Run postcar in libx86emu
TODO:
* Add support to trace only blobs, not stages.
* Improve translation of known IO to human readable format
** COM
** PCI
** APIC
** PIT
** POST
Tested on qemu. Sucessfully run ramstage in blobolator.
Change-Id: I13e47f45e69376d046f35c04363fe3db1cfaa610
Signed-off-by: Patrick Rudolph <patrick.rudolph(a)9elements.com>
---
M src/Kconfig
M src/arch/x86/boot.c
M src/mainboard/emulation/qemu-i440fx/romstage.c
M src/mainboard/emulation/qemu-q35/romstage.c
M src/vendorcode/Makefile.inc
A src/vendorcode/libx86emu/Makefile.inc
A src/vendorcode/libx86emu/blobolator.c
A src/vendorcode/libx86emu/decode.c
A src/vendorcode/libx86emu/include/decode.h
A src/vendorcode/libx86emu/include/mem.h
A src/vendorcode/libx86emu/include/ops.h
A src/vendorcode/libx86emu/include/prim_ops.h
A src/vendorcode/libx86emu/include/x86emu.h
A src/vendorcode/libx86emu/include/x86emu_int.h
A src/vendorcode/libx86emu/mem.c
A src/vendorcode/libx86emu/ops.c
A src/vendorcode/libx86emu/ops2.c
A src/vendorcode/libx86emu/prim_ops.c
18 files changed, 14,512 insertions(+), 2 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/20/32020/1
--
To view, visit https://review.coreboot.org/c/coreboot/+/32020
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I13e47f45e69376d046f35c04363fe3db1cfaa610
Gerrit-Change-Number: 32020
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <patrick.rudolph(a)9elements.com>
Gerrit-MessageType: newchange
Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/34632 )
Change subject: Documentation: Add guidelines for new mainboard ports
......................................................................
Documentation: Add guidelines for new mainboard ports
This is WIP and partly copied from https://www.coreboot.org/Motherboard_Porting_Guide
It also list what should be documented for new mainboard ports.
Change-Id: I134dbf2341696ba0dd33c3d52bf787b8eaabbdab
Signed-off-by: Patrick Rudolph <siro(a)das-labor.org>
---
M Documentation/getting_started/index.md
A Documentation/getting_started/new_mainboard_ports.md
M Documentation/getting_started/writing_documentation.md
3 files changed, 95 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/32/34632/1
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
index 52d873e..7821ee1 100644
--- a/Documentation/getting_started/index.md
+++ b/Documentation/getting_started/index.md
@@ -7,3 +7,4 @@
* [Gerrit Guidelines](gerrit_guidelines.md)
* [Documentation License](license.md)
* [Writing Documentation](writing_documentation.md)
+* [Adding new mainboards](new_mainboard_ports.md)
diff --git a/Documentation/getting_started/new_mainboard_ports.md b/Documentation/getting_started/new_mainboard_ports.md
new file mode 100644
index 0000000..cb7cd9b
--- /dev/null
+++ b/Documentation/getting_started/new_mainboard_ports.md
@@ -0,0 +1,91 @@
+# Adding new mainboards
+
+Mainboard code is placed under `src/mainboards`. It glues the HW components
+together by selecting appropiate northbridge, southbridge, on-board HW and
+drivers.
+
+It provides the devicetree.cb, configures GPIOs, audio codecs, a static ACPI
+board desciption and allows the romstage code to retrieve the SPD for
+DRAM training.
+
+## Starting a new port from scratch
+
+1. Identify your platform
+ Try to find out as much as possible about the current hardware.
+ Dump information with existing tools:
+ * lspci
+ * lsusb
+ * superiotool
+ * inteltool
+ * ectool
+ * dmidecode
+ * acpidump
+
+ Have a look at the mainboard schematics to see how those components are
+ connected.
+2. Find a similar existing board
+ It a good idea to find a similar board and use it as reference. You should
+ then provide a proper GPIO configuration and devicetree.cb.
+3. Find a similar SuperIo or BMC
+ To debug coreboot you should get the serial console working first. If your
+ board has a SuperIO or BMC try to find a compatible one.
+ Some boards have UART hardware on the SoC, makeing external components
+ obsolete.
+4. Start with a minimal bootable configuration. That is:
+ * serial is working
+ * SPD reading/DRAM is working
+ * A payload that is able to boot an operating system
+5. Be able to recover from a bad flash. You should use external flashing as
+ it's likely that you will brick your platform on the first attempts.
+ Make sure to backup the original firmware (if any).
+
+## Code submission
+
+Here's a checklist for new mainboard ports:
+
+1. Try to not duplicate code, use variants scheme instead.
+2. Split changes logical into top level directories:
+ `src/mainboard` , `src/northbridge`, `src/ec`, ...
+3. Provide good documentation, see point 4
+4. In the commit message describe as much as possible or point to the
+ documentation, satisfying the following questions:
+ * Where's the flash IC located?
+ * Can you flash incircuit?
+ * Are there pinheaders for flashing?
+ * Is the flash hardware write-protected?
+ * Which flash IC is usually equipped?
+ * If the board features an BMC, can it be used for developing and
+ debugging?
+ * What was tested and is working?
+ * What was tested and isn't working?
+ * What wasn't tested (due to lack of testing equipment)?
+ * Are blobs necessary?
+ * How can the board be debugged?
+ * Are there serial, EHCI debug, xHCI debug or BMC connections?
+ * Does it have a SuperIO?
+
+ In addition please descibe:
+ * How to retrieve blobs, like dumping them from vendor firmware
+
+ See [Writing Documentation] for more details.
+
+5. What you should **not** document:
+ * Steps or instructions how to flash the board
+ * Steps or instructions how to use a specific application for flashing
+ * Please do not provide pictures of the whole board or it's backplate
+ connectors
+6. Recommand a flashing method as descibed in [Flashing tutorial]
+7. If you are working at/for a hardware vendor, please provide free board
+ schematics as well.
+8. Provide a picture of the flash IC or flash connector.
+ * The picture should be less than 800pc in width and compressed with
+ 70% compression to reduce size.
+ * You must own the Copyright
+ * Try to cut of uninteresting parts of the image, like tables, cables, ...
+
+Once done submit your board to Gerrit. Please follow the [Gerrit Guidelines] as
+well.
+
+[Writing Documentation]: writing_documentation.md
+[Flashing tutorial]: ../flash_tutorial/index.md
+[Gerrit Guidelines]: gerrit_guidelines.md
diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md
index fb942a4..0b820fc 100644
--- a/Documentation/getting_started/writing_documentation.md
+++ b/Documentation/getting_started/writing_documentation.md
@@ -49,6 +49,8 @@
the current theme doesn't allow bigger images.
12. Shouldn't cover implementation details; for details, the code is the
reference.
+13. New mainboard ports should also add documentation. See
+ [Adding new mainboards] for more details.
## Referencing markdown documents
@@ -122,3 +124,4 @@
[Markdown Guide]: https://www.markdownguide.org/
[Gerrit Guidelines]: gerrit_guidelines.md
[review.coreboot.org]: https://review.coreboot.org
+[Adding new mainboards]: new_mainboard_ports.md
--
To view, visit https://review.coreboot.org/c/coreboot/+/34632
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I134dbf2341696ba0dd33c3d52bf787b8eaabbdab
Gerrit-Change-Number: 34632
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <siro(a)das-labor.org>
Gerrit-MessageType: newchange