title: Frequently Asked Questions x-toc-enable: true ...

Important facts

Where can I track development of Retroboot?

Yes! The git repository shows all of the work that is currently benig done in Retroboot.

You can submit bug reports, and view current bug reports here: https://notabug.org/retroboot/retroboot/issues

Flashrom complains about DEVMEM access

If running flashrom -p internal for software based flashing, and you get an error related to /dev/mem access, you should reboot with iomem=relaxed kernel parameter before running flashrom, or use a kernel that has CONFIG_STRICT_DEVMEM and CONFIG_IO_STRICT_DEVMEM not enabled.

Example flashrom output with both CONFIG_STRICT_DEVMEM and CONFIG_IO_STRICT_DEVMEM enabled:

flashrom v0.9.9-r1955 on Linux 4.11.9-1-ARCH (x86_64)
flashrom is free software, get the source code at https://flashrom.org

Calibrating delay loop... OK.
Error accessing high tables, 0x100000 bytes at 0x000000007fb5d000
/dev/mem mmap failed: Operation not permitted
Failed getting access to coreboot high tables.
Error accessing DMI Table, 0x1000 bytes at 0x000000007fb27000
/dev/mem mmap failed: Operation not permitted

Uneven backlight on GM45/ICH9 laptops such as ThinkPad X200/T400

We don't know how to detect the correct PVM value to use for the backlight, so the default one from coreboot is used. The default value is safe for LED backlit screens so as to prevent high frequency flicker that can strain the eyes.

Refer to this document

How to save kernel panic logs on thinkpad laptops?

The easiest method of doing so is by using the kernel's netconsole and reproducing the panic. Netconsole requires two machines, the one that is panicky (source) and the one that will receive crash logs (target). The source has to be connected with an ethernet cable and the target has to be reachable at the time of the panic. To set this system up, execute the following commands as root on the source (source#) and normal user on the target (target$):

Start a listener server on the target machine (netcat works well):

target$ nc -u -l -p 6666
Mount configfs (only once per boot, you can check if it is already mounted with mount | grep /sys/kernel/config. This will return no output if it is not).

source# modprobe configfs

source# mkdir -p /sys/kernel/config

source# mount none -t configfs /sys/kernel/config
find source's ethernet interface name, it should be of the form enp* or eth*, see ip address or ifconfig output.

source# iface="enp0s29f8u1" change this

Fill the target machine's IPv4 address here:

source# tgtip="192.168.1.2" change this
Create netconsole logging target on the source machine:

source# modprobe netconsole

source# cd /sys/kernel/config/netconsole

source# mkdir target1; cd target1

source# srcip=$(ip -4 addr show dev "$iface" | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+')

source# echo "$srcip" > local_ip

source# echo "$tgtip" > remote_ip

source# echo "$iface" > dev_name

source# arping -I "$iface" "$tgtip" -f | grep -o '..:..:..:..:..:..' > remote_mac

source# echo 1 > enabled
Change console loglevel to debugging:

source# dmesg -n debug
Test if the logging works by e.g. inserting or removing an USB device on the source. There should be a few lines appearing in the terminal, in which you started netcat (nc), on the target host.
Try to reproduce the kernel panic.

Hardware compatibility

What systems are compatible with Retroboot?

See the hardware compatibility list.

