README: Add doumentation for version information

There are quite a few available version options in U-Boot. Add a list of
the available Makefile variables and #defines, along with examples.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Bin Meng <bmeng.cn@gmail.com>

diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index beaa64d8d90a21785afa4ec9f0bf843ae8e96a13..ac57fdb8f30815089f1650ca5e9ca864c4e815d8 100644 (file)
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -13,6 +13,7 @@ Implementation
    global_data
    logging
    menus
+   version
 
 Debugging
 ---------

diff --git a/doc/develop/version.rst b/doc/develop/version.rst
new file mode 100644 (file)
index 0000000..6da31a4
--- /dev/null
+++ b/doc/develop/version.rst
@@ -0,0 +1,93 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2013 The Chromium OS Authors.
+
+Version information
+===================
+
+U-Boot releases are named by year and patch level, for example 2020.10 means the
+release that came out in October 2020. Release candidates are tagged every few
+weeks as the project heads to the next release. So 2020.10-rc1 was the first
+release candidate (RC), tagged soon after 2020.07 was released.
+
+See https://www.denx.de/wiki/view/U-Boot/ReleaseCycle for full details.
+
+Within the build system, various Makefile variables are created, making use of
+VERSION, PATCHLEVEL and EXTRAVERSION defined at the top of 'Makefile'. There is
+also SUBLEVEL available for downstream use. See also CONFIG_IDENT_STRING.
+
+Some variables end up in a generated header file at
+include/generated/version_autogenerated.h and can be accessed from C source by
+including <version.h>
+
+The following are available:
+
+   UBOOTRELEASE (Makefile)
+      Full release version as a string. If this is not a tagged release, it also
+      includes the number of commits since the last tag as well as the the git
+      hash.  If there are uncommitted changes a '-dirty' suffix is added too.
+
+      This is written by scripts/setlocalversion (maintained by Linux) to
+      include/config/uboot.release and ends up in the UBOOTRELEASE Makefile
+      variable.
+
+      Examples::
+
+         2020.10-rc3
+         2021.01-rc5-00248-g60dd854f3ba-dirty
+
+   PLAIN_VERSION (string #define)
+      This is UBOOTRELEASE but available in C source.
+
+      Examples::
+
+         2020.10
+         2021.01-rc5-00248-g60dd854f3ba-dirty
+
+   UBOOTVERSION (Makefile)
+      This holds just the first three components of UBOOTRELEASE (i.e. not the
+      git hash, etc.)
+
+      Examples::
+
+         2020.10
+         2021.01-rc5
+
+   U_BOOT_VERSION (string #define)
+      "U-Boot " followed by UBOOTRELEASE, for example::
+
+         U-Boot 2020.10
+         U-Boot 2021.01-rc5
+
+      This is used as part of the banner string when U-Boot starts.
+
+   U_BOOT_VERSION_STRING (string #define)
+      U_BOOT_VERSION followed by build-time information
+      and CONFIG_IDENT_STRING.
+
+      Examples::
+
+         U-Boot 2020.10 (Jan 06 2021 - 08:50:36 -0700)
+         U-Boot 2021.01-rc5-00248-g60dd854f3ba-dirty (Jan 06 2021 - 08:50:36 -0700) for spring
+
+Build date/time is also included. See the generated file
+include/generated/timestamp_autogenerated.h for the available
+fields. For example::
+
+   #define U_BOOT_DATE "Jan 06 2021"     (US format only)
+   #define U_BOOT_TIME "08:50:36"        (24-hour clock)
+   #define U_BOOT_TZ "-0700"             (Time zone in hours)
+   #define U_BOOT_DMI_DATE "01/06/2021"  (US format only)
+   #define U_BOOT_BUILD_DATE 0x20210106  (hex yyyymmdd format)
+   #define U_BOOT_EPOCH 1609948236
+
+The Epoch is the number of seconds since midnight on 1/1/70. You can convert
+this to a time with::
+
+   $ date -u -d @1609948236
+   Wed 06 Jan 2021 03:50:36 PM UTC
+   $ date -d 'Wed 06 Jan 2021 03:50:36 PM UTC' +%s
+   1609948236
+
+Every time you build U-Boot this will update based on the time
+on your build machine. See 'Reproducible builds' if you want to
+avoid that.