PineNote Development/Flashing

This page or section is under construction

Please help to review and edit this page or section. Information are subject to change.

Note: These instructions are directed towards experienced developers only!

This page contains information on flashing software to the PineNote.

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

Getting rkdeveloptool

Most flashing operations on the PineNote are done through rkdeveloptool, a command line utility built on libusb. PINE64 maintains its own fork here that you will need to get. The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) rkdeveloptool will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:

sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload

Entering Maskrom/Rockusb Mode

Interfacing with the PineNote over USB using rkdeveloptool requires first booting the PineNote into an alternative operating mode called Maskrom or Rockusb mode.

Possible Methods

There are three possible methods of entering Maskrom/Rockusb mode:

Hardware Magnet Switch

1. Connect the PineNote to your computer via USB and boot the PineNote into Android
2. Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
3. Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

U-Boot

This method requires a UART dongle for the PineNote with passthrough allowing simultaneous UART & USB connections. It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

1. Interrupt the U-Boot startup using ctrl-c (while attached using an UART dongle)
2. While in U-Boot use the command rockusb 0 mmc 0 to start Rockusb mode.

Shorting Test Points

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0) with a small tweezers, this is how it looks on board view (credit to Caleb):

Success

No matter what approach you take, you can tell whether you succeeded by running the lsusb command on your computer:

• If you find the entry 2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink in the list, the process did not succeed; reboot and retry
• If you find the entry 2207:350a Fuzhou Rockchip Electronics Company USB download gadget then the process succeeded

You can also look at the output of the rkdeveloptool list command:

• If this prints out No devices in rockusb mode found the process did not succeed; reboot and retry
• If this prints out something like DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader then the process succeeded

Exiting mode

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the rkdeveloptool reset command.

Backup

A backup of the content of the internal eMMC before anything gets messed is mandatory.

Especially the waveform partition contains data unique to your PineNote and is a prime candidate for backup.

But other partitions like U-Boot (need for any operation of the device) or the un-partitioned space at the beginning containing the GPT partition table (and presumably the VCOM setting for the e-ink display and maybe device mac addresses) contains data you may wish to backup.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large userdata partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

Manual backup using rkdeveloptool

Dorian has some nice notes regarding the PineNote

Don't forget to install a patched U-Boot for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

List partitions:

> rkdeveloptool list-partitions                      
#   LBA start (sectors)  LBA end (sectors)  Size (bytes)       Name                
00                16384              24575       4194304       uboot
01                24576              32767       4194304       trust
02                32768              36863       2097152       waveform
03                36864              45055       4194304       misc
04                45056              53247       4194304       dtbo
05                53248              55295       1048576       vbmeta
06                55296             137215      41943040       boot
07               137216             145407       4194304       security
08               145408             407551     134217728       recovery
09               407552            1193983     402653184       backup
10              1193984            3291135    1073741824       cache
11              3291136            3323903      16777216       metadata
12              3323904            9697279    3263168512       super
13              9697280            9730047      16777216       logo
14              9730048            9861119      67108864       device
15              9861120          241827775  118766927872       userdata

Warning: this process is very new! Proceed at your own risk.

See instructions on this artifact. It will instruct you on extracting the rootfs into an empty ext4 partition. This can be done from Linux or Android. Further instructions on building your own rootfs can be found here.

Automated backup using a script and rkdeveloptool

pinenote-backup is a python script for detecting the partitions and automating the backup of partitions or the whole disk.

It also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

Using the factory Android installation

TODO

Using a user installed Linux

A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using dd.

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup after they started playing with the content of the eMMC.

Side-by-side setup

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

Without Repartitioning

The recommended partition for this is mmcblk0p11 aka /cache. It is large and already formatted as ext4, so it is readable from U-Boot. Here are some general steps:

1. From the UART or adb shell, set up your chroot in /cache. I used the Alpine Linux rootfs tarball.
2. Copy in your kernel and DTB, using for example scp or wget inside the chroot.
3. Finally, create and boot an extlinux.conf as described below.

With Repartitioning

It is possible to shrink the userdata partition, and create a new partition at the end for use with mainline Linux. This provides much more space than cache. However, because userdata is formatted with f2fs, and that filesystem cannot be shrunk, resizing the partition requires wiping userdata.

1. Back up any necessary files from userdata
2. Boot to a mainline kernel from mmcblk0p11, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
3. Modify the partition table with your favorite tool, e.g. fdisk, gdisk, or parted
4. Reboot into fastboot and wipe userdata.
5. Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

Using rkdeveloptool

Building Downstream U-Boot

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh

In the current version (current as of 2022-01-02), there might have to be made a change to one line to get a clean compilation:

diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
   bool image_preloaded = false;
   uint8_t* digest;
   size_t digest_len;
-  const char* found;
+  const char* found = NULL;
   uint64_t image_size;
   size_t expected_digest_len = 0;
   uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:

diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
        fi
 
        if [ "${ARM64_TRUSTZONE}" == "y" ]; then
-               if ! python -c "import elftools" ; then
+               if ! python3 -c "import elftools" ; then
                        echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
                        exit 1
                fi

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin

This should output "Downloading bootloader succeeded".

We can now verify that this worked using e.g. the "read flash info" command:

./rkdeveloptool read-flash-info

TODO: Section needs to be finished

Creating a mainline boot image

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

1. Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
2. Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
3. Build your mainline kernel
4. Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
5. Create a file in the root of the mounted image called extlinux.conf as described below
6. Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

Using fastboot

Follow the steps for Creating a mainline boot image, but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

• Use "reboot bootloader" from adb or a UART console or
• get a U-Boot prompt and run fastboot usb 0.