7. Deploy a disk image

This chapter describes how to write a disk image as generated in one of the previous chapters using Yocto or Debian to the module.

Note

The variable SDCARD_IMG must be already set as described in respective chapter.

Warning

Avoid having the disk image on both the SD Card and the internal eMMC of the module.

As the Linux kernel on the module uses PARTLABEL and PARTUUID to identify partitions to mount, it will be unpredictable whether the SD Card or the internal eMMC is used.

7.1. Deploy on SD Card

Insert an SD card into the host PC and check dmesg -w to find out the device name that was used.

To flash the image on an SD card, bmaptool can be used, it is both faster and safer than a traditional dd. For that, the .bmap companion file, automatically built by the Yocto Project or build.sh debos-recipes wrapper script, should be in the same directory as the SDCARD_IMG artifact.

Then run the following command, with /dev/sdX replaced by the block device representing the user’s SD card:

sudo bmaptool copy "$SDCARD_IMG" /dev/sdX

7.2. Deploy on internal eMMC

7.2.1. Compile rkdeveloptool

To write the image directly onto the on-board eMMC, the flashing tool rkdeveloptool is used, and it must be compiled on the host PC:

# Install compile dependencies
sudo apt-get -y install git libudev-dev libusb-1.0-0-dev dh-autoreconf pkg-config \
	build-essential

# Download rkdeveloptool source code
git clone https://github.com/rockchip-linux/rkdeveloptool.git
cd rkdeveloptool || return

# Compile rkdeveloptool
autoreconf -i
CPPFLAGS=-Wno-format-truncation ./configure
make

# Download miniloaders used for flashing
git clone https://github.com/rockchip-linux/rkbin.git tools/rk_tools

# Build miniloader binaries
(
cd tools/rk_tools/ || return
# Tag linux-5.10-gen-rkr4.1
git checkout "1356c978"
./tools/boot_merger RKBOOT/RK3588MINIALL.ini
)

# Make the resulting files available to later steps
export RKDEVELOPTOOL_DIR="$PWD"

This step should take about 1 minute total.

7.2.2. Enter USB flashing mode

Connect a USB-C cable between the USB P11 Download port (see Fig. 2.4 Buttons and Download USB Type-C port) and a USB port of your host PC.

Make sure there is no SD card inserted into the board.

Press and hold the BIOS button (see Fig. 2.4 Buttons and Download USB Type-C port).

Push and release the RST button, and release the BIOS button about 1 second later.

The lsusb command on your host PC should return the following:

$ lsusb -d 2207:350b
Bus xxx Device 0xx: ID 2207:350b Fuzhou Rockchip Electronics Company

7.2.3. Flash the eMMC

To write the image file path stored in the variable SDCARD_IMG to the on-board eMMC, run:

cd "$RKDEVELOPTOOL_DIR" || return
sudo ./rkdeveloptool db tools/rk_tools/rk3588_spl_loader_v* && sleep 1
sudo ./rkdeveloptool wl 0 "$SDCARD_IMG"
sudo ./rkdeveloptool rd

This step should take about 1 minute for the Debian image.

7.3. Deploy U-Boot Separately

Im some circumstances, it may be useful to only deploy the U-Boot bootloader, also resetting any changes to the U-Boot environment, while leaving the rest of the system as-is.

7.3.1. Using dd

You can write U-Boot to the eMMC from a running Jaguar using:

dd "if=$JAGUAR_UBOOT_DIR/u-boot-rockchip.bin" of=/dev/mmcblk0 seek=64

Similarly, you can write U-Boot to an SD Card connected to your host PC with /dev/sdX replaced by the block device representing the user’s SD card:

dd "if=$JAGUAR_UBOOT_DIR/u-boot-rockchip.bin" of=/dev/sdX seek=64

7.3.2. Using rkdeveloptool

After entering USB flashing mode (Section 7.2.2 Enter USB flashing mode) you can deploy U-Boot to the eMMC using the following commands on your host PC:

cd "$RKDEVELOPTOOL_DIR" || return
sudo ./rkdeveloptool db tools/rk_tools/rk3588_spl_loader_v* && sleep 1
sudo ./rkdeveloptool wl 64 "$JAGUAR_UBOOT_DIR/u-boot-rockchip.bin"
sudo ./rkdeveloptool rd