.. _uboot-environment:

Environment
===========

U-Boot configuration and startup behaviour is defined in its
environment and therein held variables. While the environment's
default values are pre-defined in the U-Boot source code, these
settings and values can be overwritten by editing the respecitive
variables, either for short term till the next reboot or permantly by
writing the changed values into area in the permanent memory (NVM:
NAND or eMMC). Which in turn will be loaded at boot time.

Comprehensive description of these features is available in the `The
U-Boot Documentation`_, there specifically in the
`Environment Variables`_ section.


Reset of Variables
------------------

Users can reset the environment as a whole, or can reset just specific
variables. Selectively resetting variables can be used to access
variables or environment settings that have been updated or added
between releases.
To unset an environment variable the same common procedure as setting
is used; but instead setting it to an empty string.

.. warning::

   As long as the command ``saveenv`` is not executed, changes to the
   environment will be lost upon reset.


Examples:

- Unset a variable

  unset ``append_bootargs`` (set empty string)

  .. prompt::
     :prompts: U-Boot>

     setenv append_bootargs
     saveenv


- Reset the whole environment

  .. prompt::
     :prompts: U-Boot>

     env default -a
     saveenv


- Reset a specific variable to its compiled-in default value

  .. prompt::
     :prompts: U-Boot>

     env default <variable>
     saveenv

  E.g. resetting ``fdtsave``

  .. prompt::
     :prompts: U-Boot>

     env default fdtsave
     saveenv

  .. note::

     Resetting a variable that's not part of the compiled in default environment will be deleted, accompanied by the following message:
     ``WARNING: '<variable>' not in imported env, deleting it!``


Automatically assigned variables
--------------------------------

U-Boot will automagically assign some environment variables upon boot
or after certain actions.

.. list-table::
   :header-rows: 1

   * - Variable

     - Purpose

     - Remarks

   * - ethaddr

       eth1addr

     - MAC address(es) assigned to the ethernet interface(s)

     - Initialized from OTP memory, if unset

       Once saved, the value won't be changed by U-Boot

   * - uuid_rootfs

       uuid_boot

       uuid_userfs

     - UUIDs of various mass storage partitions 

     - partition UUID from the GPT


   * - serial#
     
     - Globally Unique Identifier from the processor's OTP memory

     - will be used e.g. for setting the name of the mass storage
       device on the host created with the ``ums`` command

   * - fileaddr

       filesize

     - convey information about the most recent 'load' or
       'tftpboot/bootp' command

     - will be unset upon boot

   * - fdt_size

     - provides the size of the in-memory FDT

     - will be changed by fdt resize

   * - fdtcontroladdr

     - RAM address of the U-Boot internal FDT

     - You may inspect the FDT that is used to configure the U-Boot
       internal devices:

       .. prompt::
	  :prompts: U-Boot >

	  fdt addr ${fdtcontroladdr}
	  fdt print


.. _`Environment Variables`: https://u-boot.readthedocs.io/en/latest/usage/environment.html
.. _`The U-Boot Documentation`: https://u-boot.readthedocs.io