/: Update and rewrite README.md

Update the top level readme file to reflect the updated documentation
and project status.

This is mostly a rewrite, but some text was just reformatted.

Signed-off-by: Martin Roth <gaumless@gmail.com>
Change-Id: I2cd59d75da47b287029a9fc5eeddefaf99198965
Reviewed-on: https://review.coreboot.org/c/coreboot/+/67119
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>

1 files changed, 151 insertions, 56 deletions

diff --git a/README.md b/README.md
index 0f0b2fdfee61..18f5789a729d 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,41 @@
 coreboot README
 ===============
 
-coreboot is a Free Software project aimed at replacing the proprietary BIOS
-(firmware) found in most computers.  coreboot performs a little bit of
-hardware initialization and then executes additional boot logic, called a
-payload.
+coreboot is a Free Software project aimed at replacing the proprietary
+firmware (BIOS/UEFI) found in most computers. coreboot performs the
+required hardware initialization to configure the system, then passes
+control to a different executable, referred to in coreboot as the
+payload. Most often, the primary function of the payload is to boot the
+operating system (OS).
 
 With the separation of hardware initialization and later boot logic,
-coreboot can scale from specialized applications that run directly
-firmware, run operating systems in flash, load custom
-bootloaders, or implement firmware standards, like PC BIOS services or
-UEFI. This allows for systems to only include the features necessary
-in the target application, reducing the amount of code and flash space
-required.
+coreboot is perfect for a wide variety of situations. It can be used
+for specialized applications that run directly in the firmware, running
+operating systems from flash, loading custom bootloaders, or
+implementing firmware standards, like PC BIOS services or UEFI. This
+flexibility allows coreboot systems to include only the features
+necessary in the target application, reducing the amount of code and
+flash space required.
 
-coreboot was formerly known as LinuxBIOS.
 
