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.