infra/common: add troubleshooting guide

Add troubleshooting guide to help rectifiying commonly faced problems.

Signed-off-by: Vijayenthiran Subramaniam <vijayenthiran.subramaniam@arm.com>
Change-Id: If2584c969179abbe8e9ce3f5d92e60a1ab7c63b7

docs/infra/common/busybox-boot.rst

@@ -64,6 +64,9 @@ Supported command line options are listed below
     - ``package``
     - ``all`` (all of the three above)
 
+Note: On networks where git port is blocked, the build procedure might not
+progress. Refer the `troubleshooting guide`_ for possible ways to resolve
+this issue.
 
 Examples of the build command are
 
@@ -177,3 +180,4 @@ Example commands to boot upto busybox are as listed below.
 
 .. _Download sources: docs/infra/common/download-sources.rst
 .. _Platform Names: docs/infra/common/platform_names.rst
+.. _troubleshooting guide: docs/infra/common/troubleshooting-guide.rst

docs/infra/common/download-sources.rst

@@ -115,6 +115,11 @@ This section explains the procedure to sync the software stack.
   ``Release Tags`` section of the corresponding platform's user guide or from
   the release notes, if obtained.
 
+  Note: The repo tool requires at least Python 3.6 to be installed on the
+  development machine. On machines where python3 is not the default, the
+  repo init command will fail to complete. Refer the `troubleshooting guide`_
+  on resolving this issue.
+
 
 Installing prerequisites
 ------------------------
@@ -182,8 +187,12 @@ following commands on the host machine.
 
 This completes the procedure to download the platform software stack, setup
 of the GCC toolchain binaries and installation of the other prerequisites.
+Refer the `troubleshooting guide`_ for solutions to known issues that might
+arise during use of the platform software stack.
 
 
 --------------
 
 *Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
+
+.. _troubleshooting guide: docs/infra/common/troubleshooting-guide.rst

docs/infra/common/troubleshooting-guide.rst

+Troubleshooting Guide
+=====================
+
+.. contents::
+
+Introduction
+------------
+
+The documentation for Neoverse reference design platform software typically
+suffices in most cases. But there could be certain host development machine
+dependencies that could cause failures either during build and execution
+stages. This page provides solutions for known issues that could affect the
+use of the platform software stack.
+
+
+Error while using repo command
+------------------------------
+
+The `repo init` or `repo sync` command fails with the below listed error
+message.
+
+::
+
+  File "<path-to-workspace>/.repo/repo/main.py", line 79
+  file=sys.stderr)
+      ^
+  SyntaxError: invalid syntax
+
+
+The typical reason for this failure could be that the default version of python
+on the development machine is not python3.6. To resolve this issue, install the
+latest version of python, if not already installed on the development machine
+and invoke the repo command from `/usr/bin/` with `python3` as listed below.
+
+::
+
+  python3 /usr/bin/repo init -u https://git.gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest.git -m pinned-rdv1.xml -b refs/tags/RD-INFRA-2021.02.24
+  python3 /usr/bin/repo sync -c -j $(nproc) --fetch-submodules --force-sync
+
+
+Builds do not progress to completion
+------------------------------------
+
+During the build of the platform software stack, components such as grub
+download additional code from remote repositories using the git port (or the
+git protocol). Development machines on which git port is blocked, the build
+does not progress to completion, waiting for the additional code to be
+downloaded. This typically is observed when setting up a new platform software
+workspace.
+
+As a workaround, use https instead of git protocol for cloning required git
+submodules of the various components in the software stack. A patch, as an
+example of this change in the grub component, is listed below.
+
+::
+
+  diff --git a/bootstrap b/bootstrap
+  index 5b08e7e2d..031784582 100755
+  --- a/bootstrap
+  +++ b/bootstrap
+  @@ -47,7 +47,7 @@ PERL="${PERL-perl}"
+
+   me=$0
+
+  -default_gnulib_url=git://git.sv.gnu.org/gnulib
+  +default_gnulib_url=https://git.savannah.gnu.org/git/gnulib.git
+
+   usage() {
+     cat <<EOF
+
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*