path: root/docs/src/index.texi

\input texinfo
@documentencoding UTF-8

@ifnottex
@paragraphindent 0
@end ifnottex
@titlepage
@title Libreboot project documentation
@end titlepage

@node Top
@top Libreboot project documentation

@menu
* Libreboot project documentation::
* Table of contents::
* About the libreboot project::
* How do I know what version I'm running?::
@end menu

@node Libreboot project documentation
@chapter Libreboot project documentation
@anchor{#libreboot-project-documentation}
Information about this release can be found at @uref{release.html,release.html}. Always check @uref{http://libreboot.org,libreboot.org} for updates.

@node Table of contents
@chapter Table of contents
@anchor{#table-of-contents}
@itemize
@item
@uref{hcl/index.html,Hardware compatibility list} - @uref{https://www.gnu.org/distros/,GNU/Linux} is expected to be running on your device.
@item
@uref{install/index.html,How to install libreboot}
@item
@uref{gnulinux/index.html,How to install GNU/Linux on a libreboot system}
@item
@uref{git/index.html,How to use the git repository and build libreboot from source}
@itemize
@item
@uref{maintain/index.html,Maintaining libreboot}
@end itemize

@item
@uref{security/index.html,Hardware security}
@item
@uref{hardware/index.html,Hardware maintenance}
@item
@uref{depthcharge/index.html,Depthcharge payload}
@item
@uref{grub/index.html,GRUB payload}
@item
@uref{misc/index.html,Miscellaneous}
@end itemize

@node About the libreboot project
@chapter About the libreboot project
@anchor{#about-the-libreboot-project}
Libreboot originally began during December 2013, as a commercial effort by @uref{http://gluglug.org.uk/,Gluglug} to achieve @uref{https://www.fsf.org/resources/hw/endorsement/respects-your-freedom,RYF} endorsement for a modified ThinkPad X60 (the first system to ever be added to libreboot).

Back then, the name @emph{libreboot} didn't exist; the project was nameless, referring to itself as a @emph{deblobbed version of coreboot}. The project named itself libreboot at some point during early 2014, and has since rapidly expanded to support more hardware and become more user-friendly.

Libreboot is a @uref{http://coreboot.org/,coreboot} distribution (distro) with proprietary software removed, intended to be a @uref{https://www.fsf.org/about/what-is-free-software,free} (libre) 'BIOS' replacement for your computer. The project is aimed at users, attempting to make coreboot as easy to use as possible. Read the full @uref{https://www.gnu.org/philosophy/free-sw.html,Free Software definition}.

Libreboot has many practical advantages over @uref{https://gnu.org/philosophy/proprietary/,proprietary} boot firmware, such as faster boot speeds and better security. You can @uref{gnulinux/index.html,install GNU/Linux with encrypted /boot/}, @uref{http://www.coreboot.org/GRUB2#signed_kernels,verify GPG signatures on your kernel}, put a kernel in the flash chip and more.
@menu
* The libreboot project has three main goals::
* Libreboot is a coreboot distribution not a coreboot fork::
* Libreboot is a 'stable' version of coreboot::
@end menu

@node The libreboot project has three main goals
@section The libreboot project has three main goals:
@anchor{#the-libreboot-project-has-three-main-goals}
@itemize
@item
@emph{@strong{Recommend and distribute only free software}}. Coreboot distributes certain pieces of proprietary software which is needed on some systems. Examples can include things like CPU microcode updates, memory initialization blobs and so on. The coreboot project sometimes recommends adding more blobs which it does not distribute, such as the Video BIOS or Intel's @emph{Management Engine}. However, a lot of dedicated and talented individuals in coreboot work hard to replace these blobs whenever possible.
@item
@emph{@strong{Support as much hardware as possible!}} Libreboot supports less hardware than coreboot, because most systems from coreboot still require certain proprietary software to work properly. Libreboot is an attempt to support as much hardware as possible, without any proprietary software.
@item
@emph{@strong{Make coreboot easy to use}}. Coreboot is notoriously difficult to install, due to an overall lack of user-focussed documentation and support. Most people will simply give up before attempting to install coreboot.@*@* Libreboot attempts to bridge this divide, making sure that everything from building to installing coreboot is automated, as much as is feasibly possible. Secondly, the project produces documentation aimed at non-technical users. Thirdly, the project attempts to provide excellent user support via mailing lists and IRC.@*@* Libreboot already comes with a payload (GRUB), flashrom and other needed parts. Everything is fully integrated, in a way where most of the complicated steps that are otherwise required, are instead done for the user in advance.@*@* You can download ROM images for your libreboot system and install them, without having to build anything from source. The build system is also fully automated, so building from source is easy if you wanted to do that (for whatever reason).
@end itemize

@node Libreboot is a coreboot distribution not a coreboot fork
@section Libreboot is a coreboot distribution, not a coreboot fork
@anchor{#libreboot-is-a-coreboot-distribution-not-a-coreboot-fork}
Libreboot is not a fork of coreboot. Every so often, the project re-bases on the latest version of coreboot, with the number of custom patches in use minimized.

All new coreboot development should be done in coreboot (upstream), not libreboot! Libreboot is about deblobbing and packaging coreboot in a user-friendly way, where most work is already done for the user.

For example, if you wanted to add a new board to libreboot, you should add it to coreboot first. Libreboot will automatically receive your code at a later date, when it updates itself.

The deblobbed coreboot tree used in libreboot is referred to as @emph{coreboot-libre}, to distinguish it as a component of @emph{libreboot}.

@node Libreboot is a 'stable' version of coreboot
@section Libreboot is a 'stable' version of coreboot
@anchor{#libreboot-is-a-stable-version-of-coreboot}
@itemize
@item
Coreboot uses the @uref{https://en.wikipedia.org/wiki/Rolling_release,rolling release} model, which means that it is not guaranteed to be stable, or to even work at all on a given day. Coreboot does have a strict code review process, but being such a large project with so many contributors, regressions are always possible.
@item
Libreboot freezes on a particular revision of coreboot, making sure that everything works properly, making fixes on top of that and repeating this during each subsequent update to a later version of coreboot. By doing this, it provides a stronger guarantee to the user that the firmware will be reliable, and not break their system.
@end itemize

@pxref{Top,Back to top of page.}

@node How do I know what version I'm running?
@chapter How do I know what version I'm running?
@anchor{#how-do-i-know-what-version-im-running}
If you are at least 127 commits after release 20150518 (commit message @emph{build/roms/helper: add version information to CBFS}) (or you have any @strong{upstream} stable release of libreboot after 20150518), then you can press C at the GRUB console, and use this command to find out what version of libreboot you have:@* @strong{cat (cbfsdisk)/lbversion}@* This will also work on non-release images (the version string is automatically generated, using @emph{git describe --tags HEAD}), built from the git repository. A file named @emph{version} will also be included in the archives that you downloaded (if you are using release archives).

If it exists, you can also extract this @emph{lbversion} file by using the @emph{cbfstool} utility which libreboot includes, from a ROM image that you either dumped or haven't flashed yet. In GNU/Linux, run cbfstool on your ROM image (@emph{libreboot.rom}, in this example):@* $ @strong{./cbfstool libreboot.rom extract -n lbversion -f lbversion}@* You will now have a file, named @emph{lbversion}, which you can read in whatever program it is that you use for reading/writing text files.

For git, it's easy. Just check the git log.

For releases on or below 20150518, or snapshots generated from the git repository below 127 commits after 20150518, you can find a file named @emph{commitid} inside the archives. If you are using pre-built ROM images from the libreboot project, you can press C in GRUB for access to the terminal, and then run this command:@* @strong{lscoreboot}@* You may find a date in here, detailing when that ROM image was built. For pre-built images distributed by the libreboot project, this is a rough approximation of what version you have, because the version numbers are dated, and the release archives are typically built on the same day as the release; you can correlate that with the release information in @uref{release.html,release.html}.

You can also check the documentation that came with your archives, and in @emph{release.html} will be the information about the version of libreboot that you are using.

Generally speaking, it is advisable to use the latest version of libreboot.

Copyright © 2014, 2015 Minifree Ltd <info@@minifree.org>@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found at @uref{resources/licenses/gfdl-1.3.txt,gfdl-1.3.txt}

Updated versions of the license (when available) can be found at @uref{https://www.gnu.org/licenses/licenses.html,https://www.gnu.org/licenses/licenses.html}

UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.

TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.

The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

@bye