NixOS on ARM/Orange Pi 5 Plus: Difference between revisions

Line 28:

== System configuration ==

~~None of~~ the ~~basic~~ components ~~(Kernel~~, ~~HW acceleration drivers)~~ are ~~available from upstream NixOS~~.

Upstream nixpkgs provide kernel and u-boot for Orange Pi 5 Plus. The generic steps from [https://nixos.wiki/wiki/NixOS_on_ARM] apply to this board as well. Make sure the kernel you use is recent enough to support Pi 5 Plus though (6.15 and above are ok). Alternatively, you may use vendor-supplied components, flakes for which are provided by volunteers.

Join `#nixos-on-arm:nixos.org` Matrix channel to hang out with users that are running this board. ~~As of writing, here is an upstream PR for rk3588 boards: https://github.com/NixOS/nixpkgs/pull/292667~~

Join <code>#nixos-on-arm:nixos.org</code> Matrix channel to hang out with users that are running this board.

~~As of writing, building a working system requires additional configuration.~~

=== Using upstream Components with U-Boot ===

~~=== @ryan4yin's flake ===~~

1. If you have installed U-Boot into on-board SPI flash, you should be able to directly boot generic aarch64 NixOS images.

A minimal flake that ~~makes~~ NixOS ~~running on Orange Pi 5~~: https://github.com/~~ryan4yin~~/nixos-rk3588

2. If you want to have U-Boot on your SD card, you need to dd it into aarch64 NixOS image at the right offsets. Find the <code>idbloader.img</code> and <code>u-boot.itb</code> binaries in [https://search.nixos.org/packages?channel=25.11&show=ubootOrangePi5Plus ubootOrangePi5Plus] package and dd them into SD card image as shown below.

<pre>

dd if=idbloader.img of=sd-card.img seek=64 conv=fsync,notrunc

dd if=u-boot.itb of=sd-card.img seek=16384 conv=fsync,notrunc

</pre>

See the [https://github.com/gnull/nixos-rk3588/tree/main/examples/upstream-opi example from gnull/nixos-rk3588] for a minimal complete configuration to build an SD card image with U-Boot installed (option 2 above). In addition to choosing an appropriate kernel and <code>dd</code>'ing U-Boot into the image, the example also sets kernel parameters to enable the serial console.

The [https://github.com/Mic92/nixos-aarch64-images Mic92/nixos-aarch64-images] is another approach for installing U-Boot into aarch64 images (although with no direct support for OPi 5 Plus yet).

=== Using Vendor-supplied Components with U-Boot ===

[https://github.com/gnull/nixos-rk3588 gnull/nixos-rk3588] (a maintained fork of the original by [[User:ryan4yin|ryan4yin]]) is a flake that builds a working SD card image using vendor-supplied kernel and firmware. The kernel used here is older than the upstream Nixpkgs version, and may differ in some driver versions (the complete list of differences is not documented as of now). For example, vendor kernel uses RKNPU driver for NPU, while upstream kernel uses [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/accel/rocket?h=v6.18 rocket] driver — they provide different interfaces and are supported by different tools.

=== Using UEFI ===

OPi 5 Plus supports booting NixOS with UEFI (such as [https://github.com/edk2-porting/edk2-rk3588 edk2]) instead of U-Boot. The [https://github.com/gnull/nixos-rk3588 gnull/nixos-rk3588] has an example (with known bugs [https://github.com/gnull/nixos-rk3588/issues/1]).

== Troubleshooting ==

=== What to do when bootloader breaks (SPI)? ===

If you flash uBoot with incorrect bootloader, you may be unable to load anything else until uboot is fixed. Orange Pi 5 Plus supports maskrom mode with `rkdeveloptool`, as documented here: https://forum.armbian.com/topic/26418-maskrom-erase-spi/#comment-175057

== See Also ==

- https://github.com/NixOS/nixpkgs/pull/292667

[[Category:NixOS on ARM]]

@@ Line 28: / Line 28: @@
 == System configuration ==
-None of the basic components (Kernel, HW acceleration drivers) are available from upstream NixOS.
+Upstream nixpkgs provide kernel and u-boot for Orange Pi 5 Plus. The generic steps from [https://nixos.wiki/wiki/NixOS_on_ARM] apply to this board as well. Make sure the kernel you use is recent enough to support Pi 5 Plus though (6.15 and above are ok). Alternatively, you may use vendor-supplied components, flakes for which are provided by volunteers.
-Join `#nixos-on-arm:nixos.org` Matrix channel to hang out with users that are running this board. As of writing, here is an upstream PR for rk3588 boards: https://github.com/NixOS/nixpkgs/pull/292667
+Join <code>#nixos-on-arm:nixos.org</code> Matrix channel to hang out with users that are running this board.
-As of writing, building a working system requires additional configuration.
+=== Using upstream Components with U-Boot ===
-=== @ryan4yin's flake ===
+. If you have installed U-Boot into on-board SPI flash, you should be able to directly boot generic aarch64 NixOS images.
-A minimal flake that makes NixOS running on Orange Pi 5: https://github.com/ryan4yin/nixos-rk3588
+. If you want to have U-Boot on your SD card, you need to dd it into aarch64 NixOS image at the right offsets. Find the <code>idbloader.img</code> and <code>u-boot.itb</code> binaries in [https://search.nixos.org/packages?channel=25.11&show=ubootOrangePi5Plus ubootOrangePi5Plus] package and dd them into SD card image as shown below.
+<pre>
+dd if=idbloader.img of=sd-card.img seek=64 conv=fsync,notrunc
+dd if=u-boot.itb of=sd-card.img seek=16384 conv=fsync,notrunc
+</pre>
+See the [https://github.com/gnull/nixos-rk3588/tree/main/examples/upstream-opi example from gnull/nixos-rk3588] for a minimal complete configuration to build an SD card image with U-Boot installed (option 2 above). In addition to choosing an appropriate kernel and <code>dd</code>'ing U-Boot into the image, the example also sets kernel parameters to enable the serial console.
+The [https://github.com/Mic92/nixos-aarch64-images Mic92/nixos-aarch64-images] is another approach for installing U-Boot into aarch64 images (although with no direct support for OPi 5 Plus yet).
+=== Using Vendor-supplied Components with U-Boot ===
+[https://github.com/gnull/nixos-rk3588 gnull/nixos-rk3588] (a maintained fork of the original by [[User:ryan4yin|ryan4yin]]) is a flake that builds a working SD card image using vendor-supplied kernel and firmware. The kernel used here is older than the upstream Nixpkgs version, and may differ in some driver versions (the complete list of differences is not documented as of now). For example, vendor kernel uses RKNPU driver for NPU, while upstream kernel uses [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/accel/rocket?h=v6.18 rocket] driver — they provide different interfaces and are supported by different tools.
+=== Using UEFI ===
+OPi 5 Plus supports booting NixOS with UEFI (such as [https://github.com/edk2-porting/edk2-rk3588 edk2]) instead of U-Boot. The [https://github.com/gnull/nixos-rk3588 gnull/nixos-rk3588] has an example (with known bugs [https://github.com/gnull/nixos-rk3588/issues/1]).
+== Troubleshooting ==
 === What to do when bootloader breaks (SPI)? ===
 If you flash uBoot with incorrect bootloader, you may be unable to load anything else until uboot is fixed. Orange Pi 5 Plus supports maskrom mode with `rkdeveloptool`, as documented here: https://forum.armbian.com/topic/26418-maskrom-erase-spi/#comment-175057
+== See Also ==
+- https://github.com/NixOS/nixpkgs/pull/292667
 [[Category:NixOS on ARM]]