User:Fxc/Draft:PineTab2 SPI
This article explains what the SPI flash memory in the PineTab2 is and how it is used and recovered.
Section will be deleted: Warning template
Getting started
The PineTab2 includes an SPI flash memory. An SPI flash memory is a non-volatile memory that uses Serial Peripheral Interface (SPI) protocol for communication. The memory can be used to store a bootloader on it. This is an important hardware functionality, because it can be used to modify the boot order (see the section #Boot order) and to store the bootloader away and independent from any operating system (on the SPI flash memory as dedicated memory, instead on the same disk like the operating system).
The SPI on the current PineTab2 batch is empty and will probably contain a bootloader in future batches to simplify the booting procedure for new users.
Boot order
The RK3566 SoC searches for the U-Boot SPL in a fixed order:
- SPI flash memory
- eMMC
- MicroSD card
The subsequent boot order in the U-Boot SPL can then be changed in software. Example: There is the U-Boot bootloader installed on the eMMC (the internal memory of the PineTab2), which tries to boot from a microSD card if it finds a bootable medium and it will otherwise load the installation from the eMMC. Another example: There is the U-Boot bootloader installed to the eMMC, which tries to first boot from microSD card and then from the eMMC.
In practice, this has several implications for the user that need to be considered:
- The bootloader might break and prevent the device from booting
- If the bootloader on the eMMC or SPI breaks and stops, you must disable the SPI and the eMMC to make the device boot from a microSD card to recover your installation (see section #Recovery)
- Bypassing the eMMC and SPI requires an UART adapter with a bypass switch (it is included in the currently shipped batch at the time of June 2023)
- Future batches might ship with a different bootloader and/or different settings on the SPI than what you're currently using and/or plan to use
- Incompatibilities can be introduced by flashing the SPI
Releases
The following bootloader releases are currently available for the SPI flash memory:
- Kwiboo's U-Boot artifacts build for the PineTab2 (testing release for development purposes, not intended for productive usage)
Flashing
A word of warning: Flashing the SPI is not recommended by the author(s) of the article. Instead it is recommended to do any development and testing solely using microSD cards and to keep the SPI in the condition at delivery. The flashing procedure has the risk of locking you out from your device because the SPI has the highest boot priority. If the bootloader on the SPI stops booting it will prevent the device from booting any further. In this state it can be only recovered by using the UART adapter with the bypass switch as explained in the section #Recovery. Additionally, bootloaders such as U-Boot flashed on the SPI will introduce incompatibilities in some operating systems, for example if they are based on AOSP.
Checklist of things you require for flashing the SPI on the PineTab2
- A fully charged PineTab2 connected to a charger
- A confirmed to work UART adapter with a bypass switch, in case anything goes wrong
- A fully working and stable operating system
- Experience with the command line
- A full understanding of the involved procedure and the risks
Steps to flash the SPI:
- Read and understand the explanation about the boot order, the procedure to recover a faulty flash and the involved risks
- Test that your UART adapter with a bypass switch is fully working and the bypass switch successfully bypasses the SPI and the eMMC
- Power on your device without the UART adapter
- Install
flashcpif it is not installed already - Download a listed release. Verify multiple times that the correct file is downloaded and that it is compatible with your device. Other devices might have a similar name or the filename might be similar to incompatible files.
- Verify that the download was complete and successful using the provided checksum of the corresponding release
- Flash the SPI using one of the methods:
- NOTE: These commands do not verify if the SPI was flashed successful. The step is done AT OWN RISK!
- Using the U-Boot command line: for Kwiboo's U-Boot release the instruction for the U-Boot command line can be found under https://github.com/Kwiboo/u-boot-build#spi-flash
- Using flashcp: run the command
flashcp -v -p u-boot-rockchip-spi.bin /dev/mtd0, with u-boot-rockchip-spi.bin being an example for a U-Boot release. It has to be stored in the directory you're running the command in. If the path in the devfs is not found, the SPI bypass switch on the UART adapter is either enabled or the SPI is protected from being overwritten in the operating system.
- Wait for the command to successfully flash your SPI
If there is any question regarding a step or if one step is not clear enough please ask in the PineTab channel on the bridged community chat before doing the step. If the procedure was not successful please read the #Recovery section.
Recovery
To bypass the SPI and to force the device to boot from the microSD card, the SPI (and eMMC) can be disabled by using the debug UART adapter shipped with the device in the box also containing the charging cable. Set the SD BOOT MASKROM switch on the adapter to the position ON and plug it into the USB/PD charging port.
Then power on the tablet with a flashed microSD card (which includes a bootloader) and unplug the debug board or set the switch to the position OFF again when the factory image is started, otherwise the factory image won't find the SPI.
Then reflash a working bootloader or remove the SPI contents:
- To reflash the SPI with a working bootloader: See section #Flashing
- To remove the SPI contents: If the path /dev/mtd0 is available in the devfs, overwrite the SPI contents with zeroes. If the path is not available, check if the bypass switch on the UART adapter was still set to ON after booting the microSD card. If it was not set to ON then you need to overwrite the SPI from the U-Boot command line.