/: 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>
This commit is contained in:
parent
4faa72f39a
commit
2db459edb0
207
README.md
207
README.md
|
@ -1,21 +1,41 @@
|
||||||
coreboot README
|
coreboot README
|
||||||
===============
|
===============
|
||||||
|
|
||||||
coreboot is a Free Software project aimed at replacing the proprietary BIOS
|
coreboot is a Free Software project aimed at replacing the proprietary
|
||||||
(firmware) found in most computers. coreboot performs a little bit of
|
firmware (BIOS/UEFI) found in most computers. coreboot performs the
|
||||||
hardware initialization and then executes additional boot logic, called a
|
required hardware initialization to configure the system, then passes
|
||||||
payload.
|
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,
|
With the separation of hardware initialization and later boot logic,
|
||||||
coreboot can scale from specialized applications that run directly
|
coreboot is perfect for a wide variety of situations. It can be used
|
||||||
firmware, run operating systems in flash, load custom
|
for specialized applications that run directly in the firmware, running
|
||||||
bootloaders, or implement firmware standards, like PC BIOS services or
|
operating systems from flash, loading custom bootloaders, or
|
||||||
UEFI. This allows for systems to only include the features necessary
|
implementing firmware standards, like PC BIOS services or UEFI. This
|
||||||
in the target application, reducing the amount of code and flash space
|
flexibility allows coreboot systems to include only the features
|
||||||
required.
|
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
|
Payloads
|
||||||
--------
|
--------
|
||||||
|
@ -23,63 +43,70 @@ Payloads
|
||||||
After the basic initialization of the hardware has been performed, any
|
After the basic initialization of the hardware has been performed, any
|
||||||
desired "payload" can be started by coreboot.
|
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
|
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
|
||||||
* <https://www.coreboot.org/Supported_Motherboards>
|
documentation](https://doc.coreboot.org/mainboard/index.html) or the
|
||||||
|
[Board Status](https://coreboot.org/status/board-status.html) pages.
|
||||||
|
|
||||||
|
|
||||||
Build Requirements
|
Releases
|
||||||
------------------
|
--------
|
||||||
|
|
||||||
* make
|
Releases are currently done by coreboot every quarter. The
|
||||||
* gcc / g++
|
release archives contain the entire coreboot codebase from the time of
|
||||||
Because Linux distribution compilers tend to use lots of patches. coreboot
|
the release, along with any external submodules. The submodules
|
||||||
does lots of "unusual" things in its build system, some of which break due
|
containing binaries are separated from the general release archives. All
|
||||||
to those patches, sometimes by gcc aborting, sometimes - and that's worse -
|
of the packages required to build the coreboot toolchains are also kept
|
||||||
by generating broken object code.
|
at coreboot.org in case the websites change, or those specific packages
|
||||||
Two options: use our toolchain (eg. make crosstools-i386) or enable the
|
become unavailable in the future.
|
||||||
`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)
|
|
||||||
|
|
||||||
Optional:
|
All releases are available on the [coreboot
|
||||||
|
download](https://coreboot.org/downloads.html) page.
|
||||||
|
|
||||||
* gdb (for better debugging facilities on some targets)
|
Please note that the coreboot releases are best considered as snapshots
|
||||||
* ncurses (for `make menuconfig` and `make nconfig`)
|
of the codebase, and do not currently guarantee any sort of extra
|
||||||
* flex and bison (for regenerating parsers)
|
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 <https://www.coreboot.org/Build_HOWTO> 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.
|
||||||
|
|
||||||
|
That same page goes through how to use QEMU to boot the build and see
|
||||||
Testing coreboot Without Modifying Your Hardware
|
the output.
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
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 <https://www.coreboot.org/QEMU> for details.
|
|
||||||
|
|
||||||
|
|
||||||
Website and Mailing List
|
Website and Mailing List
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
Further details on the project, a FAQ, many HOWTOs, news, development
|
Further details on the project, as well as links to documentation and
|
||||||
guidelines and more can be found on the coreboot website:
|
more can be found on the coreboot website:
|
||||||
|
|
||||||
<https://www.coreboot.org>
|
<https://www.coreboot.org>
|
||||||
|
|
||||||
|
@ -88,16 +115,84 @@ You can contact us directly on the coreboot mailing list:
|
||||||
<https://www.coreboot.org/Mailinglist>
|
<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
|
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.
|
||||||
|
|
Loading…
Reference in New Issue