User:Talpa/Using rkdeveloptool

Using rkdeveloptool

rkdeveloptool is a command line tool that can communicate with a some Rockchip SOCs like the RK3566 in the PineNote when they are in Maskrom/Rockusb mode.

rkdeveloptool can among other things read and write to the eMMC inside the PineNote.

It is therefor useful for backups and installing an OS to the PineNote.

About the boot process of the PineNote

When the RK3566 is powered on it checks the attached storage devices in the boot order:

• SPI NOR flash
• SPI NAND flash
• eMMC
• SD-Card

In the case of the PineNote there is only the eMMC.

If the SOC finds a storage device with a valid ID BLOCK it proceeds to boot from the device.

If no usable storage device is found the ROM in the SOC enters Maskrom mode and awaits a connection over USB

The PineNote additionally has a magnet sensor that is read by U-Boot during startup and if it detects a magnet U-Boot places the device in USB download mode

Compiling rkdeveloptool

Pine64 develops a forked version of the rkdeveloptool by RockChip, the following describes how to build the fork:

You will need to have libusb 1.0, its development headers and scdoc installed.

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

This sets up all the build files. You can then compile with make inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

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

Copying the udev rules is also performed automatically when you make install.

Entering Maskrom/Rockusb Mode

There are three ways to get into Maskrom/Rockusb mode:

The first two will result in Rockusb mode where drivers for the eMMC are loaded and rkdeveloptool can be used without further action. This mode can be identified by Loader in the output when running rkdeveloptool list

 rkdeveloptool list
 DevNo=1	Vid=0x2207,Pid=0x350a,LocationID=402	Loader

The last method is used to recover from a bad u-boot and leaves the device in Maskrom. Here rkdevelop must first be used to upload the loader code with the driver for the eMMC. This mode can be identified by Maskrom in the output when running rkdeveloptool list

 rkdeveloptool list-devices
 DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e    Maskrom

The magnet way

1. Remove the USB-C cable if connected
2. Turn the PineNote off (press the power button for 5 seconds), and flip it around so that the display faces down
3. Place a magnet in the correct place on the back of the PineNote, use one of the following methods:
   • Place a magnet on the small circle printed on the back, the pens magnetic cap can be used for this.
   • Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
4. Connect the PineNote to the PC using a USB-C cable, this will wake it up and boot. Wait for it to show up in lsusb.

It should now be in Loader mode, according to rkdeveloptool list-devices (note that Loader here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays Maskrom (not Loader) from the RK3566).

In case it doesn't work the first time just try again.

The U-Boot way

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.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between U-Boot and Rockusb, for example when trying to develop on U-Boot.

Shorting test points

Warning: This has the potential to damage you PineNote

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).

Ensure the device is off by pressing and holding the power button for 5 seconds.

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

Perform the short using one of:

* A small tweezers
* The programming pogo pins for a PineTime (mask the two unused pins with tape), the spring loaded nature of pogo pins helps getting a good contact

When shorting the test pads take great care to not short / touch other components or scratch the PCB as this may damage your PineNote.

While keeping the test pads shorted plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing rkdeveloptool list-devices.

Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e    Maskrom

Sending the loader to the RK3566 (Not needed in "Loader"/rockusb mode)

In Maskrom you must first send a SPL (Secondary program loader) with contains the drivers for accessing the eMMC.

The spl_loader .bin file can be obtained by compiling the downstream u-boot, the version number may or may not match the one displayed below depending on the sources used.

The spl .bin file is send and executed using the rkdeveloptool boot command, see below:

rkdeveloptool boot 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