gnuboot/manual/gnuboot.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gnuboot.info
@include version.texi
@settitle GNU Boot @value{VERSION}

@c Define a new index for options.
@defcodeindex op
@c Combine everything into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@c %**end of header

@copying

Copyright @copyright{} 2024 Denis 'GNUtoo' Carikli.

Copyright @copyright{} 2024 Adrien 'neox' Bourmault.

@quotation
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, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@dircategory Kernel
@direntry
* GNU Boot: (gnuboot).                 Boot software distribution
@end direntry

@titlepage
@title GNU Boot manual (version @value{VERSION})
@author GNU Boot Contributors (@email{gnuboot@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents


@ifnottex
@node Top
@top GNU Boot

This manual is for GNU Boot version @value{VERSION}.
@end ifnottex

@node Table of contents

@menu
* Overview::					General purpose and information.
* Supported hardware and configurations::
* Helping GNU Boot::				How to contribute to GNU Boot
* GNU Free Documentation License::		Copying and sharing this documentation.
* Concept index::				Index of concepts.
@end menu


@node Overview
@chapter Overview

This chapter will explain what is GNU Boot, and how it compares with
somewhat similar projects.

@node What is GNU Boot
@section What is GNU Boot

GNU Boot is a boot software distribution. What this means will be
explained below.

@node boot software
@subsection boot software
@cindex @acronym{BIOS, Basic Input/Output System}
@cindex @acronym{UEFI, Unified Extensible Firmware Interface}
@cindex boot software

If you take a modern laptop computer, and remove the storage devices
(like @acronym{SSD, Solid State Drive}, hard disks, etc) and then
power on the computer, it will typically show something on the screen.

It often looks a bit like that:

@verbatim
+--------------------------------------------------------------------+
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                        [ Some company Logo ]                       |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
| Press F2 for BIOS setup, Press F12 for the startup menu.           |
+--------------------------------------------------------------------+
@end verbatim

What is being displayed on the screen is produced by software which is
often nonfree.

It is often called @acronym{BIOS, Basic Input/Output System} or
@acronym{UEFI, Unified Extensible Firmware Interface} on computers
people are most familiar with. This software is typically stored
inside a memory chip inside the computer mainboard. In some computers,
this software can be replaced by free software.

Depending on how you read the manual, right below you may or may not
see a picture of this memory chip on the mainboard of a ThinkPad X200.

@image{images/SOIC-16,6in,, Picture of the memory chip of the ThinkPad X200
mainboard.}

@sp 2

The goal of this boot software is to initialize the hardware and load
an operating system (like GNU/Linux).

@sp 1

This kind of ``boot software'' exists for a variety of reasons:

@itemize

@item The operating systems require certain hardware components like the
@acronym{RAM, Random Access Memory} to already work when they are
started.

@item The operating system is stored on a storage device(s) (like
@acronym{SSD, Solid State Drive}, hard disks, etc) and part of it needs to be
loaded inside the @acronym{RAM, Random Access Memory} to
work. Something has to do the loading, and this is done in software
for flexibility and/or efficiency reasons.

@item Finally, certain hardware components cannot be auto-detected and
something needs to tell the operating system what drivers to load,
which which settings.

@end itemize

GNU Boot provides such software. It enables to replace nonfree boot
software (typically nonfree @acronym{BIOS, Basic Input/Output System}
or @acronym{UEFI, Unified Extensible Firmware Interface}) on some
computers.

@node distribution
@subsection distribution

GNU Boot is only a distribution because it reuses various software to
produce something that can be installed.

So it is similar to GNU/Linux distributions like Trisquel 11
(aramo) that also reuse various software to produce something that
can be installed.

@node Why free boot software is important
@section Why free boot software is important

Freedom is important in general, and running nonfree software has
negative consequences regardless of the type of software (game, boot
software, operating system, driver, etc).

@sp 1

Here are some examples of common issues for nonfree boot software:

@itemize

@item Since the boot software loads the operating system, it
can potentially modify it in a malicious way. In most cases part of
the boot software also continues to run once the operating system is
started. Because of that and, and because of the way the hardware and
boot software run, the boot software can also do such modification at
any time. If the boot software is nonfree, it is way harder to find
and remove malicious code (it's even impossible to remove in some
cases), and there is no way to make sure that there is none left. For
instance many nonfree boot software where shipped with the CompuTrace
malware (which was advertised as an anti-theft security feature).

@item Vendors of various hardware components have to collaborate together
to provide updates for nonfree Boot software, so in practice
they decide when updates are done. So if a computer is not sold
anymore, it is unlikely to get update for its Boot software
unless the Boot software uses some free software that can be
updated. Also note that applying nonfree updates comes with huge risk
as we don't know what's inside the updates. Hardware vendors who
provide the updates also have an incentive to make things worse for
the users, so they would be pushed to buy new devices.

@item Some nonfree Boot software restrict what you can do with
your computer. For instance they refuse to boot if you changed or
removed some hardware components.

@end itemize

@node Why use GNU Boot
@section Why use GNU Boot

As explained before GNU boot is just a distribution. So it is also
possible to take the same software that GNU Boot reuses, and to build,
assemble and install it yourself.

However doing that is risky because if something goes wrong, your
computer won't boot anymore.

So the goals of GNU Boot are to:

@itemize

@item Collaborate together to test if GNU Boot releases works fine.

@item Provide documentation to enable easy installation and usage.

@item Limit the amount of work done by GNU Boot and contribute
directly to the software we reuse whenever possible.

@end itemize

GNU Boot also has a long term focus, so it tries not to break users
use cases, and tries as much as possible to fix issues in the projects
it reuses instead of doing workarounds that impact users.


@node Other free boot software distributions
@section Other free boot software distributions

The following GNU/Linux distributions should also provide 100% free
boot software but they usually only provide them for computers using
the ARM architecture (which GNU Boot doesn't support yet):

@itemize

@item Parabola

@item PureOS

@item Trisquel

@end itemize

The GNU Guix package manager (which GNU Boot also reuses) also provide
100% free boot software for some ARM computers. However the Guix
packages are updated all the time and the Guix project doesn't provide
any way for users to report that specific ARM computers work fine with
the boot software they provide.

There is also Canoeboot which is a 100% free software boot
distribution similar to GNU Boot. Its goal is to remove nonfree
software from Libreboot. It focuses more on having the latest software
and many features, including some that are not available in the
projects it reuses. Because of that it can be harder for users to use.

@node How much free software is GNU Boot?
@section How much free software is GNU Boot?

Being a GNU package, GNU Boot itself is 100% free software. If you
find nonfree software in GNU Boot and/or any source code or binaries
released by GNU Boot, please contact its maintainers by opening a bug
report on its bug tracker at
@url{https://savannah.gnu.org/bugs/?group=gnuboot}.

But that doesn't mean that GNU Boot magically makes everything not
provided by GNU Boot free software.

In some cases GNU Boot even runs nonfree software not provided by GNU
Boot like nonfree GPUs drivers provided by the removable GPU
card. @xref{Supported computer parts and peripherals} for more
details about this issue and how to avoid running such nonfree
software.

To address problems like that the @uref{https://www.fsf.org/,Free
Software Foundation} has created the
@uref{https://ryf.fsf.org/,Respect Your Freedom hardware
certification} to list hardware that works with only free software
(with some very small exceptions for some components, see
@uref{https://ryf.fsf.org/about/criteria, its criteria} for more
details).

In addition there is also
@uref{https://www.fsfla.org/ikiwiki/blogs/lxo/draft/blob-fallacy,The
Blob Fallacy article} or
@uref{https://media.libreplanet.org/u/libreplanet/m/software-enshittification-or-freedom-it-s-not-a-hard-choice,
a video of a presentation about the same issue at LibrePlanet 2024} by
Alexandre Oliva that explains the related freedom issues with nonfree
software provided by the hardware and how they compare with other kind
of freedom issues (nonfree driver, nonfree firmware loaded
automatically by Linux, etc).

@node Limitations
@section Limitations

GNU Boot is fairly recent and doesn't have an official release
yet.

For the release we plan to have at least some install and upgrade
instructions for some computers and an easy way for users to use GNU
Boot.

Also the latest GNU Boot release candidate was not tested yet with all
the computers it's supposed to support (we badly need help for that).

@node Supported hardware and configurations
@chapter Supported hardware and configurations

@node Supported computers
@section Supported computers

For now, GNU Boot only provides images that can be installed on the
following computers:

@itemize

@item Acer G43T-AM3
@item Apple MacBook 1.1
@item Apple MacBook 2.1
@item Apple iMac 5,2
@item Asus KCMA-D8
@item Asus KFSN4-DRE
@item Asus KGPE-D16
@item Gigabyte D945GCLF2D
@item Gigabyte GA-G41M-ES2L
@item Intel D410PT
@item Intel D510MO
@item Intel D945GCLF
@item Lenovo ThinkPad R400
@item Lenovo ThinkPad R500
@item Lenovo ThinkPad T400
@item Lenovo ThinkPad T400S
@item Lenovo ThinkPad T500
@item Lenovo ThinkPad T60 with intel GPU
@item Lenovo ThinkPad W500
@item Lenovo ThinkPad X200
@item Lenovo ThinkPad X200S
@item Lenovo ThinkPad X200T
@item Lenovo ThinkPad X301
@item Lenovo ThinkPad X60
@item Lenovo ThinkPad X60T
@item Lenovo ThinkPad X60s
@item Libiquity Taurinus X200
@item Qemu PC (i440FX)
@item Technoethical D16
@item Technoethical T400
@item Technoethical T400s
@item Technoethical T500
@item Technoethical X200
@item Technoethical X200s
@item Technoethical X200 Tablet (X200T)
@item Vikings ASUS KCMA D8 mainboard and workstation
@item Vikings ASUS KGPE D16 mainboard
@item Vikings X200

@end itemize

However as GNU Boot is still relatively new, we lack installation and
upgrade instructions for most of these computers.

Also not all are well tested, so it's a good idea to look on the GNU
Boot website, on the status page (
@url{https://www.gnu.org/software/gnuboot/web/status.html}) for up to
date result of tests by GNU Boot users and contributors.

@node Supported computer parts and peripherals
@section Supported computer parts and peripherals

Most computer parts and peripherals don't have any compatibility issue
with GNU Boot because:

@itemize

@item they either use some standard that is most often already
implemented in the software GNU Boot reuses (storage devices like SATA
drives, USB keyboards, etc),

@item they are not relevant or supported for booting (for instance 3D printers,
cellular network cards, etc, unless people add support for them in GNU
Boot in the future). Until then they are only handled in the operating
system instead (with drivers),

@end itemize

however there is some exceptions as some hardware is non-standard and
still required for booting, these are documented in the subsections
below.

@node Supported GPUs and graphics
@subsection Supported GPUs and graphics

GNU Boot supports the GPUs that are present in the various laptops it
supports with 100% free software. Some consideration apply while
booting, but so far once booted these GPU are known to works well on
tested computers.

In addition for the non-laptop computers, it also supports the builtin
AST graphics in the KGPE-D16 and KCMA-D8 with 100% free software, but
this also comes with some limitations: in GNU/Linux it's only possible
to display text but not images, so it's limited to console
applications.

In the case of PCIe GPU / graphics cards, we don't know yet if it
is possible to use them without running nonfree software.

If AMD, ATI, and Nvidia cards work under GNU Boot, it's because GNU
Boot loaded and run the nonfree video BIOS that is present on the
card.

It's possible to prevent the nonfree video BIOS from running and you
can easily confirm that as the display will not work until the Linux
driver is loaded.

The Free Software Foundation tech team has a wiki. In
@uref{https://savannah.gnu.org/maintenance/fsf/hardware/disable-option-roms-with-cbfstool/,
the disable option roms with cbfstool article}, they explains how to
do that.

And in
@uref{https://savannah.gnu.org/maintenance/fsf/hardware/graphics-cards/,
the graphics cards article} they also explain which GPU they tested.

However the Linux driver can also run nonfree software: All the
current AMD, ATI, and Nvidia drivers have code to load and run (a
different) initialization code provided on the card. For ATI and AMD
cards the code that Linux runs is called AtomBIOS.

We don't know yet if there are cases where this code is not run (this
would need to be tested by doing very simple modifications to the
drivers, and the GNU Boot project also welcome help in this area).

@node Supported card readers
@subsection Supported card readers

GNU Boot supports the builtin card reader of the following computers:

@itemize
@item Lenovo ThinkPad X200
@item Lenovo ThinkPad X200S
@item Lenovo ThinkPad X200T
@item Libiquity Taurinus X200
@item Technoethical X200
@item Technoethical X200s
@item Technoethical X200 Tablet (X200T)
@item Vikings X200

@end itemize

It also supports some USB card readers that are viewed as
mass-storage. With all that you can boot on an SD card a microSD card
and it will be viewed like a mass storage USB key.

@node Unsupported hardware supported by projects reused by GNU Boot
@subsection Unsupported hardware supported by projects reused by GNU Boot

The following hardware components are supported by software reused by
GNU Boot, but support for them hasn't been enabled yet in GNU Boot:

@itemize
@item Serial ports.
@item Software RAID cards: Some Silicon Image SIL3114 software RAID
      cards are supported by Coreboot but not enabled in GNU Boot.
@item Network interfaces. Projects like iPXE has drivers for many network cards
      and even some Wifi cards typically used with the computers supported by GNU
      Boot and free distributions.
@item Some printers that use serial ports could probably easily be supported
      once serial ports are working.
@end itemize

The GNU Boot project needs help to evaluate the impact of enabling
these and welcome contributions in this area.

@node Supported operating systems
@subsection Supported operating systems

While GNU Boot should be able to boot almost any GNU/Linux
distribution, but in some cases some configuration might be needed by
the GNU Boot user.

Even if some cases require some configuration, GNU Boot makes sure to
provide at least one way to boot free GNU/Linux distributions (see
@url{https://www.gnu.org/distros/} for more information on these
distributions) without the need to configure anything in order to make
it possible for less technical users to use computers with GNU Boot,
and even reinstall the GNU/Linux distribution without needing to do
anything too complicated.

To make that possible, the GNU Boot contributors that proposes
improvements to the project typically test GNU Boot with free
distributions, and the GNU Boot project even runs automatic tests with
Trisquel 11 (aramo), one of the free distributions to make sure that
it can boot fine without needing any special configuration from the
user.

However sometimes fully free distributions also propose experimental
or non-standard configurations for very specific use cases. For
instance Guix has experimental support for GNU Hurd, an experimental
kernel from the GNU project, and Trisquel supports the Xen kernel,
which is a virtualization solution that not supported by all GNU/Linux
distributions. These configurations are not supported in the official
installers of these distribution and so users are usually aware thaty
they use Xen or GNU Hurd. Using GNU Boot with these configurations
might require some configuration from the user. Also we would need
help from users to report what works and doesn't work or what
workarounds are needed to make them work with GNU Boot.

The cases that are known not to require any configuration might also
work with any GNU/Linux distributions (even the nonfree ones), however
the GNU Boot project doesn't want to force contributors to download or
run nonfree software to test changes, so it relies on voulounteers
already running such distributions to report bugs in case something
doesn't work as it should.

As for other operating systems, there is some documentation on how to
boot some of them (like some BSD operating systems) on the GNU Boot
website, but again we need help from voulonteers already running such
systems to keep the documentation up to date and inform us of what
works and doesn't work.

Also if you want to do such tests, you can open a bug report on the
GNU Boot bug tracker at
@url{https://savannah.gnu.org/bugs/?group=gnuboot}.

@node Helping GNU Boot
@chapter Helping GNU Boot

The GNU Boot project needs help with this manual, specifically on
moving information from the GNU Boot website to this manual.

In general there is also a lot of ways to help the GNU Boot project
(from reviewing website pages for very simple mistakes or outdated
information, testing GNU Boot images, etc).

See the
@uref{https://www.gnu.org/software/gnuboot/web/git.html,Helping GNU
Boot} page on the GNU Boot website for the areas where we need help
and on how to help practically speaking (how to contact the project,
where to send bug reports, etc).

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl-1.3.texi


@node Concept index
@unnumbered Concept index

@printindex cp

@bye