Change in ...coreboot[master]: Documentation: Describe our ecosystem

[Patrick Georgi (Code Review)]

Patrick Georgi has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/31180

Change subject: Documentation: Describe our ecosystem
......................................................................

Documentation: Describe our ecosystem

Neither payloads nor distributors are an integral part of the coreboot
source tree, but they're very important parts of the coreboot
ecosystems, so add some descriptions.

Change-Id: Id64744c252b6b78c4811fbded48c441ef486ad94
Signed-off-by: Patrick Georgi 
---
A Documentation/distributions.md
M Documentation/index.md
A Documentation/payloads.md
3 files changed, 90 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/80/31180/1

diff --git a/Documentation/distributions.md b/Documentation/distributions.md
new file mode 100644
index 0000000..788e808
--- /dev/null
+++ b/Documentation/distributions.md
@@ -0,0 +1,46 @@
+# Distributions
+
+coreboot doesn't provide binaries but provides a toolbox that others can use
+to build boot firmware for all kinds of purposes. These third-parties can be
+broadly separated in two groups: Those shipping coreboot on their hardware,
+and those providing after-market firmware to extend the usefulness of devices.
+
+## Shipping coreboot on hardware
+
+### Purism
+
+[Purism](https://www.puri.sm) sells laptops with a focus on privacy and
+part of that is their push to remove as much unaccounted code (that is,
+binary only) from their devices as possible.
+
+### Chromebooks
+
+All Chromebooks (and related devices) that hit the market after 2013 are
+using coreboot as their main firmware. And even the Embedded Controller,
+a small microcontroller to support various periphery (like battery
+management or the keyboard) is running open source firmware.
+
+
+## After-market firmware
+
+### Libreboot
+
+[Libreboot](https://libreboot.org) is a project that provides ready-made
+binaries for platforms where those can be built entirely from source
+code. Their copy of the coreboot repository is therefore stripped of
+all devices that require binary components to boot.
+
+### John Lewis
+
+[John Lewis](https://johnlewis.ie/custom-chromebook-firmware) provides
+replacement firmware for some Chromebooks. Why replace coreboot with
+coreboot?  You might want to do different things than what the Google
+engineers prepared for the mass market, that's why. This firmware is
+"with training wheels off".
+
+### Mr. Chromebox
+
+[Matt Devo](https://mrchromebox.tech/) also provides replacements for
+Chromebook firmware, for the same reasons as John Lewis. It's a somewhat
+different set of devices, and with different configurations, so check
+out both if Chromebooks are what you're dealing with.
diff --git a/Documentation/index.md b/Documentation/index.md
index af3886e..c5bfa9b 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -13,6 +13,8 @@
 * [Code of Conduct](community/code_of_conduct.md)
 * [Community forums](community/forums.md)
 * [coreboot at conferences](community/conferences.md)
+* [Payloads](payloads.md)
+* [Distributions](distributions.md)
 * [Timestamps](timestamp.md)
 * [Intel IFD Binary Extraction](Binary_Extraction.md)
 * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
diff --git a/Documentation/payloads.md b/Documentation/payloads.md
new file mode 100644
index 0000000..b1eae61
--- /dev/null
+++ b/Documentation/payloads.md
@@ -0,0 +1,42 @@
+# Payloads
+
+coreboot doesn't try to mandate how the boot process should look, it merely
+does hardware init and then passes on control to another piece of software
+that we carry along in firmware storage, the _payload_.
+
+There is various software in that space that is either explicitly written as
+payload or can be made to work as one.
+
+## SeaBIOS
+
+[SeaBIOS](https://www.seabios.org) is an open source implementation of
+the PCBIOS API that exists since the original IBM PC and was extended
+since. While originally written for emulators such as QEMU, it can be made
+to work as a coreboot payload and all the necessary code is in SeaBIOS'
+mainline code.
+
+## Tianocore
+
+[Tianocore](https://www.tianocore.org) is the open source reference
+implementation of the UEFI Specifications that modern firmware for PCs is
+based on. There were various projects in the past to make it suitable as a
+coreboot payload, but these days this function is available directly in the
+CorebootPayloadPkg part of its source tree.
+
+## GRUB2
+
+GRUB2 was originally written as a bootloader and that's its most popular
+purpose, but it can also be compiled as a coreboot payload.
+
+## Linux
+
+There are several projects using Linux as a payload (which was the
+configuration that gave coreboot its original name, LinuxBIOS). That kernel is
+often rather small and serves to load a current kernel from somewhere, e.g.
+disk or network, and run that through the kexec mechanism.
+
+Two aspects emphasized by proponents of Linux-as-a-payload are the
+availability of well-tested, battle-hardened drivers (as compared to
+firmware project drivers that often reinvent the wheel) and the ability to
+define boot policy with familiar tools, no matter if those are shell scripts
+or compiled userland programs written in C, Go or other programming languages.

[Angel Pons (Code Review)]

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

Change subject: Documentation: Describe our ecosystem
......................................................................

Patch Set 2: Code-Review+1

(2 comments)

Looks pretty good!

https://review.coreboot.org/#/c/31180/2/Documentation/distributions.md 
File Documentation/distributions.md:

https://review.coreboot.org/#/c/31180/2/Documentation/distributions.md@20 
PS2, Line 20: periphery
peripherals

https://review.coreboot.org/#/c/31180/2/Documentation/distributions.md@41 
PS2, Line 41: ### Mr. Chromebox
IMHO, taking into account MrChromebox is much more active regarding coreboot development, I would consider placing this entry above John Lewis.

[Patrick Georgi (Code Review)]

Hello Angel Pons, Matt DeVillier, build bot (Jenkins),

I'd like you to reexamine a change. Please visit

https://review.coreboot.org/c/coreboot/+/31180

to look at the new patch set (#3).

Change subject: Documentation: Describe our ecosystem
......................................................................

Documentation: Describe our ecosystem

Neither payloads nor distributors are an integral part of the coreboot
source tree, but they're very important parts of the coreboot
ecosystems, so add some descriptions.

Change-Id: Id64744c252b6b78c4811fbded48c441ef486ad94
Signed-off-by: Patrick Georgi 
---
A Documentation/distributions.md
M Documentation/index.md
A Documentation/payloads.md
3 files changed, 90 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/80/31180/3

[Patrick Georgi (Code Review)]

Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31180 )

Change subject: Documentation: Describe our ecosystem
......................................................................

Patch Set 3:

(2 comments)

https://review.coreboot.org/#/c/31180/2/Documentation/distributions.md 
File Documentation/distributions.md:

https://review.coreboot.org/#/c/31180/2/Documentation/distributions.md@20 
PS2, Line 20: periphery
> peripherals

Done

https://review.coreboot.org/#/c/31180/2/Documentation/distributions.md@41 
PS2, Line 41: ### Mr. Chromebox
> IMHO, taking into account MrChromebox is much more active regarding coreboot development, I would co […]

Ack

[Angel Pons (Code Review)]

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

Change subject: Documentation: Describe our ecosystem
......................................................................

Patch Set 3: Code-Review+1

Should we describe the secondary payloads too?

[Patrick Georgi (Code Review)]

Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31180 )

Change subject: Documentation: Describe our ecosystem
......................................................................

Patch Set 3:
> Patch Set 3: Code-Review+1
>
> Should we describe the secondary payloads too?

potentially, but later. patches accepted :-)

I'm mostly trying to build a doc site scaffold that's more friendly to newcomers, and therefore I'm adding various categories and concepts that I think we should talk about and explain. All of that can be expanded, but right now I think this covers >70% of users and outlines all use cases (standard API implementations, specialist implementations, linux-as-firmware).

I guess we could mention tint (https://www.coreboot.org/Tint) and grub invaders (https://www.coreboot.org/GRUB_invaders) as speciment of another category: app-in-firmware ;-)

[Arthur Heymans (Code Review)]

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

Change subject: Documentation: Describe our ecosystem
......................................................................

Patch Set 3: Code-Review+2
> Patch Set 3: Code-Review+1
>
> Should we describe the secondary payloads too?

I'd say less is more in this case. I suppose the purpose is to give an overview of the ecosystem in which a few important examples are given as opposed to a more exhaustive list of less used or niche payloads.

[Angel Pons (Code Review)]

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

Change subject: Documentation: Describe our ecosystem
......................................................................

Patch Set 3: Code-Review+2

Alright, makes sense.

[Patrick Georgi (Code Review)]

Patrick Georgi has submitted this change and it was merged. ( https://review.coreboot.org/c/coreboot/+/31180 )

Change subject: Documentation: Describe our ecosystem
......................................................................

Documentation: Describe our ecosystem

Neither payloads nor distributors are an integral part of the coreboot
source tree, but they're very important parts of the coreboot
ecosystems, so add some descriptions.

Change-Id: Id64744c252b6b78c4811fbded48c441ef486ad94
Signed-off-by: Patrick Georgi 
Reviewed-on: https://review.coreboot.org/c/31180
Tested-by: build bot (Jenkins) 
Reviewed-by: Arthur Heymans 
Reviewed-by: Angel Pons 
---
A Documentation/distributions.md
M Documentation/index.md
A Documentation/payloads.md
3 files changed, 90 insertions(+), 0 deletions(-)

Approvals:
  build bot (Jenkins): Verified
  Arthur Heymans: Looks good to me, approved
  Angel Pons: Looks good to me, approved

diff --git a/Documentation/distributions.md b/Documentation/distributions.md
new file mode 100644
index 0000000..837a744
--- /dev/null
+++ b/Documentation/distributions.md
@@ -0,0 +1,46 @@
+# Distributions
+
+coreboot doesn't provide binaries but provides a toolbox that others can use
+to build boot firmware for all kinds of purposes. These third-parties can be
+broadly separated in two groups: Those shipping coreboot on their hardware,
+and those providing after-market firmware to extend the usefulness of devices.
+
+## Shipping coreboot on hardware
+
+### Purism
+
+[Purism](https://www.puri.sm) sells laptops with a focus on privacy and
+part of that is their push to remove as much unaccounted code (that is,
+binary only) from their devices as possible.
+
+### Chromebooks
+
+All Chromebooks (and related devices) that hit the market after 2013 are
+using coreboot as their main firmware. And even the Embedded Controller,
+a small microcontroller to support various peripherals (like battery
+management or the keyboard) is running open source firmware.
+
+
+## After-market firmware
+
+### Libreboot
+
+[Libreboot](https://libreboot.org) is a project that provides ready-made
+binaries for platforms where those can be built entirely from source
+code. Their copy of the coreboot repository is therefore stripped of
+all devices that require binary components to boot.
+
+### Mr. Chromebox
+
+[Matt Devo](https://mrchromebox.tech/) provides replacement firmware for
+various Chromebooks. Why replace coreboot with coreboot?  You might want
+to do different things than what the Google engineers prepared for the
+mass market, that's why. This firmware is "with training wheels off".
+
+### John Lewis
+
+[John Lewis](https://johnlewis.ie/custom-chromebook-firmware) also
+provides replacements for Chromebook firmware, for the same reasons
+as Mr. Chromebox. It's a somewhat different set of devices, and with
+different configurations, so check out both if Chromebooks are what
+you're dealing with.
diff --git a/Documentation/index.md b/Documentation/index.md
index af3886e..c5bfa9b 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -13,6 +13,8 @@
 * [Code of Conduct](community/code_of_conduct.md)
 * [Community forums](community/forums.md)
 * [coreboot at conferences](community/conferences.md)
+* [Payloads](payloads.md)
+* [Distributions](distributions.md)
 * [Timestamps](timestamp.md)
 * [Intel IFD Binary Extraction](Binary_Extraction.md)
 * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
diff --git a/Documentation/payloads.md b/Documentation/payloads.md
new file mode 100644
index 0000000..b1eae61
--- /dev/null
+++ b/Documentation/payloads.md
@@ -0,0 +1,42 @@
+# Payloads
+
+coreboot doesn't try to mandate how the boot process should look, it merely
+does hardware init and then passes on control to another piece of software
+that we carry along in firmware storage, the _payload_.
+
+There is various software in that space that is either explicitly written as
+payload or can be made to work as one.
+
+## SeaBIOS
+
+[SeaBIOS](https://www.seabios.org) is an open source implementation of
+the PCBIOS API that exists since the original IBM PC and was extended
+since. While originally written for emulators such as QEMU, it can be made
+to work as a coreboot payload and all the necessary code is in SeaBIOS'
+mainline code.
+
+## Tianocore
+
+[Tianocore](https://www.tianocore.org) is the open source reference
+implementation of the UEFI Specifications that modern firmware for PCs is
+based on. There were various projects in the past to make it suitable as a
+coreboot payload, but these days this function is available directly in the
+CorebootPayloadPkg part of its source tree.
+
+## GRUB2
+
+GRUB2 was originally written as a bootloader and that's its most popular
+purpose, but it can also be compiled as a coreboot payload.
+
+## Linux
+
+There are several projects using Linux as a payload (which was the
+configuration that gave coreboot its original name, LinuxBIOS). That kernel is
+often rather small and serves to load a current kernel from somewhere, e.g.
+disk or network, and run that through the kexec mechanism.
+
+Two aspects emphasized by proponents of Linux-as-a-payload are the
+availability of well-tested, battle-hardened drivers (as compared to
+firmware project drivers that often reinvent the wheel) and the ability to
+define boot policy with familiar tools, no matter if those are shell scripts
+or compiled userland programs written in C, Go or other programming languages.