summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--config.mk1
-rw-r--r--libreboot-policy.7181
-rw-r--r--libreboot.7176
3 files changed, 352 insertions, 6 deletions
diff --git a/config.mk b/config.mk
index 41bee2c..a201336 100644
--- a/config.mk
+++ b/config.mk
@@ -3,4 +3,5 @@ PAGES += libreboot-bsd
PAGES += libreboot-hardware
PAGES += libreboot-lbmk-overview
PAGES += libreboot-linux
+PAGES += libreboot-policy
PAGES += README
diff --git a/libreboot-policy.7 b/libreboot-policy.7
new file mode 100644
index 0000000..0a1a666
--- /dev/null
+++ b/libreboot-policy.7
@@ -0,0 +1,181 @@
+.Dd July 30, 2024
+.Dt libreboot-policy 7
+.Os "Libreboot"
+.Sh NAME
+.Pp
+.Nm libreboot-policy
+.Nd binary blob reduction policy
+.
+.Sh INTRODUCTION
+.Pp
+This article describes the principles that govern the Libreboot project. For
+information about how those principles are applied in practise for each
+mainboard, please refer for the pages for each mainboard. See
+.Xr libreboot-hardware 7 .
+.Pp
+Libreboot's policy is to provide as much
+.Lk https://writefreesoftware.org software freedom
+as possible to each user, on each and every bit of hardware supported, and to
+support as much hardware from coreboot as is feasible; what this means is that
+you should have the potential to study, modify and share all source code,
+documentation or other such resources that make Libreboot what it is. Put
+simply, you should have control of your own computing.
+.Pp
+The goal of Libreboot is
+to do exactly this, and help as many people as possible by automating the
+configuration, compilation and installation of coreboot for non-technical
+users, easing it further for the average user by providing user-friendly
+instructions for everything. Essentially, Libreboot is a coreboot
+distribution, in much the same way Alpine Linux is a Linux distribution!
+.Pp
+The purpose of this document it to outline how that is brought about, and how
+the project operates along this basis. This document is largely about the
+ideology and it is therefore (mostly) non-technical; for technical information,
+you can refer to
+.Xr libreboot-lbmk 7 .
+.
+.Sh PROJECT SCOPE
+The libreboot project is concerned with what goes in the main boot flash IC, but
+there are other pieces of firmware to take into consideration, as covered
+in
+.Xr libreboot-faq 7 .
+.Bl -bullet -compact
+.It
+Embedded controller firmware
+.It
+HDD/SSD firmware
+.It
+Intel Management Engine / AMD PSP firmware
+.El
+.
+.Ss What is a binary blob?
+.Pp
+A binary blob, in this context, is any executable for which no source code
+exists, that you cannot study and modify in a reasonable manner. By definition,
+all such blobs are *proprietary* in nature, and should be avoided if possible.
+.Pp
+For information about Intel Management Engine and AMD PSP, refer to the FAQ.
+.
+.Sh BLOB REDUCTION POLICY
+.Ss Default configurations
+.Pp
+Coreboot, upon which Libreboot is based, is mostly libre software but does
+require certain vendor code on some platforms. A most common example might be raminit
+(memory controller initialisation) or video framebuffer initialisation. The
+coreboot firmware uses certain vendor code for some of these tasks, on some mainboards,
+but some mainboards from coreboot can be initialised with 100% libre source
+code, which you can inspect, and compile for your use.
+.Pp
+Libreboot deals with this situation in a strict and principled way:
+.Bl -bullet
+.It
+If free software can be used, it should be used. For example, if VGA ROM
+initialization otherwise does a better job but coreboot has libre init code
+for a given graphics device, that code should be used in libreboot, when
+building a ROM image. Similarly, if memory controller initialization is
+possible with vendor code or libre code in coreboot, the libre code
+should be used in ROMs built by the Libreboot build system, and the vendor
+raminit code should not be used; however, if no libre init code is available
+for said raminit, it is permitted and Libreboot build system will use the
+vendor code.
+.It
+Some nuance is to be observed: on some laptop or desktop configurations, it's
+common that there will be two graphics devices (for example, an nvidia and
+an intel chip, using nvidia optimus technology, on a laptop). It may be that
+one of them has libre init code in coreboot, but the other one does not. It's
+perfectly acceptable, and desirable, for libreboot to support both devices,
+and accomodate the required vendor code on the one that lacks native
+initialization.
+.It
+An exception is made for CPU microcode updates: they are permitted, and in
+fact required as per libreboot policy. These updates fix CPU bugs, including
+security bugs, and since the CPU already has non-libre microcode burned into
+ROM anyway, the only choice is either x86 or broken x86. Thus, libreboot
+will only allow coreboot mainboard configurations where microcode updates
+are enabled, if available for the CPU on that mainboard.
+However, releases after 20230423 will provide separate ROM images with microcode
+excluded, alongside the default ones that include microcode. See
+.Xr libreboot-microcode 7 .
+.It
+Intel management engine: When possible, documentation must be written to tell
+people how to neuter the ME, if possible. The
+.Li me_cleaner
+program is very useful, and provides a much more secure ME configuration.
+.It
+Vendor blobs should never be deleted, even if they are unused. In the
+coreboot project, a set of `3rdparty` submodules are available, with vendor
+code for init tasks on many boards. These must all be included in libreboot
+releases, even if unused. That way, even if the Libreboot build system does
+not yet integrate support for a given board, someone who downloads libreboot
+can still make changes to their local version of the build system, if they
+wish, to provide a configuration for their hardware.
+.El
+.Pp
+Generally speaking, common sense is applied. For example, an exception to the
+minimalization might be if vendor raminit and libre raminit are available, but
+the libre one is so broken so as to be unusable. In that situation, the vendor
+one should be used instead, because otherwise the user might switch back to an
+otherwise fully proprietary system, instead of using coreboot (via libreboot).
+Some freedom is better than none.
+.Pp
+Libreboot's pragmatic policies will inevitably result in more people becoming
+coreboot developers in the future, by acting as that crucial bridge between
+it and non-technical people who just need a bit of help to get started.
+.Ss Configuration
+.Pp
+The principles above should apply to default configurations. However, libreboot
+is to be configurable, allowing the user to do whatever they like.
+.Pp
+It's natural that the user may want to create a setup that is less libre than
+the default one in libreboot. This is perfectly acceptable; free software is
+superior, and should be encouraged, but the user's freedom to choose should also
+be respected, and accomodated.
+.Pp
+In other words, do not lecture the user. Just try to help them with their
+problem! The goal of the libreboot project is simply to make coreboot more
+accessible for otherwise non-technical users.
+.
+.Sh LIBRE HARDWARE
+.Pp
+It is desirable to see a world where all hardware and software is libre, under
+the same ideology as the Libreboot project.
+.Pp
+RISC-V is a great example of a modern attempt at libre hardware,
+often called Open Source Hardware.
+It is a an ISA for the manufacture of a microprocessor. Many real-world
+implementations of it already exist, that can be used, and there will only be
+more.
+.Pp
+Such hardware is still in its infancy. We should start a project that will
+catalog the status of various efforts, including at the hardware level (even
+the silicon level). Movements like OSHW and Right To Repair are extremely
+important, including to our own movement which otherwise will
+typically think less about hardware freedoms (even though it really, really
+should!)
+.Pp
+One day, we will live in a world where anyone can get their own chips made,
+including CPUs but also every other type of IC. Efforts to make homemade
+chip fabrication a reality are now in their infancy, but such efforts do
+exist, for example, the work done by Sam Zeloof and the Libre Silicon project:
+.Bl -bullet -compact
+.It
+.Lk https://www.youtube.com/channel/UC7E8-0Ou69hwScPW1_fQApA
+.It
+.Lk http://sam.zeloof.xyz
+.It
+.Lk https://libresilicon.com
+.El
+.Pp
+(Sam literally makes CPUs in his garage)
+.
+.Sh SEE ALSO
+.Bl -tag
+.It Libreboot's main website
+.Lk https://libreboot.org
+.It Libreboot manual root
+.Xr libreboot 7
+.It Free Software
+.Lk https://writefreesoftware.org
+.El
+.
+.\" vim: tw=80
diff --git a/libreboot.7 b/libreboot.7
index 8c81bfe..fcf53d1 100644
--- a/libreboot.7
+++ b/libreboot.7
@@ -23,8 +23,14 @@ matters. Education matters. Right to repair matters; Libreboot lets you
continue to use your hardware, with continued firmware updates. All of
this is why Libreboot exists.
.
+.Sh RECENT RELEASE
+.Pp
+The latest release is
+.Xr libreboot-20240612 7 .
+.
.Sh MINIFREE
-Minifree, Ltd. sells devices with Libreboot preinstalled, and provides a
+.Lk https://minifree.org Minifree, Ltd.
+sells devices with Libreboot preinstalled, and provides a
send-in installation service for supported devices.
The founder and lead developer of Libreboot, Leah Rowe, also owns
and operates Minifree; sales provide funding for Libreboot.
@@ -42,16 +48,174 @@ respective manual pages:
.It BSDs
.Xr libreboot-bsd 7
.El
+.
+.Sh DESIGN OVERVIEW
+.Pp
+
+Libreboot provides
+.Lk https://coreboot.org/ coreboot
+for
+.Lk https://doc.coreboot.org/getting_started/architecture.html machine initialisation ,
+which then jumps to a
+.Lk https://doc.coreboot.org/payloads.html payload
+in
+the boot flash; coreboot works with many programs, but Libreboot specifically
+provides SeaBIOS, GNU GRUB and U-Boot as options. Memtest86+ is also provided
+in flash, on some mainboards. The payload is the program in flash that provides
+the early user interface, for booting an operating system. This payload
+infrastructure means you can run whatever you want (even Linux!) from the
+boot flash.
+.Pp
+Libreboot is specifically a
+.Em coreboot distribution ,
+in the same way that
+Debian is a
+.Em Linux distribution .
+Libreboot makes coreboot easy to use for
+non-technical users, by providing a
+fully automated build system
+.Xr "(" libreboot-lbmk 7 ")" ","
+automated build process
+.Xr "(" libreboot-build 7 ")" ","
+and
+user-friendly installation instructions
+.Xr "(" libreboot-install 7 ")" ","
+in addition to
+regular binary releases that provide pre-compiled ROM images for installation
+on supported hardware. Without automation such as that provided by Libreboot,
+coreboot would be inaccessible for most users.
+.
+.Sh WHY USE LIBREBOOT
+.Pp
+If you're already inclined towards free software, maybe already a coreboot user,
+Libreboot makes it easier to either get started or otherwise maintain coreboot
+on your machine, via build automation. It provides regular tested releases,
+pre-assembled, often with certain patches on top of coreboot (and other code)
+to ensure stability. By comparison, coreboot uses a rolling-release model, with
+a snapshot of the codebase every few months; it is very much developer-oriented,
+whereas Libreboot is specifically crafted for end users. In other words, the
+purpose of Libreboot is to
+.Em Just Work .
+Direct configuration and installation of coreboot is also possible, but
+Libreboot makes it
+.Em much
+easier.
+.Pp
+Libreboot gives you freedoms that you otherwise can't get with most
+other boot firmware, plus faster boot speeds and
+better security
+.Xr "(" libreboot-grub-hardening 7 ")" "."
+It's extremely powerful and configurable for many use cases. If you're
+unhappy with the restrictions (not to mention, security issues) imposed
+on you by proprietary BIOS vendors, then Libreboot is one possible
+choice for you. Since it inherits coreboot, it doesn't have any known
+backdoors in the code, nor does it contain legacy cruft from the 1980s.
+Libreboot provides a sleek, fast boot experience for Linux/BSD systems,
+based on coreboot which is regularly audited and improved.
+.Pp
+Libreboot is more reliable than proprietary firmware. Many people use proprietary
+(non-libre) boot firmware, even if they use a libre operating system.
+Proprietary firmware often contains backdoors, and can be buggy. The
+Libreboot project was founded in December 2013, with the express purpose
+of making coreboot firmware accessible for non-technical users.
+.Pp
+Libreboot is a community-oriented project, with a focus on helping users
+escape proprietary boot firmware; we ourselves want to live in a world
+where all software is free, and so, Libreboot is an effort to help get
+closer to that world. Unlike the big vendors, we don't try to stifle you
+in any way, nor do we see you as a security threat; we regard the
+ability to use, study, modify and redistribute software freely to be a
+human right that everyone must have. Extended to computers, these are
+products that you purchased, and so you should have the freedom to
+change them in any way you like. When you see Intel talk about their
+.Em Boot Guard
+(which prevents coreboot by only letting firmware signed by
+them be executed) or other vendors imposing similar restrictions, and
+you hear them talk about "security", they are only talking about
+.Em their
+security, not yours. In the Libreboot project, it is reversed; we see
+Intel Boot Guard and similar such technologies as an attack on your
+freedom over your own property (your computer), and so, we make it our
+mission to help you wrest back such control.
+.Sh LIBREBOOT IS NOT A FORK OF COREBOOT
+.Pp
+In fact, Libreboot tries to stay as close to *stock* coreboot as possible,
+for each board, but with many different types of configuration provided
+automatically by the Libreboot build system.
+.Pp
+In the same way that Alpine Linux is a Linux distribution, Libreboot is
+a coreboot distribution. If you want to build a ROM image from scratch, you
+otherwise have to perform expert-level configuration of coreboot, GRUB and
+whatever other software you need, to prepare the ROM image. With Libreboot,
+you can literally download from Git or a source archive, and run a simple script,
+and it will build entire ROM images. An automated build system,
+.Xr libreboot-lbmk 7
+(Libreboot MaKe), builds these ROM images automatically, without any user input
+or intervention required. Configuration has already been performed in advance.
+.Pp
+Regular binary releases of Libreboot provide these ROM images
+pre-compiled, and you can simply install them, with no special knowledge
+or skill except the ability to follow simplified instructions, written
+for non-technical users
+.Xr "(" libreboot-install 7 ")" "."
+.
+.Sh CONTRIBUTING TO LIBREBOOT
+.Pp
+.Xr libreboot-tasks 7
+lists things that could be worked on. It will be updated over time as
+more tasks are added/completed. If you want to help, you could pick one
+of these tasks and work on it.
+.Pp
+But, the single biggest way you can help is to add new mainboards in Libreboot,
+by submitting a config. Anything coreboot supports can be integrated in
+Libreboot, with ROM images provided in releases. See:
+.Bl -tag
+.It Apply to become a board maintainer/tester
+.Xr libreboot-lbmk-testing 7
+.It Porting guide for new mainboards
+.Xr libreboot-lbmk-porting 7
+.It Libreboot build system maintanance manual
+.Xr libreboot-lbmk 7
+.El
+.Pp
+Additionally, we appreciate build system maintainance (see above), documentation
+(which is critical for any serious project), and ironing out bugs on the bug
+tracker.
+.Pp
+User support is also critical. Stick around on IRC, and if you're competent to
+help someone with their issue (or wily enough to learn with them), that is a
+great service to the project.
+A lot of people also ask for user support on
+.Lk https://reddit.com/r/libreboot .
+.Pp
+You can check bugs listed on the
+.Lk https://codeberg.org/libreboot/lbmk/issues bug tracker .
+.Pp
+If you have a fix for a bug, you can submit a patch
+.Xr ( libreboot-submit-patch 7 ) .
+.
.Sh SUPPORT
.Pp
Help is available via
.Lk https://web.libera.chat/#libreboot #libreboot
on the
-.Lk https://libera.chat Libera
+.Lk https://libera.chat Libera.Chat
IRC network.
+.
.Sh SEE ALSO
-.Bl -item
-.It
-.Lk https://minifree.org Minifree, Ltd.
+.Bl -tag
+.It Libreboot's main website
+.Lk https://libreboot.org
+.It Libreboot bug tracker
+.Lk https://codeberg.org/libreboot/lbmk/issues
+.It Libreboot manual root
+.Xr libreboot 7
+.It Binary blob reduction policy
+.Xr libreboot-policy 7
+.It Free Software
+.Lk https://writefreesoftware.org
+.It Right to repair
+.Lk https://en.wikipedia.org/wiki/Right_to_repair
.El
-.\" vim: tw=72
+.
+.\" vim: tw=80