/: 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:
Martin Roth
Martin L Roth
parent
4faa72f39a
commit
2db459edb0
207
README.md
207
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.
|
||||
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:
|
||||
|
||||
* <https://www.coreboot.org/Supported_Motherboards>
|
||||
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 <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.
|
||||
|
||||
|
||||
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 <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.
|
||||
|
||||
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