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 SGI/RD platform.
Signed-off-by: Vijayenthiran Subramaniam <vijayenthiran.subramaniam@arm.com>
Change-Id: I4867e55b289ddfc450c995d69f8badc9597a1001

docs/infra/common/distro-boot.rst

+How to install and boot a linux distribution
+============================================
+
+.. contents::
+
+
+Linux distribution boot support
+--------------------------------
+
+SGI/RD platform software stack supports the installation and boot of various
+linux distributions such as Debian, Ubuntu, Fedora or Redhat. The distribution
+is installed on a SATA disk and the installed image can be used for multiple
+boots.
+
+
+Platform Names
+--------------
+
+Arm's Infra reference platforms are assigned names in order to allow the build
+and execute scripts to recognize the platform that has to be buit 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                    |
++--------------------------+-------------------------+
+
+
+Sync the required platform software
+-----------------------------------
+
+To obtain the required sources for the platform, follow the steps listed on the
+`Obtaining the platform software`_ 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.
+
+
+Procedure to build SGI/RD software stack for distro boot
+--------------------------------------------------------
+
+The SGI/RD platform software stack has to be first built to prepare for the
+distribution installation step. The procedure to build the platform software
+stack is listed below.
+
+To build the SGI/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 single chip RD-N2 software stack
+  needed for the distro installation/boot test for the platform:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rdn2 all
+
+- Command to remove the generated outputs (binaries) of the software stack for
+  the chip 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
+
+
+Procedure for installing a distro on SGI/RD platform
+----------------------------------------------------
+
+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 location (select arm64 image):
+
+- `Fedora <https://alt.fedoraproject.org/alt>`_
+- `Ubuntu <https://ubuntu.com/download/server/arm>`_
+- `Debian <https://www.debian.org/distrib/netinst>`_
+
+The command used to begin the distro installation is:
+
+- 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 iso 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 the command to begin the boot of 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 distro.
+
+- 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.
+  User should use this disk image when booting the Debian 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' which would again display two options
+      - Yes/No.
+    
+    - Select the option 'Yes' which will display 'Automatic detection did not
+      find CD-ROM'.
+    
+    - Module needed for accessing CD-ROM and display two options:
+      - none
+      - cdrom
+    
+    - Select the option 'none' and enter ``/dev/vda``. The installation media on
+      the virtio disk will be detected and installation continues.
+
+
+Procedure for booting distro on SGI/RD platform
+-----------------------------------------------
+
+To boot the installed distro, use the following command:
+
+- 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
+
+- Begin 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 command  functionality are as 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
+
+
+This completes the validation of the linux distribution installation and boot
+functionalities.
+
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
+
+
+.. _Obtaining the platform software:
+   docs/infra/common/obtain-platform-software-stack.rst