Information about freedom issues in modern Intel hardware? {#intel}

Intel Management Engine (ME) {#intelme}

NOTE: The information below is slightly out of date. Nowadays, Intel ME does not run on an ARC coprocessor, but instead runs on a modified Intel 486 based architecture, with the ME firware written for x86 based on the Minix operating system. However, the overall design philosophy and operation is mostly the same.

On most current Intel platforms that have Intel ME, it is possible to partly disable it. See:

https://github.com/corna/me_cleaner

The me_cleaner utility strips out a lot of code from the Intel ME, including networking and AMT. It leaves only a ~90kb or so binary blob that does basic initialization and power management, running only at boot time. It sets the ME Alt Disable bit in the Intel Flash Descriptor and essentially "neuters" the ME, making it safer to use (operating systems will report that the ME is missing or "malfunctioning" and the ME/AMT features will no longer work). This is considered acceptable from a security perspective for Retroboot, and on systems it supports that have intel ME, the ME only handles a minority of hardware functions where coreboot handles the rest.

The information below (with the above notes in mind) applies to systems that do not have modified ME firmware based on the me_cleaner utility.

Introduced in June 2006 in Intel's 965 Express Chipset Family of (Graphics and) Memory Controller Hubs, or (G)MCHs, and the ICH8 I/O Controller Family, the Intel Management Engine (ME) is a separate computing environment physically located in the (G)MCH chip. In Q3 2009, the first generation of Intel Core i3/i5/i7 (Nehalem) CPUs and the 5 Series Chipset family of Platform Controller Hubs, or PCHs, brought a more tightly integrated ME (now at version 6.0) inside the PCH chip, which itself replaced the ICH. Thus, the ME is present on all Intel desktop, mobile (laptop), and server systems since mid 2006.

The ME consists of an ARC processor core (replaced with other processor cores in later generations of the ME), code and data caches, a timer, and a secure internal bus to which additional devices are connected, including a cryptography engine, internal ROM and RAM, memory controllers, and a direct memory access (DMA) engine to access the host operating system's memory as well as to reserve a region of protected external memory to supplement the ME's limited internal RAM. The ME also has network access with its own MAC address through an Intel Gigabit Ethernet Controller. Its boot program, stored on the internal ROM, loads a firmware "manifest" from the PC's SPI flash chip. This manifest is signed with a strong cryptographic key, which differs between versions of the ME firmware. If the manifest isn't signed by a specific Intel key, the boot ROM won't load and execute the firmware and the ME processor core will be halted.

The ME firmware is compressed and consists of modules that are listed in the manifest along with secure cryptographic hashes of their contents. One module is the operating system kernel, which is based on a proprietary real-time operating system (RTOS) kernel called "ThreadX". The developer, Express Logic, sells licenses and source code for ThreadX. Customers such as Intel are forbidden from disclosing or sublicensing the ThreadX source code. Another module is the Dynamic Application Loader (DAL), which consists of a Java virtual machine and set of preinstalled Java classes for cryptography, secure storage, etc. The DAL module can load and execute additional ME modules from the PC's HDD or SSD. The ME firmware also includes a number of native application modules within its flash memory space, including Intel Active Management Technology (AMT), an implementation of a Trusted Platform Module (TPM), Intel Boot Guard, and audio and video DRM systems.

The Active Management Technology (AMT) application, part of the Intel "vPro" brand, is a Web server and application code that enables remote users to power on, power off, view information about, and otherwise manage the PC. It can be used remotely even while the PC is powered off (via Wake-on-Lan). Traffic is encrypted using SSL/TLS libraries, but recall that all of the major SSL/TLS implementations have had highly publicized vulnerabilities. The AMT application itself has known vulnerabilities, which have been exploited to develop rootkits and keyloggers and covertly gain encrypted access to the management features of a PC. Remember that the ME has full access to the PC's RAM. This means that an attacker exploiting any of these vulnerabilities may gain access to everything on the PC as it runs: all open files, all running applications, all keys pressed, and more.

Intel Boot Guard is an ME application introduced in Q2 2013 with ME firmware version 9.0 on 4th Generation Intel Core i3/i5/i7 (Haswell) CPUs. It allows a PC OEM to generate an asymmetric cryptographic keypair, install the public key in the CPU, and prevent the CPU from executing boot firmware that isn't signed with their private key. This means that coreboot is impossible to port to such machines, without the OEM's private signing key. Note that systems assembled from separately purchased mainboard and CPU parts are unaffected, since the vendor of the mainboard (on which the boot firmware is stored) can't possibly affect the public key stored on the CPU.

NOTE: A few people in the coreboot project are investigating ways to circumvent the Intel Boot Guard, and some discoveries have been made on certain platforms. However, Retroboot does not currently include support for any of those machines which do have the Boot Guard enabled.

ME firmware versions 4.0 and later (Intel 4 Series and later chipsets) include an ME application for audio and video DRM called "Protected Audio Video Path" (PAVP). The ME receives from the host operating system an encrypted media stream and encrypted key, decrypts the key, and sends the encrypted media decrypted key to the GPU, which then decrypts the media. PAVP is also used by another ME application to draw an authentication PIN pad directly onto the screen. In this usage, the PAVP application directly controls the graphics that appear on the PC's screen in a way that the host OS cannot detect. ME firmware version 7.0 on PCHs with 2nd Generation Intel Core i3/i5/i7 (Sandy Bridge) CPUs replaces PAVP with a similar DRM application called "Intel Insider". Like the AMT application, these DRM applications, which in themselves are defective by design, demonstrate the omnipotent capabilities of the ME: this hardware and its proprietary firmware can access and control everything that is in RAM and even everything that is shown on the screen.

The Intel Management Engine with its proprietary firmware has complete access to and control over the PC: it can power on or shut down the PC, read all open files, examine all running applications, track all keys pressed and mouse movements, and even capture or display images on the screen. And it has a network interface that is demonstrably insecure, which can allow an attacker on the network to inject rootkits that completely compromise the PC and can report to the attacker all activities performed on the PC. It is a threat to freedom, security, and privacy that can't be ignored.

Before version 6.0 (that is, on systems from 2008/2009 and earlier), the ME can be disabled by setting a couple of values in the SPI flash memory. The ME firmware can then be removed entirely from the flash memory space. Libreboot does this on the Intel 4 Series systems that it supports, such as the Libreboot X200 and Libreboot T400. ME firmware versions 6.0 and later, which are found on all systems with an Intel Core i3/i5/i7 CPU and a PCH, include "ME Ignition" firmware that performs some hardware initialization and power management. If the ME's boot ROM does not find in the SPI flash memory an ME firmware manifest with a valid Intel signature, the whole PC will shut down after 30 minutes.

Due to the signature verification, developing free replacement firmware for the ME is difficult. It might be possible to dump the ME bootrom on certain dev hardware, and potentially find security vulnerabilities in it that allow some freedoms for us. The only entity capable of replacing the ME firmware right now is Intel. As previously stated, the ME includes proprietary code licensed from third parties, so Intel couldn't release the source code even if they wanted to. Even if they developed completely new ME firmware without third-party proprietary code and released its source code, the ME's boot ROM would reject any modified firmware that isn't signed by Intel. Thus, the ME firmware is both hopelessly proprietary and "tivoized".

In summary, the Intel Management Engine is OK so long as you use the me_cleaner utility to remove the nasty anti-features and security threat that it poses. If you do not use me_cleaner, or your system is not supported by it, the Retroboot project strongly recommends against use of that hardware in normal everyday computing, except for the purposes of reverse engineering.

More information about the Management Engine can be found on various Web sites, including me.bios.io, unhuffme, coreboot wiki, and Wikipedia. The book Platform Embedded Security Technology Revealed describes in great detail the ME's hardware architecture and firmware application modules.

Firmware Support Package (FSP) {#fsp}

In the Retroboot project, FSP based systems in coreboot are not considered to be coreboot. Instead, it is referred to as shimboot. Retroboot mainly allows boards from coreboot that are 100% free software in coreboot; the only exception allowed right now is VGA Option ROMs for the graphics processor, Intel ME if me_cleaner is compatible, and CPU microcode updates. When considering whether to add a given board from coreboot, judgement will be made on a case by case basis. Generally, it is preferred that a board in Retroboot must be 100% free software in the coreboot repository, or very nearly free software with only minor freedom issues. The purpose of the Retroboot project is to reduce the amount of non-free software people use when they don't want to use a Libreboot system, which is all free software in the boot flash; Retroboot is about harm reduction.

The Intel FSP is definitely harmful to your freedom, in no uncertain terms. Read on to learn more:

On all new Intel platforms that come out, coreboot support has revolved around integrating a blob (for each system) called the FSP (firmware support package), which handles all of the hardware initialization, including memory and CPU initialization. Reverse engineering and replacing this blob is very difficult, but coreboot developers work on it daily. Even for a skilled developer, it would take years to replace everything. Intel distributes this blob to firmware developers, without source code.

Since the FSP is responsible for the early hardware initialization, that means it also handles SMM (System Management Mode). This is a special mode that operates below the operating system level. It's possible that rootkits could be implemented there, which could perform a number of attacks on the user (the list is endless). Any Intel system that has the proprietary FSP blob cannot be trusted at all. In fact, several SMM rootkits have been demonstrated in the wild (use a search engine to find them).

CPU microcode updates {#microcode}

All modern x86 CPUs (from Intel and AMD) use what is called microcode. CPUs are extremely complex, and difficult to get right, so the circuitry is designed in a very generic way, where only basic instructions are handled in hardware. Most of the instruction set is implemented using microcode, which is low-level software running inside the CPU that can reconfigures arrays of logic gates, for each instruction. The built-in microcode is part of the hardware, and read-only. Both the circuitry and the microcode can have bugs, which could cause reliability issues.

Microcode updates are proprietary blobs, uploaded to the CPU at boot time, which patch the built-in microcode and disable buggy parts of the CPU to improve reliability. In the past, these updates were handled by the operating system kernel, but on most computers it is the boot firmware that will perform this task. Coreboot does distribute microcode updates for Intel and AMD CPUs, and retroboot adds them to all supported machines that use microcode. Technically, the microcode updates are non-free software but so is the microcode built in to the CPU. If you choose not to use the microcode, you're still using an older/buggier version burned into the CPU, so freedom-wise the updates make zero difference except in terms of symbolism.

Retroboot highly recommends installing the microcode updates. Retroboot supplies these updates by default, on all x86 platforms supported. The updates are volatile, which means they have to be re-applied each time the system reboots.

On some older Intel/AMD CPUs, it is possible to exclude the microcode updates and not have any reliability issues in practise. However, not including them can cause all kinds of issues, such as:

Unstable raminit (initialization of memory controller)
General instability and corruption of data
Unpredictable behaviour of the CPU. Your software could behave in weird ways and you could potentially lose data.
No support from the manufacturer. They will consider your CPU as being out of spec if you are not running the latest updates.
Potential for security issues.

Intel CPU microcode updates are signed, which means that you could not even run a modified version, even if you had the source code. If you try to upload your own modified updates, the CPU will reject them. In practise, access to source code wouldn't be as useful because information about the CPU is withheld by the manufacturer.

As far as the Retroboot project is concerned, you agree to use non-free microcode when you buy an Intel or AMD processor or system that has one. There are many good projects out there, such as RISC-V, attempting to produce completely libre CPUs and computing platforms. If you're using an x86 CPU, you may aswell just apply the microcode updates at boot time.

Intel is uncooperative

For years, coreboot has been struggling against Intel. Intel has been shown to be extremely uncooperative in general. Many coreboot developers, and companies, have tried to get Intel to cooperate; namely, releasing source code for the firmware components. Even Google, which sells millions of chromebooks (coreboot preinstalled) have been unable to persuade them.

Even when Intel does cooperate, they still don't provide source code. They might provide limited information (datasheets) under strict corporate NDA (non-disclosure agreement), but even that is not guaranteed. Even ODMs and IBVs can't get source code from Intel, in most cases (they will just integrate the blobs that Intel provides).

Recent Intel graphics chipsets also require firmware blobs.

Intel is only going to get worse when it comes to user freedom. Retroboot has no support for recent Intel platforms, precisely because of the problems described above. The only way to solve this is to get Intel to change their policies and to be more friendly to the free software community. Reverse engineering won't solve anything long-term, unfortunately, but we need to keep doing it anyway. Moving forward, Intel hardware is a non-option unless a radical change happens within Intel. Likewise, Retroboot doesn't support modern Intel platforms because of the FSP situation and a whole host of other reasons (Sandybridge and Ivybridge are currently the most modern Intel platforms that the Retroboot project recommends. Such hardware is circa 2012/2013 and still holds up performance/feature-wise compared to modern platforms).

There is still a great potential for new Intel platforms to be added to Retroboot, however! Lots of Sandybridge and Ivybridge platforms are supported by coreboot, and later platforms are quickly becoming feasible due to excellent work done by the coreboot project.

Information about freedom issues in modern AMD hardware {#amd}

AMD used to contribute source code to the coreboot project, for many of their platforms. They did not write native code for coreboot, based on coreboot design principles. Instead, they did code drops of scrubbed versions of their AGESA codebase, which has a very different design than coreboot.

Coreboot made attempts to integrate AGESA, bolting it on top of the coreboot codebase. Many boards were added to coreboot, using AGESA as a base.

Unfortunately, AMD stopped providing source code. They continued providing AGESA updates to the coreboot project, but in the form of binary blobs. Same as how Intel provides FSP as binary blobs (and always did).

AMD Platform Security Processor (PSP)

This is basically AMD's own version of the Intel Management Engine. It has all of the same basic security and freedom issues, although the implementation is wildly different.

The Platform Security Processor (PSP) is built in on the AMD CPUs whose architecture is Late Family 16h (Puma), Zen 17h or later (and also on the AMD GPUs which are GCN 5th gen (Vega) or later). On the CPUs, a PSP controls the main x86 core startup. PSP firmware is cryptographically signed with a strong key similar to the Intel ME. If the PSP firmware is not present, or if the AMD signing key is not present, the x86 cores will not be released from reset, rendering the system inoperable.

The PSP is an ARM core with TrustZone technology, built onto the main CPU die. As such, it has the ability to hide its own program code, scratch RAM, and any data it may have taken and stored from the lesser-privileged x86 system RAM (kernel encryption keys, login data, browsing history, keystrokes, who knows!). To make matters worse, the PSP theoretically has access to the entire system memory space (AMD either will not or cannot deny this, and it would seem to be required to allow the DRM "features" to work as intended), which means that it has at minimum MMIO-based access to the network controllers and any other PCI/PCIe peripherals installed on the system.

In theory any malicious entity with access to the AMD signing key would be able to install persistent malware that could not be eradicated without an external flasher and a known good PSP image. Furthermore, multiple security vulnerabilities have been demonstrated in AMD firmware in the past, and there is every reason to assume one or more zero day vulnerabilities are lurking in the PSP firmware. Given the extreme privilege level (ring -2 or ring -3) of the PSP, said vulnerabilities would have the ability to remotely monitor and control any PSP enabled machine completely outside of the user's knowledge.

Much like with the Intel Boot Guard (an application of the Intel Management Engine), AMD's PSP can also act as a tyrant by checking signatures on any boot firmware that you flash, making replacement boot firmware (e.g. retroboot, libreboot, coreboot) impossible on some boards. Early anecdotal reports indicate that AMD's boot guard counterpart will be used on most OEM hardware, disabled only on so-called "enthusiast" CPUs.

AMD IMC firmware

Read https://www.coreboot.org/AMD_IMC.

AMD SMU firmware

Handles some power management for PCIe devices (without this, your laptop will not work properly) and several other power management related features.

The firmware is signed, although on older AMD hardware it is a symmetric key, which means that with access to the key (if leaked) you could sign your own modified version and run it. Rudolf Marek (coreboot hacker) found out how to extract this key in this video demonstration, and based on this work, Damien Zammit (another coreboot hacker) partially replaced it with free firmware.

AMD AGESA firmware

This is responsible for virtually all core hardware initialization on modern AMD systems. In 2011, AMD started cooperating with the coreboot project, releasing this as source code under a free license. In 2014, they stopped releasing source code and started releasing AGESA as binary blobs instead. This makes AGESA now equivalent to Intel FSP.

AMD CPU microcode updates

Read the Intel section practically the same, though it was found with much later hardware in AMD that you could run without microcode updates and not have many reliability issues, unlike on Intel CPUs which tend to be unstable without these updates. It's unknown whether the updates are needed on all AMD boards (depends on CPU).

As always, Retroboot recommends installing the updates at boot time.

At present, Retroboot does not integrate support for AMD hardware.

AMD is uncooperative

AMD seemed like it was on the right track in 2011 when it started cooperating with and releasing source code for several critical components to the coreboot project. It was not to be. For so-called economic reasons, they decided that it was not worth the time to invest in the coreboot project anymore. Unfortunately they haven't even shared the source code of AGESA library for a Family 15h Steamroller/Excavator architectures (which, like the earlier fam15h Bulldozer/Piledriver, do not have a PSP) and released it to a coreboot project only as a binary.

This is very sad. Retroboot's goal is for everyone to use Free Software. If something is already non-free, then it's rock bottom. However, for something free to become non-free later on is truly sad.

Given the current state of Intel hardware with the Management Engine, it is our opinion that all performant x86 hardware newer than the AMD Family 15h CPUs (on AMD's side) or anything post-2009 on Intel's side is defective by design and cannot safely be used to store, transmit, or process sensitive data. Sensitive data is any data in which a data breach would cause significant economic harm to the entity which created or was responsible for storing said data, so this would include banks, credit card companies, or retailers (customer account records), in addition to the "usual" engineering and software development firms. This also affects whistleblowers, or anyone who needs actual privacy and security.

Will desktop/server hardware be supported?

Several sandybridge/ivybridge boards exist in coreboot that can be integrated in Retroboot. This is a high priority for the retroboot project. These systems can be used with all free software in coreboot, and you can use me_cleaner to neuter the Intel ME, much like on laptops.

Many new boards will be added to Retroboot! Anything coreboot supports that meets Retroboot's guidelines will be integrated. It's simply a matter of purchasing the hardware and testing it, to make sure everything works and then support can be added; either testing is done by a Retroboot developer, or support is added but testing is outsourced to a third party user.

If you have a board that you think could be added to Retroboot, and you have access to debugging equipment (e.g. FT232H or other EHCI debug dongle) and external flashing equipment, and willingness to get your hands dirty, Retroboot could certainly benefit from your help!

Retroboot is, as of this date (24 December 2020) a very young project. In fact, this version of this section of the FAQ was written before the website even went online!

Hi, I have <insert random system here>, can it be supported?

First, you must consult coreboot's own hardware compatibility list at https://coreboot.org/status/board-status.html and, if it is supported, consult Retroboot via one of the support channels. A decision will be made, based on research of that mainboard.

For those systems where no coreboot support exists, you must first port it to coreboot.

Please note that board development should be done upstream (in coreboot) and merged downstream (into retroboot). This is the correct way to do it, and it is how the Retroboot project is coordinated so as to avoid too much forking of the coreboot source code.

What about ARM?

Coreboot supports many ARM SoCs, such as the Rockchip platforms.

These can be added. It's just a matter of acquiring each machine for testing, so that it can be developed on and integrated into the Retroboot build system!

Freedom-wise, a lot of these Rockchip platfroms are superior to x86, because:

No microcode whatsoever, not even inside the CPU (everything is done in hardware, and everything is bare metal)
Libre EC (embedded controller) firmware on a lot of those machines
Nowadays, the Panfrost project exists which is a reversed engineered driver collection for the Mali Midguard and Bitfrost GPUs, and is now mainlined in the Linux kernel! Alyssa Rosenzweig is the project's founder, and she also used to be a member of the Libreboot project. You can find the Panfrost project here: https://panfrost.freedesktop.org/

General questions

How do I install Retroboot?

See installation guide

How do I program an SPI flash chip?

SPI flash chips can be programmed with the Raspberry Pi.

It's possible to use a 16-pin SOIC test clip on an 8-pin SOIC chip, if you align the pins properly. The connection is generally more sturdy.

If doing ISP, make sure the VCC lines going to the flash chip on the mainboard are properly isolated (using diodes) so that external power from your SPI flasher is only powering the flash chip; also put 47ohm resistors on the data lines (this should also be done when not doing ISP, like when flashing a chip that is not yet soldered/connected to a mainboard).

STM32 Blue Pill is a low-cost serprog-compatible SPI flash solution which the Retroboot project is looking into. For now, the documentation for RPi is adequate for giving you a stable, reliable flashing setup.

How do I set a boot password?

If you are using the GRUB payload, you can add a username and password (salted, hashed) to your GRUB configuration that resides inside the flash chip. The following guides (which also cover full disk encryption, including the /boot/ directory) show how to set a boot password in GRUB: (Installing Debian or Devuan with FDE) and (Installing Parabola or Arch GNU+Linux-Libre, with FDE)

How do I write-protect the flash chip?

By default, there is no write-protection on a Retroboot system. This is for usability reasons, because most people do not have easy access to an external programmer for re-flashing their firmware, or they find it inconvenient to use an external programmer.

On some systems, it is possible to write-protect the firmware, such that it is rendered read-only at the OS level (external flashing is still possible, using dedicated hardware).

It's possible to write-protect on all Retroboot systems, but the instructions need to be written. The documentation is in the main git repository, so you are welcome to submit patches adding these instructions.

The instructions will differ depending on your flash chip. Consult the datasheet for your flash chip. Some platforms also provide options; for instance, on Intel Flash Descriptor (for most platforms) you can can regions of the flash chip to read-only, write-only or read-write. The ifdtool utility in coreboot (also included in Retroboot) can handle this for you.

How do I change the BIOS settings?

Retroboot actually uses the GRUB payload on some boards. More information about payloads can be found at coreboot.org/Payloads.

On some boards, Retroboot also provides you the option to use SeaBIOS. You can refer to the SeaBIOS page for information:

https://www.coreboot.org/SeaBIOS

https://seabios.org/SeaBIOS may also provide some useful information.

Retroboot also provides the option to use Tianocore UEFI payload on some boards. Documentation has not yet been written in Retroboot for this, and this is very much experimental for Retroboot purposes. Documentation will be written for this at a later date, or links will be provided to other sources (such as the official Tianocore documentation).

Retroboot inherits the modular payload concept from coreboot, which means that pre-OS bare-metal BIOS setup programs are not very practical. Coreboot (and retroboot) does include a utility called nvramtool, which can be used to change some settings. You can find nvramtool under coreboot/util/nvramtool/, in the Retroboot source archives. Nvramtool is mainly not useful in Retroboot, because NVRAM/CMOS settings are hardcoded by default, set to defaults in each ROM, with modifications made to the defaults.

However, you can dump the ROM that you're using and run nvram on that to change the defaults. See below for information.

The -a option in nvramtool will list the available options, and -w can be used to change them. Consult the nvramtool documentation on the coreboot wiki for more information.

In practise, you don't need to change any of those settings, in most cases.

Retroboot locks the CMOS table, to ensure consistent functionality for all users. You can use:

$ nvramtool -C yourrom.rom -w somesetting=somevalue

This will change the default inside that ROM image, and then you can re-flash it.

How do I pad a ROM before flashing?

Required for ROMs where the ROM image is smaller than the flash chip (e.g. writing a 2MiB ROM to a 16MiB flash chip).

Create an empty (00 bytes) file with a size the difference between the ROM and flash chip. The case above, for example:

$ truncate -s +14MiB pad.bin

For x86 descriptorless images you need to pad from the beginning of the ROM:

$ cat pad.bin yourrom.rom > yourrom.rom.new

For ARM and x86 with intel flash descriptor, you need to pad after the image:

$ cat yourrom.rom pad.bin > yourrom.rom.new

Flash the resulting file. Note that cbfstool will not be able to operate on images padded this way so make sure to make all changes to the image, including runtime config, before padding.

To remove padding, for example after reading it off the flash chip, simply use dd(1) to extract only the non-padded portion. Continuing with the examples above, in order to extract a 2MiB x86 descriptorless ROM from a padded 16MiB image do the following:

$ dd if=flashromread.rom of=yourrom.rom ibs=14MiB skip=1

With padding removed cbfstool will be able to operate on the image as usual.

Do I need to install a bootloader when installing a distribution?

Retroboot integrates the GRUB bootloader already, on some boards, as a payload. This means that the GRUB bootloader is actually flashed, as part of the boot firmware (Retroboot). This means that you do not have to install a boot loader on the HDD or SSD, when installing a new distribution. You'll be able to boot just fine, using the bootloader (GRUB) that is in the flash chip.

This also means that even if you remove the HDD or SSD, you'll still have a functioning bootloader installed which could be used to boot a live distribution installer from a USB flash drive. See How to install GNU+Linux on a Retroboot system

However, not all boards standardize on GRUB. You can also use SeaBIOS or Tianocore and a bootloader is required on your HDD/SSD for either of these options.

In general, it is recommended that you install with a bootloader present on the HDD, tested and confirmed working, so that it is compatible regardless of whether you use GRUB or some other payload.

Do I need to re-flash when I re-install a distribution?

Retroboot (using the GRUB payload) will automatically switch to a GRUB configuration on the HDD or SSD, if it exists. You can also load a different GRUB configuration, from any kind of device that is supported in GRUB (such as a USB flash drive). For more information, see Modifying the GRUB Configuration in Retroboot Systems

GRUB as payload is a very non standard thing and will directly boot any kernel it has support for, such as Linux kernels and various BSD kernels. These kernels are then running on bare metal, not in BIOS or UEFI. The Linux kernel is capable of bare metal execution; in fact, coreboot payloads such as linuxboot exist for this very reason!

If using SeaBIOS, anything BIOS-compatible will just work. SeaBIOS automatically detects devices such as BIOS compatible bootable USB drives (e.g. BIOS compatible GNU+Linux installer / live system) and HDD/SSD partitions (using MBR partitioning) which you can then boot from.

If using Tianocore, anything UEFI-compatible will just work. Tianocore automatically detects devices such as UEFI compatible USB drives (e.g. UEFI compatible GNU+Linux installer / live system) and HDD/SSD partitions (using GPT partitioning) which you can then boot from.

What does a flash chip look like?

SOIC-8 SPI flash chip:

SOIC-16 SPI flash chip:

Those are just common examples. WSON8 chips are not linked above, for example.

What other firmware exists outside of Retroboot?

The main freedom issue on any system, is the boot firmware (usually referred to as a BIOS or UEFI). Retroboot replaces the boot firmware with as much free software as is feasible, but there may still be other hardware components in the system (e.g. laptop) that run their own dedicated firmware, sometimes proprietary. These are on often secondary processors, where the firmware is usually read-only, written for very specific tasks. While these are unrelated to Retroboot, technically speaking, it makes sense to document some of the issues here.

Note that these issues are not unique to Retroboot systems. They apply universally, to most systems. The issues described below are the most common (or otherwise critical).

External GPUs

The Video BIOS is present on most video cards. For integrated graphics, the VBIOS (special kind of OptionROM) is usually embedded in the main boot firmware. For external graphics, the VBIOS is usually on the graphics card itself. This is usually proprietary; the only difference is that SeaBIOS can execute it (alternatively, you embed it in a coreboot ROM image and have coreboot executes it, if you use a different payload, such as GRUB).

EC (embedded controller) firmware

Most (all?) laptops have this. The EC (embedded controller) is a small, separate processor that basically processes inputs/outputs that are specific to laptops. For example:

When you flick the radio on/off switch, the EC will enable/disable the wireless devices (wifi, bluetooth, etc) and enable/disable an LED that indicates whether it's turned on or not
Listen to another chip that produces temperature readings, adjusting fan speeds accordingly (or turning the fan(s) on/off).
Takes certain inputs from the keyboard, e.g. brightness up/down, volume up/down.
Detect when the lid is closed or opened, and send a signal indicating this.
Etc.

Alexander Couzens from coreboot (lynxis on coreboot IRC) is/was working on a free EC firmware replacement for the ThinkPads that are supported in libreboot/retroboot. See: https://github.com/lynxis/h8s-ec (not ready yet) in addition to reverse engineering how it is flashed externally. Swiftgeek from the Libreboot project has continued this research.

EC is present on nearly all laptops. Other devices use, depending on complexity, either EC and/or variant with firmware in Mask ROM such as SuperIO.

HDD/SSD firmware

HDDs and SSDs have firmware in them, intended to handle the internal workings of the device while exposing a simple, standard interface (such as AHCI/SATA) that the OS software can use, generically. This firmware is transparent to the user of the drive.

HDDs and SSDs are quite complex, and these days contain quite complex hardware which is even capable of running an entire operating system (by this, we mean that the drive itself is capable of running its own embedded OS), even GNU+Linux or BusyBox/Linux.

SSDs and HDDs are a special case, since they are persistent storage devices as well as computers.

Example attack that malicious firmware could do: substitute your SSH keys, allowing unauthorized remote access by an unknown adversary. Or maybe substitute your GPG keys. SATA drives can also have DMA (through the controller), which means that they could read from system memory; the drive can have its own hidden storage, theoretically, where it could read your LUKS keys and store them unencrypted for future retrieval by an adversary.

With proper IOMMU and use of USB instead of SATA, it might be possible to mitigate any DMA-related issues that could arise.

Some proof of concepts have been demonstrated. For HDDs: https://spritesmods.com/?art=hddhack&page=1 For SSDs: http://www.bunniestudios.com/blog/?p=3554

Viable free replacement firmware is currently unknown to exist. For SSDs, the OpenSSD project may be interesting.

Apparently, SATA drives themselves don't have DMA but can make use of it through the controller. This http://www.lttconn.com/res/lttconn/pdres/201005/20100521170123066.pdf (pages 388-414, 420-421, 427, 446-465, 492-522, 631-638) and this http://www.intel.co.uk/content/dam/www/public/us/en/documents/technical-specifications/serial-ata-ahci-spec-rev1_3.pdf (pages 59, 67, 94, 99).

The following is based on discussion with Peter Stuge (CareBear\) in the coreboot IRC channel on Friday, 18 September 2015, when investigating whether the SATA drive itself can make use of DMA. The following is based on the datasheets linked above:

According to those linked documents, FIS type 39h is *"DMA Activate FIS

Device to Host"*. It mentions "transfer of data from the host to the device, and goes on to say: Upon receiving a DMA Activate, if the host adapter's DMA controller has been programmed and armed, the host adapter shall initiate the transmission of a Data FIS and shall transmit in this FIS the data corresponding to the host memory regions indicated by the DMA controller's context." FIS is a protocol unit (Frame Information Structure). Based on this, it seems that a drive can tell the host controller that it would like for DMA to happen, but unless the host software has already or will in the future set up this DMA transfer then nothing happens. A drive can also send DMA Setup. If a DMA Setup FIS is sent first, with the Auto-Activate bit set, then it is already set up, and the drive can initiate DMA. The document goes on to say "Upon receiving a DMA Setup, the receiver of the FIS shall validate the received DMA Setup request." - in other words, the host is supposed to validate; but maybe there's a bug there. The document goes on to say "The specific implementation of the buffer identifier and buffer/address validation is not specified" - so noone will actually bother. "the receiver of the FIS" - in the case we're considering, that's the host controller hardware in the chipset and/or the kernel driver (most likely the kernel driver). All SATA devices have flash-upgradeable firmware, which can usually be updated by running software in your operating system; malicious software running as root could update this firmware, or the firmware could already be malicious. Your HDD or SSD is the perfect place for a malicious adversary to install malware, because it's a persistent storage device as well as a computer.

Based on this, it's safe to say that use of USB instead of SATA is advisable if security is a concern. USB 2.0 has plenty of bandwidth for many HDDs (a few high-end ones can use more bandwidth than USB 2.0 is capable of), but for SSDs it might be problematic (unless you're using USB 3.0, which is not yet usable in freedom. See

Use of USB is also not an absolute guarantee of safety, so do beware. The attack surface becomes much smaller, but a malicious drive could still attempt a "fuzzing" attack (e.g. sending malformed USB descriptors, which is how the tyrant DRM on the Playstation 3 was broken, so that users could run their own operating system and run unsigned code). (you're probably safe, unless there's a security flaw in the USB library/driver that your OS uses. USB is generally considered one of the safest protocols, precisely because USB devices have no DMA)

NIC (ethernet controller)

Ethernet NICs will typically run firmware inside, which is responsible for initializing the device internally. Theoretically, it could be configured to drop packets, or even modify them.

With proper IOMMU, it might be possible to mitigate the DMA-related issues. A USB NIC can also be used, which does not have DMA.

CPU microcode

Implements an instruction set. See description. Here we mean microcode built in to the CPU. We are not talking about the updates supplied by the boot firmware. Microcode can be very powerful. No proof that it's malicious, but it could theoretically

There isn't really a way to solve this, unless you use a CPU which does not have microcode. Every choice you make implies compromise at some level, so it's basically pick your poison.

CPUs often on modern systems have a processor inside it for things like power management. ARM for example, has lots of these.

Sound card

Sound hardware (integrated or discrete) typically has firmware on it (DSP) for processing input/output. Again, a USB DAC is a good workaround.

Webcam

Webcams have firmware integrated into them that process the image input into the camera; adjusting focus, white balancing and so on. Can use USB webcam hardware, to work around potential DMA issues.

Most laptops will use USB internally, for integrated webcams.

USB host controller

Doesn't really apply to current Retroboot systems (none of them have USB 3.0 at the moment), but USB 3.0 host controllers typically rely on firmware to implement the XHCI specification. Some newer coreboot ports also require this blob, if you want to use USB 3.0.

With proper IOMMU, it might be possible to mitigate the DMA-related issues (with the host controller).

WWAN firmware

Some laptops might have a simcard reader in them, with a card for handling WWAN, connecting to a 3g/4g (e.g. GSM) network. This is the same technology used in mobile phones, for remote network access (e.g. internet).

NOTE: not to be confused with wifi. Wifi is a different technology, and entirely unrelated.

The baseband processor inside the WWAN chip will have its own embedded operating system, most likely proprietary. Use of this technology also implies the same privacy issues as with mobile phones (remote tracking by the GSM network, by triangulating the signal).

On some laptops, these cards use USB (internally), so won't have DMA, but it's still a massive freedom and privacy issue. If you have an internal WWAN chip/card, the Retroboot project recommends that you disable and (ideally, if possible) physically remove the hardware. If you absolutely must use this technology, an external USB dongle is much better because it can be easily removed when you don't need it, thereby disabling any external entities from tracking your location.

Use of ethernet or wifi is recommended, as opposed to mobile networks, as these are generally much safer.

On all current Retroboot laptops, it is possible to remove the WWAN card and sim card if it exists. The WWAN card is next to the wifi card, and the sim card (if installed) will be in a slot underneath the battery, or next to the RAM.

Operating Systems

Can I use GNU+Linux?

Absolutely! It is well-tested in Retroboot, and highly recommended. See installing GNU+Linux and booting GNU+Linux.

Any recent distribution should work, as long as it uses KMS (kernel mode setting) for the graphics if using pure GRUB payload and native graphics initialization in coreboot.

If using VGA ROM, obviously it will also work. GNU+Linux will work with any Retroboot ROM, using any payload.

Fedora won't boot? (may also be applicable to Redhat/CentOS)

On Fedora, by default the grub.cfg tries to boot linux in 16-bit mode. You just have to modify Fedora's GRUB configuration. Refer to the GNU+Linux page.

Can I use BSD?

Absolutely! Retroboot has native support for NetBSD, OpenBSD and LibertyBSD when using the GNU GRUB bootloader as payload option.

If using SeaBIOS or Tianocore, BSD will absolutely work aswell.

See: docs/bsd/

Are other operating systems compatible? (e.g. Windows)

Yes! On all systems currently supported in Retroboot, the option exists to use SeaBIOS with a VGA option ROM from the manufacturer of the video chipset in use on that machine. SeaBIOS can also load PCI option ROMs from add-on video cards, and provide BIOS services for legacy OS aswell.

ROMs with SeaBIOS and SeaVGABIOS will not work well with legacy operating systems that use Int 10H video callbacks (BIOS interrupts). SeaVGABIOS is a libre VGA ROM that runs under the coreboot framebuffer; it has support for a lot of functionality but currently does not support mode switching very well.

Most modern operating systems that are UEFI compatible will work on Retroboot systems if they have a ROM with the Tianocore UEFI payload in use. This includes Windows! (recent versions only. some older Windows versions are UEFI compatible but still use Int 10H video BIOS interrupt services for certain video functions).

Generally speaking, the most compatible options are, if you want to ensure maximum OS support:

SeaBIOS + non-free VGA option ROM with proper mode switching support
Tianocore + non-free VGA option ROM (with SeaBIOS as CSM for Tianocore, for legacy operating systems)

However, GNU+Linux and BSD distros will work very well with any Retroboot system, regardless of which ROM you use (even ones that use less non-free software such as VGA option ROM, where instead native video initialization is used in coreboot).

Does Retroboot make my machine 100% free?

The correct answer is: no. See the section above titled What other firmware exists outside of Retroboot?

Retroboot on all devices only provides host hardware init firmware images, that can be written 25XX SPI NOR Flash. On many systems there are a lot more computers running blob firmware. Some of them are not practicable to replace due to being located on Mask ROM. Some devices have EC firmware being build as well. Additionally, besides software components, there are hardware ones (from ICs to boards) that are not released on OSHW licenses. We do not have a single device that would be "100% free", and such absolutes are nearly impossible to reach in the real world.

What can be said is that Retroboot severely reduces how much non-free software in use on your system, when you install and boot it.

Notable proprietary blobs (not a complete list):

All devices (see notes above about other firmware)
- SATA/PATA Hard Drive/Optical Disc Drive Firmware (often contain powerful ARM based computer)
- Pendrives and any USB peripherals - they contain a computer with code running to at the very least handle the USB protocol
ThinkPads:
- EC Firmware (H8S until including Sandy Bridge, later ARC based MEC16xx)
- TrackPoint Firmware (8051)
- Penabled devices contain µPD78F0514 MCU on wacom subboard, and Atmega (AVR) on led indicator/button board
- Battery BMS, bq8030 (CoolRISC C816)
Chomebooks C201PA/C100PA:
- Battery BMS, bq30z55
- Elan Touchpad
- eMMC flash memory controller firmware

Where can I learn more about electronics

Basics of soldering and rework by PACE
Both series of videos are mandatory regardless of your soldering skill.
- Basic Soldering
- Rework and Repair
edX course on basics of electronics
In most countries contents of this course is covered during middle and high school. It will also serve well to refresh your memory if you haven't used that knowledge ever since.
Impedance intro
- Similiarities of Wave Behavior
- Reflections in tranmission line
- Stubs:
  - Wikipedia article on stubs
  - Polar Instruments article on stubs
    With external SPI flashing we only care about unintended PCB stubs
How to accurately measure header/connector pitch
Other YouTube channels with useful content about electronics
Boardview files can be open with OpenBoardview, which is free software under MIT license.

Use of youtube-dl with mpv would be recommended for youtube links

Lastly the most important message to everybody gaining this wonderful new hobby - Secret to Learning Electronics

faq.md 57 KB 永久連結 文件歷史 原始文件