README.md

   1 coreboot README
   2 ===============
   3
   4 coreboot is a Free Software project aimed at replacing the proprietary
   5 firmware (BIOS/UEFI) found in most computers. coreboot performs the
   6 required hardware initialization to configure the system, then passes
   7 control to a different executable, referred to in coreboot as the
   8 payload. Most often, the primary function of the payload is to boot the
   9 operating system (OS).
  10
  11 With the separation of hardware initialization and later boot logic,
  12 coreboot is perfect for a wide variety of situations. It can be used
  13 for specialized applications that run directly in the firmware, running
  14 operating systems from flash, loading custom bootloaders, or
  15 implementing firmware standards, like PC BIOS services or UEFI. This
  16 flexibility allows coreboot systems to include only the features
  17 necessary in the target application, reducing the amount of code and
  18 flash space required.
  19
  20
  21 Source code
  22 -----------
  23
  24 All source code for coreboot is stored in git. It is downloaded with
  25 the command:
  26
  27 `git clone https://review.coreboot.org/coreboot.git`.
  28
  29 Code reviews are done in [the project's Gerrit
  30 instance](https://review.coreboot.org/).
  31
  32 The code may be browsed via [coreboot's Gitiles
  33 instance](https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master).
  34
  35 The coreboot project also maintains a
  36 [mirror](https://github.com/coreboot/coreboot) of the project on github.
  37 This is read-only, as coreboot does not accept github pull requests,
  38 but allows browsing and downloading the coreboot source.
  39
  40 Payloads
  41 --------
  42
  43 After the basic initialization of the hardware has been performed, any
  44 desired "payload" can be started by coreboot.
  45
  46 See <https://doc.coreboot.org/payloads.html> for a list of some of
  47 coreboot's supported payloads.
  48
  49
  50 Supported Hardware
  51 ------------------
  52
  53 The coreboot project supports a wide range of architectures, chipsets,
  54 devices, and mainboards. While not all of these are documented, you can
  55 find some information in the [Architecture-specific
  56 documentation](https://doc.coreboot.org/arch/index.html) or the
  57 [SOC-specific documentation](https://doc.coreboot.org/soc/index.html).
  58
  59 For details about the specific mainboard devices that coreboot supports,
  60 please consult the [Mainboard-specific
  61 documentation](https://doc.coreboot.org/mainboard/index.html) or the
  62 [Board Status](https://coreboot.org/status/board-status.html) pages.
  63
  64
  65 Releases
  66 --------
  67
  68 Releases are currently done by coreboot every quarter. The
  69 release archives contain the entire coreboot codebase from the time of
  70 the release, along with any external submodules. The submodules
  71 containing binaries are separated from the general release archives. All
  72 of the packages required to build the coreboot toolchains are also kept
  73 at coreboot.org in case the websites change, or those specific packages
  74 become unavailable in the future.
  75
  76 All releases are available on the [coreboot
  77 download](https://coreboot.org/downloads.html) page.
  78
  79 Please note that the coreboot releases are best considered as snapshots
  80 of the codebase, and do not currently guarantee any sort of extra
  81 stability.
  82
  83 Build Requirements and building coreboot
  84 ----------------------------------------
  85
  86 The coreboot build, associated utilities and payloads require many
  87 additional tools and packages to build. The actual coreboot binary is
  88 typically built using a coreboot-controlled toolchain to provide
  89 reproducibility across various platforms. It is also possible, though
  90 not recommended, to make it directly with your system toolchain.
  91 Operating systems and distributions come with an unknown variety of
  92 system tools and utilities installed. Because of this, it isn't
  93 reasonable to list all the required packages to do a build, but the
  94 documentation lists the requirements for a few different Linux
  95 distributions.
  96
  97 To see the list of tools and libraries, along with a list of
  98 instructions to get started building coreboot, go to the [Starting from
  99 scratch](https://doc.coreboot.org/tutorial/part1.html) tutorial page.
 100
 101 That same page goes through how to use QEMU to boot the build and see
 102 the output.
 103
 104
 105 Website and Mailing List
 106 ------------------------
 107
 108 Further details on the project, as well as links to documentation and
 109 more can be found on the coreboot website:
 110
 111   <https://www.coreboot.org>
 112
 113 You can contact us directly on the coreboot mailing list:
 114
 115   <https://doc.coreboot.org/community/forums.html>
 116
 117
 118
 119 Copyrights and Licenses
 120 ---------------------
 121
 122
 123 ### Uncopyrightable files
 124
 125 There are many files in the coreboot tree that we feel are not
 126 copyrightable due to a lack of creative content.
 127
 128 "In order to qualify for copyright protection in the United States, a
 129 work must satisfy the originality requirement, which has two parts. The
 130 work must have “at least a modicum” of creativity, and it must be the
 131 independent creation of its author."
 132
 133   <https://guides.lib.umich.edu/copyrightbasics/copyrightability>
 134
 135 Similar terms apply to other locations.
 136
 137 These uncopyrightable files include:
 138
 139 - Empty files or files with only a comment explaining their existence.
 140   These may be required to exist as part of the build process but are
 141   not needed for the particular project.
 142 - Configuration files either in binary or text form. Examples would be
 143   files such as .vbt files describing graphics configuration, spd files
 144   as binary .spd or text \*spd\*.hex representing memory chip
 145   configuration.
 146 - Machine-generated files containing version numbers, dates, hash
 147   values or other "non-creative" content.
 148
 149 As non-creative content, these files are in the public domain by
 150 default.  As such, the coreboot project excludes them from the project's
 151 general license even though they may be included in a final binary.
 152
 153 If there are questions or concerns about this policy, please get in
 154 touch with the coreboot project via the mailing list.
 155
 156
 157 ### Copyrights
 158
 159 The copyright on coreboot is owned by quite a large number of individual
 160 developers and companies. A list of companies and individuals with known
 161 copyright claims is present at the top level of the coreboot source tree
 162 in the 'AUTHORS' file. Please check the git history of each of the
 163 source files for details.
 164
 165
 166 ### Licenses
 167
 168 Because of the way coreboot began, using a significant amount of source
 169 code from the Linux kernel, it's licensed the same way as the Linux
 170 Kernel, with GNU General Public License (GPL) Version 2. Individual
 171 files are licensed under various licenses, though all are compatible
 172 with GPLv2. The resulting coreboot image is licensed under the GPL,
 173 version 2. All source files should have an SPDX license identifier at
 174 the top for clarification.
 175
 176 Files under coreboot/Documentation/ are licensed under CC-BY 4.0 terms.
 177 As an exception, files under Documentation/ with a history older than
 178 2017-05-24 might be under different licenses.
 179
 180 Files in the coreboot/src/commonlib/bsd directory are all licensed with
 181 the BSD-3-clause license.  Many are also dual-licensed GPL-2.0-only or
 182 GPL-2.0-or-later.  These files are intended to be shared with libpayload
 183 or other BSD licensed projects.
 184
 185 The libpayload project contained in coreboot/payloads/libpayload may be
 186 licensed as BSD or GPL, depending on the code pulled in during the build
 187 process. All GPL source code should be excluded unless the Kconfig
 188 option to include it is set.
 189
 190
 191 The Software Freedom Conservancy
 192 --------------------------------
 193
 194 Since 2017, coreboot has been a member of [The Software Freedom
 195 Conservancy](https://sfconservancy.org/), a nonprofit organization
 196 devoted to ethical technology and driving initiatives to make technology
 197 more inclusive. The conservancy acts as coreboot's fiscal sponsor and
 198 legal advisor.