Merge pull request #57 from pine64/multi_image

Improved readability of the instructions

content/documentation/PinePhone_Pro/Software/Boot_order.adoc

@@ -6,7 +6,7 @@ menu:
     title:
     parent: "PinePhone_Pro/Software"
     identifier: "PinePhone_Pro/Software/Boot_order"
-    weight: 
+    weight: 1
 ---
 
 The RK3399S processor in the PinePhone Pro searches for the bootloader (such as _U-Boot_ or _Tow-Boot_) in the following order:

content/documentation/PinePhone_Pro/Software/Bootloaders.adoc

@@ -6,7 +6,7 @@ menu:
     title:
     parent: "PinePhone_Pro/Software"
     identifier: "PinePhone_Pro/Software/Bootloaders"
-    weight: 
+    weight: 4
 ---
 
 The following section contains notes regarding compatible bootloaders with the PinePhone Pro.

content/documentation/PinePhone_Pro/Software/Multi-distribution_image.adoc

@@ -0,0 +1,262 @@
+---
+title: "Multi-distribution image"
+draft: false
+menu:
+  docs:
+    title:
+    parent: "PinePhone_Pro/Software"
+    identifier: "PinePhone_Pro/Software/Multi-distribution_image"
+    weight: 99
+---
+
+:toc:
+
+This article explains how to install a multiple linux distribution enviroment on your PinePhone Pro that is bootable both from the eMMC internal memory or a microSD card.
+
+== Installing rk2aw
+
+Make sure your phone has the link:/documentation/PinePhone_Pro/Software/Bootloaders/#rk2aw[rk2aw pre-loader] installed to SPI flash. PinePhone Pro models ordered after November 2023 are shipped with rk2aw pre-installed. Otherwise, follow the instructions in this section to install it.
+
+TIP: The multi-boot image _can_ function without rk2aw, but you may need to hold down the **RE** button during boot to force the phone to boot from microSD card by disabling the SPI flash memory and the eMMC.
+
+Make sure the phone’s SSH server is up and running on the PinePhone Pro's stock operating system. Then Connect to your phone from your Linux computer using SSH:
+
+----
+ssh USER@PHONEIP
+mkdir -p ~/rk2aw
+cd ~/rk2aw
+curl -O https://xff.cz/kernels/bootloaders-2024.04/ppp.tar.gz
+tar -xvzf ppp.tar.gz -C ~/rk2aw
+cd ~/rk2aw/ppp
+sudo ./spinor-flash-initial-setup.sh
+----
+
+Further instructions can be found on the link:https://xff.cz/kernels/bootloaders-2024.04/ppp/rk2aw/INSTALL[author's website].
+
+== Setting variables
+
+During processes of partitioning target device or building the image, everytime you open a new terminal window, make sure needed `$VARIABLES` are properly defined:
+
+`DISTROURL is the image downloading URL address of Linux distribution, in example **DISTROURL=https://github.com/dreemurrs-embedded/Pine64-Arch/releases/download/20230925/archlinux-pinephone-pro-phosh-20230925.img.xz**`
+`DEVICE is the name of the device displayed in the **lsblk** command, in example **DEVICE=sdb**`
+`PARTSIZE is the capacity of each partition, in example **PARTSIZE=16G**`
+`PARTNAME is the name of partition/distribution, in example **PARTNAME=ARCH**`
+`PARTNUMBER is the number of partition/distribution, in example **PARTNUMBER=2**`
+
+This guide has been tested with following images:
+
+* https://github.com/dreemurrs-embedded/Pine64-Arch/releases/download/20230925/archlinux-pinephone-pro-phosh-20230925.img.xz
+* https://github.com/manjaro-pinephone/phosh/releases/download/beta37/Manjaro-ARM-phosh-pinephonepro-beta37.img.xz
+* https://images.mobian.org/pinephonepro/weekly/mobian-pinephonepro-phosh-20240121.img.xz
+* https://images.postmarketos.org/bpo/v23.12/pine64-pinephonepro/phosh/20240221-0448/20240221-0448-postmarketOS-v23.12-phosh-22.3-pine64-pinephonepro.img.xz
+
+== Building
+
+Connect your PinePhone Pro to a Linux computer and press power button on. From the graphical menu select `eMMC over USB` or `SD over USB` to expose the device to your computer. Make sure there are no signatures or partitions left with the command `sudo wipefs /dev/$DEVICE`. To erase all signatures, type `sudo wipefs --all --force /dev/$DEVICE`.
+
+Overwrite the device with zeroes by either overwriting the first sectors with zeroes (command 1) or the whole device (command 2): 
+
+. `sudo dd if=/dev/zero of=/dev/$DEVICE status=progress bs=32768 count=1`
+. `sudo dd if=/dev/zero of=/dev/$DEVICE status=progress bs=32768 count=$(expr $(lsblk -bno SIZE /dev/$DEVICE | head -1) \/ 32768)`
+
+=== Partitioning
+
+Partition the device for the multiple distributions:
+
+----
+sudo sfdisk /dev/$DEVICE --wipe always <<EOF
+ label: gpt
+ first-lba: 64
+ table-length: 8
+ attrs=RequiredPartition, type=D7B1F817-AA75-2F4F-830D-84818A145370, start=64, size=32704, name="uboot_raw"
+ attrs="RequiredPartition,LegacyBIOSBootable", size=$PARTSIZE, name="ARCH"
+ attrs="RequiredPartition,LegacyBIOSBootable", size=$PARTSIZE, name="MANJARO"
+ attrs="RequiredPartition,LegacyBIOSBootable", size=$PARTSIZE, name="MOBIAN"
+ attrs="RequiredPartition,LegacyBIOSBootable", size=$PARTSIZE, name="PMOS"
+ attrs="RequiredPartition,LegacyBIOSBootable", size=+, name="extra"
+EOF
+----
+
+Expected results:
+
+----
+Checking that no-one is using this disk right now ... OK
+Disk /dev/sd[...]: 118.16 GiB, 126877696000 bytes, 247808000 sectors
+Disk model: microSD card Reader  
+Units: sectors of 1 * 512 = 512 bytes
+Sector size (logical/physical): 512 bytes / 512 bytes
+I/O size (minimum/optimal): 512 bytes / 512 bytes
+>>> Script header accepted.
+New situation:
+Disklabel type: gpt
+Disk identifier: A012E9D0-B4EB-4677-926F-D93AE4C696FA
+ Device    Start       End  Sectors   Size Type
+ sdb1         64     32767    32704   16M  unknown
+ sdb2      32768  33587199 33554432   16G  Linux fs
+ sdb3   33587200  67141631 33554432   16G  Linux fs
+ sdb4   67141632 100696063 33554432   16G  Linux fs
+ sdb5  100696064 134250495 33554432   16G  Linux fs
+ sdb7  167804928 247805951 80001024 38.1G  Linux fs
+The partition table has been altered.
+Calling ioctl() to re-read partition table.
+Syncing disks.
+----
+
+=== Install U-Boot
+
+Download the following U-Boot build (the source code of the build can be on link:https://xff.cz/git/u-boot/tree/?h=ppp-2023.07[xff.cz]):
+
+----
+cd ~/rk2aw
+curl -O https://xff.cz/kernels/bootloaders-2024.04/ppp.tar.gz
+tar -xzf ppp.tar.gz
+----
+
+NOTE: This is the same `ppp.tar.gz` from the <<install_rk2aw>> section; if you already have a copy of it on your computer then you don't have to download it again.
+
+Then write the U-Boot image to the device using the following command:
+
+----
+sudo dd if=ppp/foss/u-boot-rockchip.bin of=/dev/$DEVICE bs=512 seek=64 status=progress conv=fsync
+----
+
+If you are interested in building this U-Boot image yourself, you will need to copy the `ppp/foss/.config` file from the archive above to the root of your U-Boot source directory.
+
+=== Build the partitions
+
+Download, decompress and mount the distribution image on your Linux computer. Copy root filesystem and boot to needed partition. Make sure you use an updated image from link:/documentation/PinePhone_Pro/Software/Releases[relases download link] for each distribution.
+
+----
+mkdir -p ~/ppp/distros
+cd ~/ppp/distros
+wget $DISTROURL
+xz -v -d -k IMAGE.*.xz
+mv IMAGE.img $PARTNAME.img
+----
+
+----
+sudo losetup -P /dev/loop0 $PARTNAME.img
+sudo mkdir -p /mnt/$PARTNAME/boot /mnt/$PARTNAME/root /mnt/$PARTNAME/device
+sudo mount /dev/loop0p1 /mnt/$PARTNAME/boot/
+sudo mount /dev/loop0p2 /mnt/$PARTNAME/root/
+----
+
+----
+sudo dd if=/dev/loop0p2 of=/dev/$DEVICE$PARTNUMBER bs=1M status=progress conv=fsync
+sudo mount /dev/$DEVICE$PARTNUMBER /mnt/$PARTNAME/device/
+sudo scp -r /mnt/$PARTNAME/boot/* /mnt/$PARTNAME/device/boot
+# sudo mv /mnt/$PARTNAME/device/boot/boot.scr /mnt/$PARTNAME/device/boot/boot.scrORIG # rename if present
+----
+
+Replace/create `/boot/extlinux/extlinux.conf` and `/etc/fstab` files:
+
+----
+sudo mkdir -p /mnt/$PARTNAME/device/boot/extlinux
+# sudo mv /mnt/$PARTNAME/device/boot/extlinux/extlinux.conf /mnt/$PARTNAME/device/boot/extlinux/extlinux.confORIG # rename if present
+
+sudo tee /mnt/$PARTNAME/device/boot/extlinux/extlinux.conf <<EOF
+#/boot/extlinux/extlinux.conf
+menu title Pinephone Pro Boot Menu
+label l0
+menu label $PARTNAME
+
+#uncomment next 3 lines for ARCH
+#fdt /boot/dtbs/rockchip/rk3399-pinephone-pro.dtb
+#initrd /boot/initramfs-linux.img
+#kernel /boot/Image.gz
+
+#uncomment next 3 lines for MANJARO
+#fdt /boot/dtbs/rockchip/rk3399-pinephone-pro.dtb
+#initrd /boot/initramfs-linux.img
+#kernel /boot/Image
+
+#uncomment next 3 lines for MOBIAN
+#linux /boot/vmlinuz-6.6-rockchip
+#initrd /boot/initrd.img-6.6-rockchip
+#fdtdir /boot/dtb-6.6-rockchip/
+
+#uncomment next 3 lines for PMOS
+#fdtdir /boot/dtbs-pine64-pinephonepro/
+#linux /boot/vmlinuz
+#initrd /boot/initramfs-extra
+
+append root=PARTLABEL=$PARTNAME console=ttyS2,115200 console=tty0 loglevel=7 rw rootwait
+
+EOF
+----
+
+----
+sudo mv /mnt/$PARTNAME/device/etc/fstab /mnt/$PARTNAME/device/etc/fstabORIG # rename
+
+sudo tee /mnt/$PARTNAME/device/etc/fstab <<EOF
+#<file system>         <dir>      <type> <options>                  <dump> <pass>
+
+#uncomment next line for ARCH
+#PARTLABEL=$PARTNAME   /          ext4   rw,relatime                0      1
+
+#uncomment next line for MANJARO
+#PARTLABEL=MANJARO     /          ext4   defaults                   0      1
+
+#uncomment next line for MOBIAN
+#PARTLABEL=$PARTNAME   /          ext4   defaults,x-systemd.growfs  0      1
+
+#uncomment next line for PMOS
+#PARTLABEL=$PARTNAME   /          ext4   defaults                   0      0
+
+EOF
+----
+
+==== Build PostmarketOS image
+
+You can optionally use link:https://wiki.postmarketos.org/wiki/Pmbootstrap[pmbootstrap] to generate the distribution image on your Linux computer, instead of downloading a pre-made image. Make sure you install pmbootstrap before building the image.
+
+Start creating 2 GB empty image file, format and mount it.
+
+----
+sudo su
+dd if=/dev/zero of=postmarketos.img bs=1 count=0 seek=2G status=progress && sync
+mkfs.ext4 postmarketos.img
+losetup -P /dev/loop0 postmarketos.img
+exit
+----
+
+Build the PostmarketOS image via pmbootstrap:
+
+----
+pmbootstrap init
+pmbootstrap status
+pmbootstrap pull
+pmbootstrap install --sdcard=/dev/[LOOP-DEVICE]
+pmbootstrap shutdown
+----
+
+=== Unmount and detach
+
+To unmount and deatch all building images, run:
+
+----
+sudo umount /mnt/$PARTNAME/*
+sudo rm -r /mnt/$PARTNAME
+sudo losetup -D
+----
+
+== Resizing the partitions
+
+On the first boot, if it doesn't happen automatically, you can manually resize each image to fill the entire partition using GParted GUI software or using the CLI:
+
+----
+sudo e2fsck -f /dev/$DEVICE$PARTNUMBER
+sudo resize2fs /dev/$DEVICE$PARTNUMBER
+----
+
+Repeat the building process for each needed distribution.
+
+== Troubleshooting
+
+To find the exact _LABEL_, _UUID_, _PARTLABEL_ and _PARTUUID_ names, open a terminal window on the phone and use the command `blkid`.
+
+Any time a distribution update rebuilds the initramfs it is necessary to delete `/boot/boot.scr` again to keep the rk2aw menu clean.
+
+In case you want to reinstall only one distribution, the easy way is to delete and recreate the selected partition using the GParted GUI.
+
+If the device doesn't start, connect a compatible link:https://pine64.com/product/pinebook-pinephone-pinetab-serial-console[serial cable] to the headphone jack and a computer, switch off microswitch 6 and start a serial console to investigate further. Find out the corresponding USB device using `ls /dev/ttyUSB*` and then connect to it with for example _minicom_ using the command `minicom -b 1500000 -D /dev/ttyUSB**[...]**`, where *[...]* is the number of the USB device.

content/documentation/PinePhone_Pro/Software/Releases.adoc

@@ -6,7 +6,7 @@ menu:
     title:
     parent: "PinePhone_Pro/Software"
     identifier: "PinePhone_Pro/Software/Releases"
-    weight: 
+    weight: 2
 ---
 
 This page contains a list of all available releases and tools for the link:/documentation/PinePhone_Pro[PinePhone Pro].

content/documentation/PinePhone_Pro/Software/Software_state.adoc

@@ -6,7 +6,7 @@ menu:
     title:
     parent: "PinePhone_Pro/Software"
     identifier: "PinePhone_Pro/Software/Software_state"
-    weight: 
+    weight: 3
 ---
 
 Presently the PinePhone Pro Explorer Edition is aimed at *Linux developers with an extensive knowledge of embedded systems and/or experience with mobile Linux*. It will take time for all the PinePhone Pro’s functionality to reach software parity with the original PinePhone and for mobile operating systems, in more general, to reach a higher degree of maturity.