.. include:: ../substitutions.rst

.. _ConfiguringTheBootloader-62A:

Configuring the Bootloader
==========================

Change the Device Tree
----------------------

By default, U-Boot loads a device tree binary (dtb) file named *oftree* during boot. The *oftree* file is a copy of *k3-am62a7-phyboard-lyra-rdk.dtb*. This portion of the guide will instruct how to change U-boot to load different device trees.

* Power on the board and press any key to stop autoboot when prompted by the Bootloader.
* Use the following command to list the available file's within the boot media's Boot partition (this is typically where binaries used for boot are stored):

  .. code-block:: console
    :substitutions:

    |uboot-prompt| ls mmc 1:1

  .. code-block:: console
    :substitutions:
    :caption: Example Output

    |uboot-prompt| ls mmc 1:1
               EFI/
    21608960   Image
         361   k3-am6-phycore-disable-eth-phy.dtbo
         234   k3-am6-phycore-disable-rtc.dtbo
         235   k3-am6-phycore-disable-spi-nor.dtbo
        1627   k3-am62-phyboard-lyra-gpio-fan.dtbo
        3620   k3-am62-phyboard-lyra-m2-lwb5p.dtbo
        2001   k3-am62-phyboard-lyra-vm016-mipi.dtbo
         908   k3-am62-phyboard-lyra-x17-spi0.dtbo
       59467   k3-am62a7-phyboard-lyra-rdk.dtb
       59467   oftree
      298498   tiboot3.bin
      990887   tispl.bin
      948203   u-boot.img


* We can check which file is the active device tree like so:

  .. code-block:: console
    :substitutions:

    |uboot-prompt| printenv fdtfile

* Change the default device tree.

  .. code-block:: console
    :substitutions:

    |uboot-prompt| setenv fdtfile <dtb name>
    |uboot-prompt| saveenv
    |uboot-prompt| boot

U-boot will now load the dtb file named '<dtb name>' automatically during subsequent boots (just replace it with the appropriate file name when you run the command).

Working with Overlays
---------------------

The PHYTEC BSP also comes with some device tree overlays to help evaluate certain interfaces and accessory hardware. The table "`Linux Device Tree Summary <https://docs.phytec.com/projects/yocto-phycore-am62ax/en/bsp-yocto-ampliphy-am62ax-pd23.1.1/releasenotes/pd23.1.1.html#linux-device-tree-summary>`_ in the Release Notes shows an overview of all available overlays.


Enable an Overlay
~~~~~~~~~~~~~~~~~

* U-boot has an extra environment variable called "overlays" to apply device tree overlay files. We can enable device tree overlays with it like so:

.. code-block:: console
    :substitutions:

    |uboot-prompt| setenv overlays k3-am62-phyboard-lyra-vm016-mipi.dtbo
    |uboot-prompt| saveenv
    |uboot-prompt| boot

* Moreover, it's possible to enable multiple overlays by separating them with a space.

.. code-block:: console
    :substitutions:

    |uboot-prompt| setenv overlays k3-am62-phyboard-lyra-vm016-mipi.dtbo k3-am62-phyboard-lyra-x17-spi0.dtbo
    |uboot-prompt| saveenv
    |uboot-prompt| boot

The ``saveenv`` command stores the boot environment to non-volatile memory. If you would like temporarily adjust the boot environment, you can omit the ``saveenv`` command and the boot environment will go back to the previously saved settings on the next boot.

Reset the U-Boot Environment to Default Settings
------------------------------------------------

* In order to revert the U-Boot environment back to its original settings, run the following:

.. code-block:: console
    :substitutions:

    |uboot-prompt| env default -f -a
    |uboot-prompt| saveenv
    |uboot-prompt| boot

.. note:: When booting from the SD card, if you have saved changes to the environment using ``saveenv``, the changes may persist across flashes of the SD card. It is a good idea to default your environment after flashing.