Merge pull request #13 from lool/rb1-instructions

Add alpha instructions to craft a RB1 image

Author: lool

README.md

@@ -105,6 +105,152 @@ To enter EDL mode:
 
 NB: It's also possible to run qdl from the host while the baord is not connected, and starting the board directly in EDL mode.
 
+### RB1 instructions (alpha)
+
+The RB1 board boots from eMMC by default and uses an Android style boot architecture. Read-on to flash a disk image to the eMMC storage of the RB1 board and emulate an UEFI boot architecture.
+
+#### Build disk-sdcard.img with debos
+As above, build a SD card image as it's using a 512 sector size, like eMMC on the RB1:
+    ```bash
+    debos \
+        --fakemachine-backend qemu \
+        --memory 1GiB \
+        --scratchsize 4GiB \
+        -t xfcedesktop:true \
+        debos-recipes/qualcomm-linux-debian-rootfs.yaml
+    debos \
+        --fakemachine-backend qemu \
+        --memory 1GiB \
+        --scratchsize 4GiB \
+        -t dtb:qcom/qrb2210-rb1.dtb \
+        -t imagetype:sdcard \
+        debos-recipes/qualcomm-linux-debian-image.yaml
+    ```
+
+#### Build U-Boot with RB1 support
+
+U-Boot will be chainloaded from the first Android boot partition.
+
+1. install build-dependencies to build U-Boot and to generate Android boot images
+    ```bash
+    sudo apt install git build-essential crossbuild-essential-arm64 flex bison libssl-dev gnutls-dev mkbootimg
+    ```
+
+1. get the qcom-mainline branch from Sumit Garg's U-Boot repository ([upstream submission](https://patchwork.ozlabs.org/project/uboot/list/?series=451544))
+    ```bash
+    git clone -b qcom-mainline https://github.com/b49020/u-boot/
+    ```
+
+1. build U-Boot and pack it into an Android boot image with the RB1 DTB
+    ```bash
+    make qcom_defconfig
+    make -j`nproc` DEVICE_TREE=qcom/qrb2210-rb1
+    gzip u-boot-nodtb.bin
+    cat u-boot-nodtb.bin.gz dts/upstream/src/arm64/qcom/qrb2210-rb1.dtb >u-boot-nodtb.bin.gz-dtb
+    mkbootimg --base 0x80000000 --pagesize 4096 --kernel u-boot-nodtb.bin.gz-dtb  --cmdline "root=/dev/notreal" --ramdisk u-boot.bin --output rb1-boot.img
+    ```
+
+#### Build an upstream Linux kernel to workaround boot issues
+
+Linux 6.14 or later will just work, but 6.13 kernels need `CONFIG_CLK_QCM2290_GPUCC=m` ([upstream submission](https://lore.kernel.org/linux-arm-msm/[email protected]/))
+
+1. install build-dependencies, get latest kernel (or a stable one)
+    ```bash
+    sudo apt install git flex bison bc libelf-dev libssl-dev
+    git clone --depth=1  https://github.com/torvalds/linux
+    make defconfig
+    make deb-pkg -j$(nproc)
+    ```
+
+1. on an arm64 capable machine, chroot into the disk image's root filesystem, mount the ESP and install the kernel
+    ```bash
+    # this mounts the image and starts a shell in the chroot
+    host% sudo scripts/disk-image-edit.sh disk-sdcard.img 512
+    chroot#
+
+    # in another shell on the host, copy the kernel .deb to /mnt/root
+    host% chroot sudo cp linux-image-6.13.0_6.13.0-1_arm64.deb /mnt/root/
+
+    # from within the chroot, mount ESP and install the kernel
+    chroot# mount /boot/efi
+    chroot# dpkg -i /root/linux-image-6.13.0_6.13.0-1_arm64.deb
+    # uncompress the kernel as systemd-boot doesn’t handle these
+    chroot# zcat /boot/efi/*/6.13*/linux >/tmp/linux
+    chroot# mv /tmp/linux /boot/efi/*/6.13*/linux
+    # update systemd entry to point at uncompressed kernel
+    vi /boot/efi/…
+    chroot# umount /boot/efi
+
+    # leave chroot and unmount image
+    chroot# exit
+    ```
+
+#### Extract the root and ESP partitions from the disk image
+
+This will create disk-sdcard.img1 and disk-sdcard.img2:
+```bash
+fdisk -l disk-sdcard.img | sed -n '1,/^Device/ d; p' |
+    while read name start end sectors rest; do
+        dd if=disk-sdcard.img of="${name}" bs=512 skip="${start}" count="${sectors}"
+    done
+```
+
+#### Prepare a flashable image
+
+1. download and unpack the [Linux eMMC RB1 recovery image version 23.12 from Linaro](https://releases.linaro.org/96boards/rb1/linaro/rescue/23.12/)
+
+1. edit rawprogram0.xml and change the filename for the following partitions to these values to match files generated earlier:
+
+|label|filename|
+|---|---|
+|`boot_a`|`u-boot-abootimg.img`|
+|`esp`|`disk-sdcard.img1`|
+|`rootfs`|`disk-sdcard.img2`|
+
+#### Flash the image
+
+You probably want to connect to the serial port during the whole process, to follow what’s happening on the target. Plug the type-B USB cable to your host and access the serial console with 115200 8N1, e.g. with screen:
+
+Linux (tweak the name of the device):
+```bash
+screen /dev/ttyUSB* 115200
+```
+macOS (tweak the name of the device):
+```bash
+screen /dev/cu.usbserial-* 115200
+```
+
+Make sure that the 6th switch on the `DIP_SW_1` bank next to the eMMC is `ON` as to use the USB type-C port for flashing.
+
+Put the board in "emergency download" mode (EDL) by removing any cable from the USB type-C port, and pressing the `F_DL` button while turning the power on.
+
+Connect a cable from the flashing host to the USB type-C port on the board.
+
+Unpack the pre-built tarball and run:
+```bash
+qdl --storage emmc prog_firehose_ddr.elf rawprogram*.xml patch*.xml
+```
+
+You should see:
+```
+Waiting for EDL device
+waiting for programmer...
+flashed "xbl_a" successfully
+[...]
+partition 0 is now bootable
+```
+
+And the board should boot to a LightDM greeter on HDMI. Login to the serial console or Xfce session with user / password debian / debian.
+
+The USB ports and Ethernet should work after flipping the 6th switch on the `DIP_SW_1` bank next to the eMMC to `OFF`.
+
+#### Installing “qbootctl” to reset the reboot counter on boot
+
+In the installed Debian system, install “qbootctl” to make the current Android boot image as a successful:
+```bash
+sudo apt install qbootctl
+```
+
 ## Development
 
 Want to join in the development? Changes welcome! See [CONTRIBUTING.md file](CONTRIBUTING.md) for step by step instructions.

scripts/disk-image-edit.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+# SPDX-License-Identifier: BSD-3-Clause
+
+# Input disk image and sector size
+DISK_IMG="$1"
+SECTOR_SIZE="$2"
+
+# Setup loop device with specified sector size
+LOOP_DEV=$(losetup -f --show -P --sector-size "$SECTOR_SIZE" "$DISK_IMG")
+
+# Mount the second partition
+mkdir -p /mnt
+mount "${LOOP_DEV}p2" /mnt
+
+# Bind mount necessary directories
+mount --bind /dev /mnt/dev
+mount --bind /dev/pts /mnt/dev/pts
+mount --bind /proc /mnt/proc
+mount --bind /sys /mnt/sys
+
+# Dangerous
+#mount --bind /tmp /mnt/tmp
+
+# DNS from host
+touch /mnt/etc/resolv.conf
+mount --bind /etc/resolv.conf /mnt/etc/resolv.conf
+
+# Chroot into /mnt and run a shell
+chroot /mnt /bin/bash
+
+# Cleanup after exiting the chroot shell
+umount /mnt/etc/resolv.conf
+#umount /mnt/tmp
+umount /mnt/dev/pts
+umount /mnt/dev
+umount /mnt/proc
+umount /mnt/sys
+umount /mnt
+
+# Detach the loop device
+losetup -d "$LOOP_DEV"
+
+echo "Cleanup completed."