Difference between revisions of "Pinebook Pro SPI"

From PINE64
Jump to navigation Jump to search
(Adding introduction text)
(Overhaul whole article)
Line 1: Line 1:
The Pinebook Pro comes equipped with two non-volatile storage components, the eMMC and the SPI. The capacity of the SPI is 128MiB and it may be used in the boot process.
The Pinebook Pro comes equipped with two non-volatile storage components, the eMMC and the SPI. The capacity of the SPI is 128MiB and it may be used in the boot process.


= Writing to the Pinebook Pro SPI =
Boot data can be written to the SPI via two methods: either from within PBP or from a second machine connected to the PBP by USB.


'''Necessary Items:'''
= Writing to SPI from within PBP =


1. A screwdriver<br>
[https://forum.pine64.org/member.php?action=profile&uid=15527 Forum user pcm720] showed an example of writing to the SPI from within PBP in [https://github.com/pcm720/u-boot-build-scripts/releases their self-published version of U-Boot] that offers boot functionality for NVMe drives. It involves use of <code>flash_erase</code> command (available in the mtd-utils package on Arch/Manjaro) and the <code>dd</code> command.
2. USB Type-A to USB-C cable<br>
3. Another Computer with a USB-A 3.0 port
*''Not a requirement but if you want to boot from NVMe you need:''
4. A bootable NVMe (i.e., with /boot/boot.txt having root=/dev/whatever_your_nvme_is plus some operating system.


'''Procedure:'''
= Writing to SPI from a second machine =


1. Build and install rkdeveloptool on your other computer, find out all the info to do that on [https://github.com/rockchip-linux/rkdeveloptool their Github.]
Writing to the SPI from a second machine is more complicated than the other method, but it is the only option when troubleshooting an SPI flash gone wrong. This method works by bringing the PBP into <code>maskrom mode</code> and issuing commands on the second machine that download the flash image onto the PBP.


2. Verify correct and successful installation:
Upon entering <code>maskrom mode</code>, the power LED on your PBP won't light up and neither will the display. Instead, your second machine, the one connected to your PBP via USB, will indicate <code>maskrom mode</code> by logging to <code>journalctl</code>.
:<code>rkdeveloptool --version</code> should output: <code>rkdeveloptool ver 1.3</code>
3. On the same computer, make a directory to hold the necessary files.
:<code>mkdir ~/PBPBoot</code>


:You will need to have two files in this directory:
There are two ways to reach <code>maskrom mode</code>, but the first tends to be less reliable.
*The db flash helper([https://droppy.ironrobin.net/%24/JWP47 rk3399_loader_spinor_v1.15.114.bin]). This prepares the SPI for a binary.
*The U-Boot, or other bootloader binary.


'''Note: SPI binaries are built for SPI environment only. It will not work if you try putting it on your eMMC.'''
== Maskrom mode (unreliable method) ==
 
:<code>mv rk3399_loader_spinor_v1.15.114.bin ~/PBPBoot</code>
:<code>mv dhiv_SPI_uboot.bin ~/PBPBoot</code>
:<code>cd ~/PBPBoot</code>
 
4. Put the Pinebook Pro into maskrom mode:
*Remove all bootable devices from your Pinebook Pro.
*Plug the Type-A end into your non-Pinebook Pro device.
*Plug the Type-C end into your Pinebook Pro.
5. Reboot the Pinebook Pro.
:To verify you are in maskrom mode, with your computers connected, run <code>rkdeveloptool ld</code>
:You should get an output like this: '''DevNo=1 Vid=0x2207,Pid=0x330c,LocationID=1401 Maskrom'''
6. Flash the flash helper db file.
:<code>rkdeveloptool db rk3399_loader_spinor_v1.15.114.bin</code>
:Upon success, the output should read '''Downloading bootloader succeeded.'''
7. Flash the new SPI binary.
:<code>rkdeveloptool wl 0 dhiv_SPI_uboot.bin</code>
:Successful output should read: '''Write LBA from file (100%)'''.
8. Test the installation.
:<code>rkdeveloptool td</code>
:Successful output should read '''Reset Device OK'''.
9. Run <code>rkdeveloptool rd</code> to reboot your Pinebook Pro.
 
= Recovering from broken SPI flashes/installs =
 
If you accidentally soft brick your PBP there is special mode implemented called maskrom mode. In this mode the device is accessible as regular USB device and can be accessed using rkdeveloptools, especially to rewrite SPI flash or to erase it.
 
Upon entering maskrom mode, the power LED on your PBP won't light up and neither will the display. Instead, your second machine, the one connected to your PBP via USB, will indicate maskrom mode by logging to journalctl.
 
Below are the two known procedures to enter maskrom mode.
 
=== Simple, but unreliable maskrom mode procedure ===


According to Rockchip documentation, these steps should work; unfortunately, many users have reported them to be unsuccessful. You may need to repeat these steps several times for them to work.
According to Rockchip documentation, these steps should work; unfortunately, many users have reported them to be unsuccessful. You may need to repeat these steps several times for them to work.
Line 69: Line 28:
* The problem occurs only when the SPI was previously flashed.
* The problem occurs only when the SPI was previously flashed.


The button works by shorting two pins in an SPI device. But in some cases it just does nothing. Fortunately, the two pins can shorted by hand, as described in the next procedure.
The button works by shorting two pins in the SPI device. But in some cases it just does nothing. Fortunately, the two pins can shorted by hand, as described in the next method.


=== Demanding, but reliable maskrom mode procedure ===
== Maskrom mode (reliable method) ==


# Compile rkdeveloptools (see [https://github.com/rockchip-linux/rkdeveloptool project repository] for instructions)
# Build and install <code>rkdeveloptool</code> (see [https://github.com/rockchip-linux/rkdeveloptool project repository] for instructions)
# Verify successful installation. Running <code>rkdeveloptool --version</code> should output: <code>rkdeveloptool ver 1.3</code>
# Run <code>journalctl -f</code> and keep it running. Once maskrom mode is reached it will produce additional output.
# Unscrew bottom cover.
# Unscrew bottom cover.
# Remove the metal shield surrounding main CPU - it is held in place by a tape and micro clamps on pcb. The clamps can be released with a pry tool and some force. [https://forum.pine64.org/showthread.php?tid=11073&pid=75096#pid75096 This forum post with photos] shows how it can be done.
# Remove the metal shield surrounding main CPU. The shield is held in place by a tape and micro clamps on the board. The clamps can be released with a pry tool and some force. [https://forum.pine64.org/showthread.php?tid=11073&pid=75096#pid75096 This forum post with photos] shows how it can be done.
# Disconnect all (!!!) boot devices (emmc, sdcard, usb).
# Disconnect all (!!!) boot devices (emmc, sdcard, usb).
# Locate SPI flash (number 29 on picture with Pinebook Pro internals).
# Locate SPI flash (component number 29 on [https://wiki.pine64.org/images/4/45/PBPL_S.jpg this photo of the Pinebook Pro internals]).
# Connect your PBP with USB-C - USB-A cable to another computer (PBP on USB-C side)
# Connect your PBP with USB-C - USB-A cable to second machine (PBP on USB-C side)
# Turn on PBP, short pins CLK and VSS and press reset. It should get your PBP into maskrom mode. (see picture)
# Short pins CLK and VSS (see chip diagram below for names of pins). This can be done with a pair of tweezers when short on tools. [[File:Spi.png]]
# Press the reset button (component number 28)
# Check if there is new output from <code>journalctl</code> program.
# Check if the PBP connected by running <code>rkdeveloptool ld</code>. If successful, the output should be like: <code>DevNo=1 Vid=0x2207,Pid=0x330c,LocationID=1401 Maskrom</code>


[[File:Spi.png]]
== After entering maskrom mode ==


= Zeroing out SPI Flash =
Now that the PBP is in <code>maskrom mode</code>, you can use <code>rkdeveloptool</code> to write data to the SPI. To do so you'll need the binary file you'll be writing to SPI, which will be referred to as <code>SPI_new.bin</code>, and a helper file named [https://droppy.ironrobin.net/%24/JWP47 rk3399_loader_spinor_v1.15.114.bin].


On another computer:
# Flash the flash helper db file: <code>rkdeveloptool db rk3399_loader_spinor_v1.15.114.bin</code>. If successful, the output should read <code>Downloading bootloader succeeded</code>.
# Flash the new SPI binary: <code>rkdeveloptool wl 0 SPI_new.bin</code>. If successful, the output should read: <code>Write LBA from file (100%)</code>.
# Test the installation: <code>rkdeveloptool td</code>. If successful, output should read <code>Reset Device OK</code>.
# Run <code>rkdeveloptool rd</code> to reboot your Pinebook Pro.


1. Create a file filled with zeros<br>
== Zeroing out the SPI ==


<code>dd if=/dev/zero of=zerospi bs=1M count=16</code>
In case, you wrote something bad to your SPI, it's helpful to wipe away that data with zeros. To do that, you follow the same steps above to enter <code>maskrom mode</code> and then write an binary file that consists of all zeros.


2. Write the file to SPI.<br>
# Create the binary file <code>dd if=/dev/zero of=zero.bin bs=1M count=16</code>
<code>rkdeveloptool db rk3399_loader_spinor_v1.15.114.bin</code><br>
# Flash the flash helper db file: <code>rkdeveloptool db rk3399_loader_spinor_v1.15.114.bin</code>. If successful, the output should read <code>Downloading bootloader succeeded</code>.
<code>rkdeveloptool wl 0 zerospi</code><br>
# Flash the new SPI binary: <code>rkdeveloptool wl 0 zero.bin</code>. If successful, the output should read: <code>Write LBA from file (100%)</code>.
<code>rkdeveloptool td</code><br>
# Test the installation: <code>rkdeveloptool td</code>. If successful, output should read <code>Reset Device OK</code>.
<code>rkdeveloptool rd</code>
# Run <code>rkdeveloptool rd</code> to reboot your Pinebook Pro.

Revision as of 04:53, 1 September 2020

The Pinebook Pro comes equipped with two non-volatile storage components, the eMMC and the SPI. The capacity of the SPI is 128MiB and it may be used in the boot process.

Boot data can be written to the SPI via two methods: either from within PBP or from a second machine connected to the PBP by USB.

Writing to SPI from within PBP

Forum user pcm720 showed an example of writing to the SPI from within PBP in their self-published version of U-Boot that offers boot functionality for NVMe drives. It involves use of flash_erase command (available in the mtd-utils package on Arch/Manjaro) and the dd command.

Writing to SPI from a second machine

Writing to the SPI from a second machine is more complicated than the other method, but it is the only option when troubleshooting an SPI flash gone wrong. This method works by bringing the PBP into maskrom mode and issuing commands on the second machine that download the flash image onto the PBP.

Upon entering maskrom mode, the power LED on your PBP won't light up and neither will the display. Instead, your second machine, the one connected to your PBP via USB, will indicate maskrom mode by logging to journalctl.

There are two ways to reach maskrom mode, but the first tends to be less reliable.

Maskrom mode (unreliable method)

According to Rockchip documentation, these steps should work; unfortunately, many users have reported them to be unsuccessful. You may need to repeat these steps several times for them to work.

  1. Press and hold recovery button.
  2. Short press reset.
  3. Release recovery button after about 3 seconds.

Why this procedure is unreliable is not clear, but there are two suspicions:

  • The button is not working correctly or is just prone to failures.
  • The problem occurs only when the SPI was previously flashed.

The button works by shorting two pins in the SPI device. But in some cases it just does nothing. Fortunately, the two pins can shorted by hand, as described in the next method.

Maskrom mode (reliable method)

  1. Build and install rkdeveloptool (see project repository for instructions)
  2. Verify successful installation. Running rkdeveloptool --version should output: rkdeveloptool ver 1.3
  3. Run journalctl -f and keep it running. Once maskrom mode is reached it will produce additional output.
  4. Unscrew bottom cover.
  5. Remove the metal shield surrounding main CPU. The shield is held in place by a tape and micro clamps on the board. The clamps can be released with a pry tool and some force. This forum post with photos shows how it can be done.
  6. Disconnect all (!!!) boot devices (emmc, sdcard, usb).
  7. Locate SPI flash (component number 29 on this photo of the Pinebook Pro internals).
  8. Connect your PBP with USB-C - USB-A cable to second machine (PBP on USB-C side)
  9. Short pins CLK and VSS (see chip diagram below for names of pins). This can be done with a pair of tweezers when short on tools. Spi.png
  10. Press the reset button (component number 28)
  11. Check if there is new output from journalctl program.
  12. Check if the PBP connected by running rkdeveloptool ld. If successful, the output should be like: DevNo=1 Vid=0x2207,Pid=0x330c,LocationID=1401 Maskrom

After entering maskrom mode

Now that the PBP is in maskrom mode, you can use rkdeveloptool to write data to the SPI. To do so you'll need the binary file you'll be writing to SPI, which will be referred to as SPI_new.bin, and a helper file named rk3399_loader_spinor_v1.15.114.bin.

  1. Flash the flash helper db file: rkdeveloptool db rk3399_loader_spinor_v1.15.114.bin. If successful, the output should read Downloading bootloader succeeded.
  2. Flash the new SPI binary: rkdeveloptool wl 0 SPI_new.bin. If successful, the output should read: Write LBA from file (100%).
  3. Test the installation: rkdeveloptool td. If successful, output should read Reset Device OK.
  4. Run rkdeveloptool rd to reboot your Pinebook Pro.

Zeroing out the SPI

In case, you wrote something bad to your SPI, it's helpful to wipe away that data with zeros. To do that, you follow the same steps above to enter maskrom mode and then write an binary file that consists of all zeros.

  1. Create the binary file dd if=/dev/zero of=zero.bin bs=1M count=16
  2. Flash the flash helper db file: rkdeveloptool db rk3399_loader_spinor_v1.15.114.bin. If successful, the output should read Downloading bootloader succeeded.
  3. Flash the new SPI binary: rkdeveloptool wl 0 zero.bin. If successful, the output should read: Write LBA from file (100%).
  4. Test the installation: rkdeveloptool td. If successful, output should read Reset Device OK.
  5. Run rkdeveloptool rd to reboot your Pinebook Pro.