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/+/HEAD).
  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, .apcb
 144   files containing configuration parameters for AMD firmware binaries,
 145   and spd files as binary .spd or text \*spd\*.hex representing memory
 146   chip configuration.
 147 - Machine-generated files containing version numbers, dates, hash
 148   values or other "non-creative" content.
 149
 150 As non-creative content, these files are in the public domain by
 151 default.  As such, the coreboot project excludes them from the project's
 152 general license even though they may be included in a final binary.
 153
 154 If there are questions or concerns about this policy, please get in
 155 touch with the coreboot project via the mailing list.
 156
 157
 158 ### Copyrights
 159
 160 The copyright on coreboot is owned by quite a large number of individual
 161 developers and companies. A list of companies and individuals with known
 162 copyright claims is present at the top level of the coreboot source tree
 163 in the 'AUTHORS' file. Please check the git history of each of the
 164 source files for details.
 165
 166
 167 ### Licenses
 168
 169 Because of the way coreboot began, using a significant amount of source
 170 code from the Linux kernel, it's licensed the same way as the Linux
 171 Kernel, with GNU General Public License (GPL) Version 2. Individual
 172 files are licensed under various licenses, though all are compatible
 173 with GPLv2. The resulting coreboot image is licensed under the GPL,
 174 version 2. All source files should have an SPDX license identifier at
 175 the top for clarification.
 176
 177 Files under coreboot/Documentation/ are licensed under CC-BY 4.0 terms.
 178 As an exception, files under Documentation/ with a history older than
 179 2017-05-24 might be under different licenses.
 180
 181 Files in the coreboot/src/commonlib/bsd directory are all licensed with
 182 the BSD-3-clause license.  Many are also dual-licensed GPL-2.0-only or
 183 GPL-2.0-or-later.  These files are intended to be shared with libpayload
 184 or other BSD licensed projects.
 185
 186 The libpayload project contained in coreboot/payloads/libpayload may be
 187 licensed as BSD or GPL, depending on the code pulled in during the build
 188 process. All GPL source code should be excluded unless the Kconfig
 189 option to include it is set.
 190
 191
 192 The Software Freedom Conservancy
 193 --------------------------------
 194
 195 Since 2017, coreboot has been a member of [The Software Freedom
 196 Conservancy](https://sfconservancy.org/), a nonprofit organization
 197 devoted to ethical technology and driving initiatives to make technology
 198 more inclusive. The conservancy acts as coreboot's fiscal sponsor and
 199 legal advisor.