+Source code
+-----------
+
+All source code for coreboot is stored in git. It is downloaded with
+the command:
+
+`git clone https://review.coreboot.org/coreboot.git`.
+
+Code reviews are done in [the project's Gerrit
+instance](https://review.coreboot.org/).
+
+The code may be browsed via [coreboot's Gitiles
+instance](https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master).
+
+The coreboot project also maintains a
+[mirror](https://github.com/coreboot/coreboot) of the project on github.
+This is read-only, as coreboot does not accept github pull requests,
+but allows browsing and downloading the coreboot source.
 
 Payloads
 --------
@@ -23,63 +43,70 @@ Payloads
 After the basic initialization of the hardware has been performed, any
 desired "payload" can be started by coreboot.
 
-See <https://www.coreboot.org/Payloads> for a list of supported payloads.
+See <https://doc.coreboot.org/payloads.html> for a list of some of
+coreboot's supported payloads.
 
 
 Supported Hardware
 ------------------
 
-coreboot supports a wide range of chipsets, devices, and mainboards.
-
-For details please consult:
-
- * <https://www.coreboot.org/Supported_Motherboards>
-
+The coreboot project supports a wide range of architectures, chipsets,
+devices, and mainboards. While not all of these are documented, you can
+find some information in the [Architecture-specific
+documentation](https://doc.coreboot.org/arch/index.html) or the
+[SOC-specific documentation](https://doc.coreboot.org/soc/index.html).
 
-Build Requirements
-------------------
-
- * make
- * gcc / g++
-   Because Linux distribution compilers tend to use lots of patches. coreboot
-   does lots of "unusual" things in its build system, some of which break due
-   to those patches, sometimes by gcc aborting, sometimes - and that's worse -
-   by generating broken object code.
-   Two options: use our toolchain (eg. make crosstools-i386) or enable the
-   `ANY_TOOLCHAIN` Kconfig option if you're feeling lucky (no support in this
-   case).
- * iasl (for targets with ACPI support)
- * pkg-config
- * libssl-dev (openssl)
+For details about the specific mainboard devices that coreboot supports,
+please consult the [Mainboard-specific
+documentation](https://doc.coreboot.org/mainboard/index.html) or the
+[Board Status](https://coreboot.org/status/board-status.html) pages.
 
-Optional:
 
-  * gdb (for better debugging facilities on some targets)
- * ncurses (for `make menuconfig` and `make nconfig`)
- * flex and bison (for regenerating parsers)
+Releases
+--------
 
+Releases are currently done by coreboot every quarter. The
+release archives contain the entire coreboot codebase from the time of
+the release, along with any external submodules. The submodules
+containing binaries are separated from the general release archives. All
+of the packages required to build the coreboot toolchains are also kept
+at coreboot.org in case the websites change, or those specific packages
+become unavailable in the future.
 
-Building coreboot
------------------
+All releases are available on the [coreboot
+download](https://coreboot.org/downloads.html) page.
 
-Please consult <https://www.coreboot.org/Build_HOWTO> for details.
+Please note that the coreboot releases are best considered as snapshots
+of the codebase, and do not currently guarantee any sort of extra
+stability.
 
+Build Requirements and building coreboot
+----------------------------------------
 
-Testing coreboot Without Modifying Your Hardware
-------------------------------------------------
+The coreboot build, associated utilities and payloads require many
+additional tools and packages to build. The actual coreboot binary is
+typically built using a coreboot-controlled toolchain to provide
+reproducibility across various platforms. It is also possible, though
+not recommended, to make it directly with your system toolchain.
+Operating systems and distributions come with an unknown variety of
+system tools and utilities installed. Because of this, it isn't
+reasonable to list all the required packages to do a build, but the
+documentation lists the requirements for a few different Linux
+distributions.
 
-If you want to test coreboot without any risks before you really decide
-to use it on your hardware, you can use the QEMU system emulator to run
-coreboot virtually in QEMU.
+To see the list of tools and libraries, along with a list of
+instructions to get started building coreboot, go to the [Starting from
+scratch](https://doc.coreboot.org/tutorial/part1.html) tutorial page.
 
-Please see <https://www.coreboot.org/QEMU> for details.
+That same page goes through how to use QEMU to boot the build and see
+the output.
 
 
 Website and Mailing List
 ------------------------
 
-Further details on the project, a FAQ, many HOWTOs, news, development
-guidelines and more can be found on the coreboot website:
+Further details on the project, as well as links to documentation and
+more can be found on the coreboot website:
 
   <https://www.coreboot.org>
 
@@ -88,16 +115,84 @@ You can contact us directly on the coreboot mailing list:
   <https://www.coreboot.org/Mailinglist>
 
 
-Copyright and License
+
+Copyrights and Licenses
 ---------------------
 
+
+### Uncopyrightable files
+
+There are many files in the coreboot tree that we feel are not
+copyrightable due to a lack of creative content.
+
+"In order to qualify for copyright protection in the United States, a
+work must satisfy the originality requirement, which has two parts. The
+work must have “at least a modicum” of creativity, and it must be the
+independent creation of its author."
+
+  <https://guides.lib.umich.edu/copyrightbasics/copyrightability>
+
+Similar terms apply to other locations.
+
+These uncopyrightable files include:
+
+- Empty files or files with only a comment explaining their existence.
+  These may be required to exist as part of the build process but are
+  not needed for the particular project.
+- Configuration files either in binary or text form. Examples would be
+  files such as .vbt files describing graphics configuration, spd files
+  as binary .spd or text \*spd\*.hex representing memory chip
+  configuration.
+- Machine-generated files containing version numbers, dates, hash
+  values or other "non-creative" content.
+
+As non-creative content, these files are in the public domain by
+default.  As such, the coreboot project excludes them from the project's
+general license even though they may be included in a final binary.
+
+If there are questions or concerns about this policy, please get in
+touch with the coreboot project via the mailing list.
+
+
+### Copyrights
+
 The copyright on coreboot is owned by quite a large number of individual
-developers and companies. Please check the individual source files for details.
+developers and companies. A list of companies and individuals with known
+copyright claims is present at the top level of the coreboot source tree
+in the 'AUTHORS' file. Please check the git history of each of the
+source files for details.
+
+
+### Licenses
+
+Because of the way coreboot began, using a significant amount of source
+code from the Linux kernel, it's licensed the same way as the Linux
+Kernel, with GNU General Public License (GPL) Version 2. Individual
+files are licensed under various licenses, though all are compatible
+with GPLv2. The resulting coreboot image is licensed under the GPL,
+version 2. All source files should have an SPDX license identifier at
+the top for clarification.
+
+Files under coreboot/Documentation/ are licensed under CC-BY 4.0 terms.
+As an exception, files under Documentation/ with a history older than
+2017-05-24 might be under different licenses.
+
+Files in the coreboot/src/commonlib/bsd directory are all licensed with
+the BSD-3-clause license.  Many are also dual-licensed GPL-2.0-only or
+GPL-2.0-or-later.  These files are intended to be shared with libpayload
+or other BSD licensed projects.
+
+The libpayload project contained in coreboot/payloads/libpayload may be
+licensed as BSD or GPL, depending on the code pulled in during the build
+process. All GPL source code should be excluded unless the Kconfig
+option to include it is set.
+
 
-coreboot is licensed under the terms of the GNU General Public License (GPL).
-Some files are licensed under the "GPL (version 2, or any later version)",
-and some files are licensed under the "GPL, version 2". For some parts, which
-were derived from other projects, other (GPL-compatible) licenses may apply.
-Please check the individual source files for details.
+The Software Freedom Conservancy
+--------------------------------
 
-This makes the resulting coreboot images licensed under the GPL, version 2.
+Since 2017, coreboot has been a member of [The Software Freedom
+Conservancy](https://sfconservancy.org/), a nonprofit organization
+devoted to ethical technology and driving initiatives to make technology
+more inclusive. The conservancy acts as coreboot's fiscal sponsor and
+legal advisor.