Back to turingpi.com

Failsafe boot

Suggest Edits

Safe mode

Using Safe mode, users can recover their boards in case its not booting anymore. Safe mode temporarily disables all user modifications to the filesystem, effectively booting the board with "factory settings." After a successive reboot, the board boots again with all the files present as before the safe boot.

👍

user files are perserved

Failsafe will never remove or permanently change any files that the user created.

If failsafe is activated and your board is still not booting, we recommend you ask for help on Discord or our Question section.

Entering safe mode

  • restart your board
  • Press the KEY_1 button for 5 seconds
  • if you have a serial cable connected to the BMC UART3 port, you see the following logline passing by:
PREINIT: Starting  
PREINIT: Entering safemode
  • Logged in to the BMC, verify that you are in safe mode by checking the environment variable "IS_SAFEMODE":
$IS_SAFEMODE && echo "we are in safemode!"

About read-only filesystems

The BMC uses a read-only filesystem, EROFS. This filesystem can layer multiple partitions on top of each other. This enables us to upgrade the bottom layer, our base firmware, without wiping any files residing on the user layer. We will not go into much detail on how this works, but its important to understand that these layers are opaque to the user and that in safe mode, the user partition is mounted to an arbitrary directory rather than layered on top of the root filesystem.

Change files in the user layer

So, you identified why your board is not working, and a change to one of your files is required. However, you cannot find the file in its usual place. Remember, this is because the user layer gets mounted to a different place in safe mode. In safe mode, this partition is remounted to/tmp/safeboot/upper. Any modifications can be made here. When you are satisfied, call.reboot to reboot the system. Your board will start up again in normal mode.

Recovery mode

When KEY1 is pressed for 15 seconds during boot, or if no valid OS is found, "recovery mode" is entered. Depending on if you are running Linux from your SD card or, more conventionally, from Flash the following will happen:

  • Flash

an attempt is made to do a netboot over DHCP. If failed, it falls back to providing the U-Boot console over netconsole.

  • (micro)SD card

exposes the microSD card over the USB interface as a mass storage device

Updated 14 days ago