From 2db459edb0936bbaf874f40a96e98cdfc6d5d5ce Mon Sep 17 00:00:00 2001 From: Martin Roth Date: Fri, 26 Aug 2022 18:20:46 -0600 Subject: [PATCH] /: 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 Change-Id: I2cd59d75da47b287029a9fc5eeddefaf99198965 Reviewed-on: https://review.coreboot.org/c/coreboot/+/67119 Tested-by: build bot (Jenkins) Reviewed-by: Elyes Haouas --- README.md | 207 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 151 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 0f0b2fdfee..18f5789a72 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 for a list of supported payloads. +See for a list of some of +coreboot's supported payloads. Supported Hardware ------------------ -coreboot supports a wide range of chipsets, devices, and mainboards. +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). -For details please consult: - - * +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. -Build Requirements ------------------- +Releases +-------- - * 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) +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. -Optional: +All releases are available on the [coreboot +download](https://coreboot.org/downloads.html) page. - * gdb (for better debugging facilities on some targets) - * ncurses (for `make menuconfig` and `make nconfig`) - * flex and bison (for regenerating parsers) +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 +---------------------------------------- -Building coreboot ------------------ +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. -Please consult for details. +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. - -Testing coreboot Without Modifying Your Hardware ------------------------------------------------- - -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. - -Please see 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: @@ -88,16 +115,84 @@ You can contact us directly on the coreboot mailing list: -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." + + + +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. -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. -This makes the resulting coreboot images licensed under the GPL, version 2. +### 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. + + +The Software Freedom Conservancy +-------------------------------- + +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.