.. index::
    FSBL Fallback Mechanism

.. _fsbl_fallback:

FSBL Fallback Mechanism
:::::::::::::::::::::::

We developed a modification of Xilinx First Stage Boot Loader (FSBL) to support
a fallback boot to a valid known BOOT.BIN file.
The idea is to have a mechanism to allow the boards boot using a known BOOT.BIN
file after a failed boot due to the usage of a wrong/corrupted BOOT.BIN.
Fallback mechanism operational flow is the following:

-  Does the ``FLBK.TXT`` file exist in the root of the BOOT partition?
-  Yes. Enter in fallback mode and boot using the ``FLBK.BIN`` file
-  No. Create the ``FLBK.TXT`` file and follow with a regular boot
   (usually using the ``BOOT.BIN`` file).
-  The OS should mount the boot partition and remove the ``FLBK.TXT``
   file after each boot (aka a successful boot).


FSBL Patch
''''''''''

:download:`FSBL Patch file (fsbl_patch_v010.diff) <files/fsbl_patch_v010.diff>`

In addition to the patch, the read-only filesystem protection must be
disabled before the BOOT.BIN generation to allow the fallback mechanism work.
This can be done by editing the ``xparameters.h`` file
(``components/bootloader/zynqmp_fsbl/zynqmp_fsbl_bsp/psu_cortexa53_0/include/xparameters.h``)
and removing any definition of ``FILE_SYSTEM_READ_ONLY`` pre-processor variable.
Note that this header is re-generated/updated by petalinux tools in some steps.
We need to ensure that it is properly edited when the bootloader is compiled,
usually during the ``petalinux-build`` step.


System cleanup service
''''''''''''''''''''''

:download:`Systemctl service (remove-fsbl-flbk.service) <files/remove-fsbl-flbk.service>`

This service mounts the boot partition and removes the FSBL.TXT file created by
the BSC FSBL. If the file is not removed, the next boot will use the
``FLBK.BIN`` file instead of ``BOOT.BIN``. To install the service, copy the
service file in the /etc/systemd/system/ folder and enable it with the following
commands (they may require root privileges):

.. code:: bash

    systemctl daemon-reload
    systemctl enable remove-fsbl-flbk.service
    systemctl start remove-fsbl-flbk.service