|
|
| (21 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| − | {{ARM/breadcrumb}}
| + | This page has been moved to the official NixOS Wiki: |
| | | | |
| − | {{note|This page is written assuming <tt>AArch64</tt>. It is possible that following most of these instructions for <tt>armv7l</tt> would work just as well, but armv7l support in NixOS is not at a point where doing so will be nice.}}
| + | ⇒ '''[https://wiki.nixos.org/wiki/NixOS_on_ARM/UEFI NixOS on ARM/UEFI]''' |
| | | | |
| − | This section of the NixOS on ARM documentation aims to document as much as possible about booting ''any'' ARM boards using UEFI. This will be written with a heavy bias about ''Single Board Computers'' (SBCs), as this is where booting is seen as complicated, cumbersome, when not described as impossible.
| + | ''— samueldr, Lead of NixOS on ARM.'' |
| − | | |
| − | == The Basics First ==
| |
| − | | |
| − | === Target Support ===
| |
| − | | |
| − | Some things will not be specific to UEFI. For example, board support by the kernel used. This is written assuming that mainline Linux works enough on the target system so that you can install from the generic iso image.
| |
| − | | |
| − | Just as you could on <tt>x86_64</tt> if your platform required it, you can build a customized iso image. Explaining this is out of scope for this article. The same pitfalls apply. For example, the generated configuration will not take into account configuring the customized kernel.
| |
| − | | |
| − | === Initial Boot Firmware ===
| |
| − | | |
| − | Let's define what an '''Initial Boot Firmware''' is. It is a generic term I'm using to describe the first thing the CPU starts at boot time. On your typical <tt>x86_64</tt> system, it would be what was previously called the ''BIOS''. Now often diminutively called by the name ''EFI''. This is what initializes enough of the hardware so that the operating system can start. Additionally, it often provides facilities for the user to do basic configuration, and manage boot options.
| |
| − | | |
| − | In the ARM with SBCs landscape, '''U-Boot''' is the de facto solution for the ''Initial Boot Firmware''. Though ''U-Boot'' is confusingly, but rightly, often referred to as a ''Boot Loader''. ''U-Boot'' plays double duties often. It is tasked with ''initializing the hardware'', and often also used to handle ''loading and booting'' the operating system.
| |
| − | | |
| − | === UEFI ===
| |
| − | | |
| − | The ''[https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface Unified Extensible Firmware Interface]'' it not in itself a tangible thing. Wrongly abstracted, it is a specification used to provide an ''interface'' to describe a standard boot process, including an environment before the operating system starts, and protocols for operating systems.
| |
| − | | |
| − | There are multiple implementations of UEFI. Vendors like ''American Megatrends'', ''Phoenix Technologies'' and ''Insyde Software'' may have produced the one on your personal <tt>x86_64</tt> machine. '''TianoCore''' is ''the'' reference UEFI implementation, and Open Source. Luckily enough, ''U-Boot'' implements enough (and a bit more) of the UEFI spec.
| |
| − | | |
| − | ==== SBBR? EBBR? ====
| |
| − | | |
| − | Other than letter salads, they are ''Server Base Boot Requirements'' and ''Embedded Base Boot Requirements''. Two specifications for ARM. If your target is in compliance with either, booting with UEFI should already be supported. With the minimal UEFI support in ''U-Boot'', targets that were not made to be EBBR compliant can be made compliant, or be close enough for what it matters.
| |
| − | | |
| − | == UEFI, on my SBC??? ==
| |
| − | | |
| − | Believe me or not, it's more likely that you can, if your SBC is well supported by mainline ''U-Boot''. ''U-Boot'' provides enough UEFI to comply with EBBR, which in turn is enough to allow us to boot the <tt>AArch64</tt> UEFI NixOS iso, and with almost no differences compared to the <tt>x86_64</tt> guide, simply follow the installation instruction to boot into an installed system.
| |
| − | | |
| − | === Getting an ''Initial Boot Firmware'' ===
| |
| − | | |
| − | {{expansion|More details and alternative ways to go would be desirable}}
| |
| − | | |
| − | As an opinionated example, you can get started with [https://github.com/Tow-Boot/Tow-Boot Tow-Boot, a ''U-Boot'' distribution], which is intended to make the initial setup a bit easier by abstracting the platform differences so that they do not matter.
| |
| − | | |
| − | Any other UEFI complient ''Initial Boot Firmware'' can be used.
| |
| − | | |
| − | === Getting the installer image ===
| |
| − | | |
| − | For the time being, the following jobs are recommended:
| |
| − | | |
| − | * <tt>[https://hydra.nixos.org/job/nixos/trunk-combined/nixos.iso_minimal.aarch64-linux nixos:trunk-combined:nixos.iso_minimal.aarch64-linux]</tt>
| |
| − | * '''<tt>[https://hydra.nixos.org/job/nixos/trunk-combined/nixos.iso_minimal_new_kernel.aarch64-linux nixos:trunk-combined:nixos.iso_minimal_new_kernel.aarch64-linux]</tt>'''
| |
| − | | |
| − | With the ''new kernel'' variant being preferred
| |
| − | | |
| − | This installer image should be written to a USB drive, like usual. In a pinch, it may also be written to an SD image, if your target's initial boot firmware does not need to be written to that same SD image. This UEFI iso is incompatible (by design) with ''shared firmware storage''.
| |
| − | | |
| − | === Installing ===
| |
| − | | |
| − | Following [https://nixos.org/manual/nixos/stable/index.html#sec-installation the usual installation steps for UEFI] is almost enough. Here's what you need to be mindful about.
| |
| − | | |
| − | {{aside|title=Sidenote:|As the introduction stated, this guide '''assumes''' that the kernel in use '''fully supports''' your target board. If there are issues that comes from lack of hardware support, it is not a bug in this documentation.}}
| |
| − | | |
| − | ==== Shared Firmware Storage ====
| |
| − | | |
| − | {{note|This will make more sense when ''Getting an Initial Boot Firmware'' is finished...}}
| |
| − | | |
| − | If your ''Initial Boot Firmware'' lives on the target installation storage, e.g. written to an SD card and you install to the same SD card, you will need need to make sure that:
| |
| − | | |
| − | * You are not overwriting the firmware, if it is not protected by a partition.
| |
| − | * The partition table is not rewritten from scratch / zero.
| |
| − | * To not delete required existing firmware partitions.
| |
| − | | |
| − | {{note|If your ''Initial Boot Firmware'' is not protected by a partition, consider choosing an alternative ''Initial Boot Firmware'' installation method or distribution that protects it.}}
| |
| − | | |
| − | Otherwise, you can do as you would usually, create an ESP partition, FAT32, to be mounted at <code>/boot/</code>, your preferred rootfs partition, swap if desired, etc.
| |
| − | | |
| − | ==== Bootloader configuration ====
| |
| − | | |
| − | Know if your ''Initial Boot Firmware'''s UEFI implementation has writable EFI vars. This is not true for all UEFI implementations on ARM, but is something to be mindful about. If it does not, {{Nixos:option|boot.loader.efi.canTouchEfiVariables}} has to be set to '''<code>false</code>'''.
| |
| − | | |
| − | <syntaxhighlight lang="nix">
| |
| − | { /* configuration.nix */
| |
| − | boot.loader.efi.canTouchEfiVariables = false;
| |
| − | }
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | {{tip|Just like on <tt>x86_64</tt> [[REFInd|rEFInd]] installed to the fallback location (<code>/EFI/BOOT/BOOTAA64.EFI</code>) may be helpful.}}
| |
| − | | |
| − | For the time being, only GRUB2 has been verified to work. When using the systemd-boot bootloader on a test system, the kernel panics. Since EFI variables cannot be manipulated, using <code>efiInstallAsRemovable</code> handles installing GRUB2 to the default fallback location.
| |
| − | | |
| − | <syntaxhighlight lang="nix">
| |
| − | { /* configuration.nix */
| |
| − | boot.loader.grub.enable = true;
| |
| − | boot.loader.grub.efiSupport = true;
| |
| − | boot.loader.grub.efiInstallAsRemovable = true;
| |
| − | boot.loader.grub.device = "nodev";
| |
| − | }
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | === General Tips ===
| |
| − | | |
| − | Using the latest kernel is probably a good idea. Hardware support for ARM platforms is always improving, and using the latest kernel, rather than the "latest LTS", might be enough to break it or make it.
| |
| − | | |
| − | <syntaxhighlight lang="nix">
| |
| − | { /* configuration.nix */
| |
| − | boot.kernelPackages = pkgs.linuxPackages_latest;
| |
| − | }
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | == Known Issues ==
| |
| − | | |
| − | === Device Trees ===
| |
| − | | |
| − | As of right now, there is no consensus within Linux distros about the topic of managing device trees for the boot process with UEFI.
| |
| − | | |
| − | This current setup relies on the initial boot firmware providing an appropriate device tree for the kernel that will run.
| |
| − | | |
| − | With ''U-Boot'', it is possible to make it load a device tree, for example a more up-to-date one, by placing the dtb folder from a kernel build output at the <code>/dtb</code> location in the ESP. ''U-Boot'' will automatically load a device tree according to heuristics, which should be the right one.
| |
| − | | |
| − | It is unknown how much of an actual issue this is in practice.
| |