Commit cb0c81fd authored by Vijayenthiran Subramaniam's avatar Vijayenthiran Subramaniam Committed by Thomas Abraham
Browse files

infra/common: add troubleshooting guide

Add troubleshooting guide to help rectifiying commonly faced problems.

Signed-off-by: Vijayenthiran Subramaniam's avatarVijayenthiran Subramaniam <>
Change-Id: If2584c969179abbe8e9ce3f5d92e60a1ab7c63b7
parent 157aa7d9
......@@ -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
......@@ -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
Troubleshooting Guide
.. contents::
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
File "<path-to-workspace>/.repo/repo/", line 79
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 -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
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}"
usage() {
cat <<EOF
*Copyright (c) 2021, Arm Limited. All rights reserved.*
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment