Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

6 files changed, 319 insertions, 0 deletions

diff --git a/roms/u-boot/doc/build/clang.rst b/roms/u-boot/doc/build/clang.rst
new file mode 100644
index 000000000..1d35616eb
--- /dev/null
+++ b/roms/u-boot/doc/build/clang.rst
@@ -0,0 +1,76 @@
+Building with Clang
+===================
+
+The biggest problem when trying to compile U-Boot with Clang is that almost all
+archs rely on storing gd in a global register and the Clang 3.5 user manual
+states: "Clang does not support global register variables; this is unlikely to
+be implemented soon because it requires additional LLVM backend support."
+
+The ARM backend can be instructed not to use the r9 and x18 registers using
+-ffixed-r9 or -ffixed-x18 respectively. As global registers themselves are not
+supported inline assembly is needed to get and set the r9 or x18 value. This
+leads to larger code then strictly necessary, but at least works.
+
+**NOTE:** target compilation only work for _some_ ARM boards at the moment.
+Also AArch64 is not supported currently due to a lack of private libgcc
+support. Boards which reassign gd in c will also fail to compile, but there is
+in no strict reason to do so in the ARM world, since crt0.S takes care of this.
+These assignments can be avoided by changing the init calls but this is not in
+mainline yet.
+
+
+Debian based
+------------
+
+Required packages can be installed via apt, e.g.
+
+.. code-block:: bash
+
+    sudo apt-get install clang
+
+Note that we still use binutils for some tools so we must continue to set
+CROSS_COMPILE. To compile U-Boot with Clang on Linux without IAS use e.g.
+
+.. code-block:: bash
+
+    make HOSTCC=clang rpi_2_defconfig
+    make HOSTCC=clang CROSS_COMPILE=arm-linux-gnueabi- \
+         CC="clang -target arm-linux-gnueabi" -j8
+
+It can also be used to compile sandbox:
+
+.. code-block:: bash
+
+    make HOSTCC=clang sandbox_defconfig
+    make HOSTCC=clang CC=clang -j8
+
+
+FreeBSD 11
+----------
+
+Since llvm 3.4 is currently in the base system, the integrated assembler as
+is incapable of building U-Boot. Therefore gas from devel/arm-gnueabi-binutils
+is used instead. It needs a symlink to be picked up correctly though:
+
+.. code-block:: bash
+
+    ln -s /usr/local/bin/arm-gnueabi-freebsd-as /usr/bin/arm-freebsd-eabi-as
+
+The following commands compile U-Boot using the Clang xdev toolchain.
+
+**NOTE:** CROSS_COMPILE and target differ on purpose!
+
+.. code-block:: bash
+
+    export CROSS_COMPILE=arm-gnueabi-freebsd-
+    gmake rpi_2_defconfig
+    gmake CC="clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd" -j8
+
+Given that U-Boot will default to gcc, above commands can be
+simplified with a simple wrapper script - saved as
+/usr/local/bin/arm-gnueabi-freebsd-gcc - listed below:
+
+.. code-block:: bash
+
+    #!/bin/sh
+    exec clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd "$@"
diff --git a/roms/u-boot/doc/build/docker.rst b/roms/u-boot/doc/build/docker.rst
new file mode 100644
index 000000000..953d1b28a
--- /dev/null
+++ b/roms/u-boot/doc/build/docker.rst
@@ -0,0 +1,14 @@
+GitLab CI / U-Boot runner container
+===================================
+
+In order to have a reproducible and portable build environment for CI we use a container for building in.  This means that developers can also reproduce the CI environment, to a large degree at least, locally.  This file is located in the tools/docker directory.  To build the image yourself
+
+.. code-block:: bash
+
+    sudo docker build -t your-namespace:your-tag .
+
+Or to use an existing container
+
+.. code-block:: bash
+
+    sudo docker pull trini/u-boot-gitlab-ci-runner:bionic-20200807-02Sep2020
diff --git a/roms/u-boot/doc/build/gcc.rst b/roms/u-boot/doc/build/gcc.rst
new file mode 100644
index 000000000..c51b3e73b
--- /dev/null
+++ b/roms/u-boot/doc/build/gcc.rst
@@ -0,0 +1,139 @@
+Building with GCC
+=================
+
+Dependencies
+------------
+
+For building U-Boot you need a GCC compiler for your host platform. If you
+are not building on the target platform you further need  a GCC cross compiler.
+
+Debian based
+~~~~~~~~~~~~
+
+On Debian based systems the cross compiler packages are named
+gcc-<architecture>-linux-gnu.
+
+You could install GCC and the GCC cross compiler for the ARMv8 architecture with
+
+.. code-block:: bash
+
+    sudo apt-get install gcc gcc-aarch64-linux-gnu
+
+Depending on the build targets further packages maybe needed
+
+.. code-block:: bash
+
+    sudo apt-get install bc bison build-essential coccinelle \
+      device-tree-compiler dfu-util efitools flex gdisk liblz4-tool \
+      libguestfs-tools libncurses-dev libpython3-dev libsdl2-dev libssl-dev \
+      lzma-alone openssl python3 python3-coverage python3-pyelftools \
+      python3-pytest python3-sphinxcontrib.apidoc python3-sphinx-rtd-theme swig
+
+SUSE based
+~~~~~~~~~~
+
+On suse based systems the cross compiler packages are named
+cross-<architecture>-gcc<version>.
+
+You could install GCC and the GCC 10 cross compiler for the ARMv8 architecture
+with
+
+.. code-block:: bash
+
+    sudo zypper install gcc cross-aarch64-gcc10
+
+Depending on the build targets further packages maybe needed.
+
+.. code-block:: bash
+
+    zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \
+      ncurses-devel python3-devel python3-pytest swig
+
+Prerequisites
+-------------
+
+For some boards you have to build prerequisite files before you can build
+U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware
+beforehand. Please, refer to the board specific documentation
+:doc:`../board/index`.
+
+Configuration
+-------------
+
+Directory configs/ contains the template configuration files for the maintained
+boards following the naming scheme::
+
+    <board name>_defconfig
+
+These files have been stripped of default settings. So you cannot use them
+directly. Instead their name serves as a make target to generate the actual
+configuration file .config. For instance the configuration template for the
+Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file
+is generated by
+
+.. code-block:: bash
+
+    make odroid-c2_defconfig
+
+You can adjust the configuration using
+
+.. code-block:: bash
+
+    make menuconfig
+
+Building
+--------
+
+When cross compiling you will have to specify the prefix of the cross-compiler.
+You can either specify the value of the CROSS_COMPILE variable on the make
+command line or export it beforehand.
+
+.. code-block:: bash
+
+    CROSS_COMPILE=<compiler-prefix> make
+
+Assuming cross compiling on Debian for ARMv8 this would be
+
+.. code-block:: bash
+
+    CROSS_COMPILE=aarch64-linux-gnu- make
+
+Build parameters
+~~~~~~~~~~~~~~~~
+
+A list of available parameters for the make command can be obtained via
+
+.. code-block:: bash
+
+    make help
+
+You can speed up compilation by parallelization using the -j parameter, e.g.
+
+.. code-block:: bash
+
+    CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc)
+
+Further important build parameters are
+
+* O=<dir> - generate all output files in directory <dir>, including .config
+* V=1 - verbose build
+
+Other build targets
+~~~~~~~~~~~~~~~~~~~
+
+A list of all make targets can be obtained via
+
+.. code-block:: bash
+
+    make help
+
+Important ones are
+
+* clean - remove most generated files but keep the configuration
+* mrproper - remove all generated files + config + various backup files
+
+Installation
+------------
+
+The process for installing U-Boot on the target device is device specific.
+Please, refer to the board specific documentation :doc:`../board/index`.
diff --git a/roms/u-boot/doc/build/index.rst b/roms/u-boot/doc/build/index.rst
new file mode 100644
index 000000000..69952f90d
--- /dev/null
+++ b/roms/u-boot/doc/build/index.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Build U-Boot
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   source
+   gcc
+   clang
+   docker
+   tools
diff --git a/roms/u-boot/doc/build/source.rst b/roms/u-boot/doc/build/source.rst
new file mode 100644
index 000000000..470f79398
--- /dev/null
+++ b/roms/u-boot/doc/build/source.rst
@@ -0,0 +1,30 @@
+Obtaining the source
+=====================
+
+The source of the U-Boot project is maintained in a Git repository.
+
+You can download the source via
+
+.. code-block:: bash
+
+    git clone https://source.denx.de/u-boot/u-boot.git
+
+A mirror of the source is maintained on Github
+
+.. code-block:: bash
+
+    git clone https://github.com/u-boot/u-boot
+
+The released versions are available as tags which use the naming scheme::
+
+    v<year>.<month>
+
+Release candidates are named::
+
+    v<year>.<month>-rc<number>
+
+To checkout the October 2020 release you would use:
+
+.. code-block:: bash
+
+    git checkout v2020.10
diff --git a/roms/u-boot/doc/build/tools.rst b/roms/u-boot/doc/build/tools.rst
new file mode 100644
index 000000000..c06f91527
--- /dev/null
+++ b/roms/u-boot/doc/build/tools.rst
@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com>
+
+Host tools
+==========
+
+Building tools for Linux
+------------------------
+
+To allow distributions to distribute all possible tools in a generic way,
+avoiding the need of specific tools building for each machine, a tools only
+defconfig file is provided.
+
+Using this, we can build the tools by doing::
+
+   $ make tools-only_defconfig
+   $ make tools-only
+
+Building tools for Windows
+--------------------------
+If you wish to generate Windows versions of the utilities in the tools directory
+you can use MSYS2, a software distro and building platform for Windows.
+
+Download the MSYS2 installer from https://www.msys2.org. Make sure you have
+installed all required packages below in order to build these host tools::
+
+   * gcc (9.1.0)
+   * make (4.2.1)
+   * bison (3.4.2)
+   * diffutils (3.7)
+   * openssl-devel (1.1.1.d)
+
+Note the version numbers in these parentheses above are the package versions
+at the time being when writing this document. The MSYS2 installer tested is
+http://repo.msys2.org/distrib/x86_64/msys2-x86_64-20190524.exe.
+
+There are 3 MSYS subsystems installed: MSYS2, MinGW32 and MinGW64. Each
+subsystem provides an environment to build Windows applications. The MSYS2
+environment is for building POSIX compliant software on Windows using an
+emulation layer. The MinGW32/64 subsystems are for building native Windows
+applications using a linux toolchain (gcc, bash, etc), targeting respectively
+32 and 64 bit Windows.
+
+Launch the MSYS2 shell of the MSYS2 environment, and do the following::
+
+   $ make tools-only_defconfig
+   $ make tools-only NO_SDL=1