infra/common: document linux distro install and boot procedures

Add a new document that explains the procedure to install and boot linux
distributions on the Neoverse Reference Design platforms.

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

docs/infra/common/distro-boot.rst

+Install and boot a linux distribution on Neoverse RD platforms
+==============================================================
+
+.. contents::
+
+
+Linux distribution boot
+-----------------------
+
+Neoverse Reference Design (RD) platform software stack supports the installation
+and boot of various linux distributions such as Debian, Ubuntu or Fedora. The
+distribution is installed on a SATA disk and the installed image can be used for
+multiple boots.
+
+
+Platform Names
+--------------
+
+Arm's Neoverse reference design platforms are assigned names in order to allow
+the build and execute scripts to recognize the platform for which the software
+has to be built and executed. The names for the reference platforms are listed
+below. Please make a note of the name of the platform of your choice. This name
+is required to start the build and execute procedure. The names under 'Platform
+Name' column has to be used in place of the placeholder ``<platform>`` as
+mentioned in the commands listed below.
+
+
++--------------------------+-------------------------+
+| Reference Platform       | Platform Name           |
++==========================+=========================+
+| SGI-575                  | sgi575                  |
++--------------------------+-------------------------+
+| RD-N1-Edge (Single Chip) | rdn1edge                |
++--------------------------+-------------------------+
+| RD-N1-Edge (Dual Chip)   | rdn1edgex2              |
++--------------------------+-------------------------+
+| RD-E1-Edge               | rde1edge                |
++--------------------------+-------------------------+
+| RD-Daniel Config-M       | rddaniel                |
++--------------------------+-------------------------+
+| RD-Daniel Config-XLR     | rddanielxlr             |
++--------------------------+-------------------------+
+| RD-N2                    | rdn2                    |
++--------------------------+-------------------------+
+
+
+Download the platform software
+------------------------------
+
+Skip this section if the required sources have been downloaded.
+
+To obtain the required sources for the platform, follow the steps listed on the
+`Download sources`_ page. Ensure that the platform software is downloaded before
+proceeding with the steps listed below. Also, note the host machine requirements
+listed on that page which is essential to build and execute the platform
+software stack.
+
+
+Build the platform software
+---------------------------
+
+This section describes the procedure to build the platform firmware required to
+install and boot a linux distribution on Neoverse RD platforms.
+
+To build the RD software stack, the command to be used is
+
+::
+
+  ./build-scripts/build-test-uefi.sh -p <platform> <command>
+
+Supported command line options are listed below
+
+* <platform>
+
+  - Supported platforms are listed in `Platform Names`_.
+
+* <command>
+
+  - ``clean``
+  - ``build``
+  - ``package``
+  - ``all`` (all of the three above)
+
+
+Examples of the build command are
+
+- Command to clean, build and package the RD-N2 software stack required for
+  the distro installation/boot test on the platform:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rdn2 all
+
+- Command to remove the generated outputs (binaries) of the software stack for
+  the RD-N2 platform:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rdn2 clean
+
+- Command to perform an incremental build of the software components included in
+  the software stack for the RD-Daniel Config-XLR platform:
+
+  *Note:* this command should be followed by the ``package`` command to
+  complete the preparation of the fip image.
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rddanielxlr build
+
+- Command to package the previously built software stack and prepares the fip
+  image:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rddanielxlr package
+
+
+Installing a linux distribution
+-------------------------------
+
+After the build of the platform software stack for the distro install/boot is
+complete, a distribution can be installed into a SATA disk image. Before
+beginning the installation process, download the CD iso image of the required
+distribution version.
+
+Latest version of distro installation images can be downloaded from the
+following locations (select an image built for aarch64 architecture):
+
+- `Fedora <https://alt.fedoraproject.org/alt>`_
+- `Ubuntu <https://ubuntu.com/download/server/arm>`_
+- `Debian <https://www.debian.org/distrib/netinst>`_
+
+The commands used to begin the distro installation are:
+
+- If platform is SGI-575:
+
+  ::
+
+    cd model-scripts/sgi
+
+- If platform is an RD:
+
+  ::
+
+    cd model-scripts/rdinfra
+
+- Launch the installation:
+
+  ::
+
+    ./distro.sh -p <platform> -i <abs_iso_image_path> -s <disk size> -a <additional_params> -n [true|false]
+
+Supported command line options are listed below
+
+*  -p <platform>
+
+   - Supported platforms are listed in `Platform Names`_.
+
+*  -i <abs_iso_image_path>
+
+   - Absolute path to the downloaded distribution installer disk image.
+
+*  -s <disk_size>
+
+   - Size of the SATA disk image (in GB) to be created. 12GB and above is
+     good enough for most use cases.
+
+*  -n [true|false] (optional)
+
+   - Controls the use of network ports by the model. If network ports have
+     to be enabled, use 'true' as the option. Default value is set to
+     'false'.
+
+*  -a <additional_params>
+
+   - Specify any additional model parameters to be passed. The model
+     parameters and the data to be passed to those parameters can be found
+     in the FVP documentation.
+
+
+An example of a command to install the debian distribution is listed below.
+
+::
+
+  ./distro.sh -p rddaniel -i /absolute/path/to/debian-10.6.0-arm64-xfce-CD-1.iso -s 16
+
+
+- This command creates a 16GB SATA disk image, boots the RD-Daniel Config-M
+  software stack and starts the installation of debian distribution.
+
+- From here on, follow the instructions of the choosen distribution
+  installer. For more information about the installation procedure, refer
+  online installation manuals of the choosen distribution.
+
+- After the installation is completed, the disk image with a random name
+  "<number>.satadisk" will be created in model-scripts/rdinfra/ folder.
+  Use this disk image for booting the installed distribution.
+
+
+Additional distribution specific instructions (if any)
+******************************************************
+
+- Debian Distribution installation:
+
+  - During installation, the installer will prompt the user with the message
+    'Load CD-ROM drivers from removable media' and display two options - Yes/No.
+    Select the option 'No'. This is followed by another prompt 'Manually select 
+    a CD-ROM module and device?' and displays two options - Yes/No. Select the
+    option 'Yes'. This brings up the module list required for accessing CD-ROM
+    and lists two options - 'none' and 'cdrom'. Select the option 'none' and
+    enter ``/dev/vda``. The installation media on the virtio disk will be
+    detected and installation continues.
+
+
+Booting a linux distribution
+----------------------------
+
+To boot the installed distro, use the following commands:
+
+- Set ``MODEL`` path before launching the model:
+
+  ::
+
+    export MODEL=<absolute path to the platform FVP binary>
+
+- If platform is SGI-575:
+
+  ::
+
+    cd model-scripts/sgi
+
+- If platform is an RD:
+
+  ::
+
+    cd model-scripts/rdinfra
+
+- Start the distro boot:
+
+  ::
+
+    ./distro.sh -p <platform> -d <satadisk_path> -a <additional_params> -n [true|false]
+
+Supported command line options are listed below
+
+*  -p <platform>
+
+   - Supported platforms are listed in `Platform Names`_.
+
+*  -d <satadisk_path>
+
+   -  Absolute path to the installed distro disk image created using the
+      instructions listed in the previous section.
+
+*  -n [true|false] (optional)
+
+   -  Controls the use of network ports by the model. If network ports have
+      to be enabled, use 'true' as the option. Default value is set to
+      'false'.
+
+*  -a <additional_params>
+
+   -  Specify any additional model parameters to be passed. The model
+      parameters and the data to be passed to those parameters can be found
+      in the FVP documentation.
+
+Example commands to boot a linux distribution are listed below.
+
+- Command to look for the available .satadisk image in the
+  ``model-scripts/rdinfra`` folder and boots with that image. If multiple
+  ``.satadisk`` images are found, it will list them all but won't boot:
+
+  ::
+
+    ./distro.sh -p rddaniel
+
+
+- Command to begin the distro boot from the ``fedora.satadisk`` image:
+
+  ::
+
+    ./distro.sh -p rddaniel -d /absolute/path/to/fedora.satadisk
+
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
+
+.. _Download sources: docs/infra/common/download-sources.rst