infra/common: document linuxboot procedure

Add a new document that explains the procedure to build software stack
and boot to busybox using linuxboot on the Neoverse reference design
platforms.
Signed-off-by: Shriram K <shriram.k@arm.com>
Change-Id: Ie89140985a877cc616f3e54d8b6c36d976249274

docs/infra/common/linuxboot.rst

+Linuxboot on Neoverse RD platforms
+=====================================
+
+.. contents::
+
+
+Overview of Linuxboot
+------------------------
+
+Linuxboot is a firmware for modern servers that replaces specific firmware
+functionality like the UEFI DXE phase with a Linux kernel and runtime. Refer the
+`Linuxboot Book`_ for more details.
+
+Linuxboot support on Neoverse Reference Design (RD) platform software stack
+demonstrates the integration of various software compontents on the software
+stack resulting in the ability to boot linux kernel using linuxboot on RD fixed
+virtual platform (FVP).
+
+This document describes how to build the Neoverse RD platform software stack and
+and use it to boot linuxboot on the Neoverse RD FVP.
+
+Please note that this is just an initial implementation of linuxboot as a
+prototype on RD platforms. Hence this implementation does not remove the UEFI
+DXE phase entirely. Instead a minimal set of DXEs are used to boot the linuxboot
+kernel as a UEFI application from the UEFI Boot Manager menu by replacing the
+UEFI shell. The following diagram describes the boot flow of the prototpe
+linuxboot implementation on Reference Design(RD) platforms.
+
+::
+
+  +------------------------+
+  |                        |
+  |    Trusted Firmware    |
+  |                        |
+  +-----------+------------+
+              |
+              |
+              v                                                +------------------------+              +----------------------+
+  +------------------------+                                   |                        |              |                      |
+  |                        |       launch stage-1 kernel       |  Stage-1 Linux Kernel  |  kexec call  |  Final Linux Kernel  |
+  | Minimal UEFI DXE phase +---------------------------------->|          +             +------------->|          +           |
+  |                        |     as UEFI shell application     |        u-root          |              |       busybox        |
+  +------------------------+                                   |                        |              |                      |
+                                                               +------------------------+              +----------------------+
+
+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 disk image for linuxboot.
+The disk image consists of stage-2 linux kernel image and busybox ramdisk.
+Examples on how to use the build command for linuxboot are listed below.
+
+To build the software stack, the command to be used is
+
+::
+
+  ./build-scripts/rdinfra/build-test-linuxboot.sh -p <platform name> <command>
+
+Supported command line options are listed below
+
+* <platform name>
+
+  - Lookup for a platform name in `Platform Names`_.
+
+* <command>
+
+  - Supported commands are
+
+    - ``clean``
+    - ``build``
+    - ``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
+
+- Command to clean, build and package the RD-N2 software stack required for
+  linuxboot on RD-N2 platform:
+
+  ::
+
+    ./build-scripts/rdinfra/build-test-linuxboot.sh -p rdn2 all
+
+- Command to perform an incremental build of the software components included in
+  the software stack for the RD-N2 platform.
+
+  *Note:* this command should be followed by the ``package`` command to complete
+  the preparation of the FIP and the disk image.
+
+  ::
+
+    ./build-scripts/rdinfra/build-test-linuxboot.sh -p rdn2 build
+
+- Command to package the previously built software stack and prepare the FIP and
+  the disk image.
+
+  ::
+
+    ./build-scripts/rdinfra/build-test-linxuboot.sh -p rdn2 package
+
+
+Boot linuxboot
+-----------------
+
+After the build of the platform software stack for linuxboot is complete, the
+following commands can be used to start the execution of the *selected platform
+fastmodel* and boot the platform up to the u-root prompt.
+
+NOTE: This prototype implementation uses a minimal set of UEFI DXEs to boot the
+linuxboot kernel and does not replace the UEFI DXE phase entirely.
+
+Examples on how to use the command are listed below.
+
+To boot up to the u-root prompt using linuxboot, the commands to be used are
+
+- Set ``MODEL`` path before launching the model:
+
+  ::
+
+    export MODEL=<absolute path to the platform FVP binary>
+
+- Navigate to model-scripts:
+
+  ::
+
+    cd model-scripts/rdinfra
+
+- Launch linuxboot:
+
+  ::
+
+    ./linuxboot.sh -p <platform name> -a <additional_params>
+
+
+Supported command line options are listed below
+
+*  -p <platform name>
+
+   - Lookup for a platform name in `Platform Names`_.
+
+*  -a <additional_params> (optional)
+
+   - 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 linuxboot are as listed below.
+
+- Command to start the execution of the RD-N2 model to boot linuxboot:
+
+  ::
+
+    ./linuxboot.sh -p rdn2
+
+- Command to start the execution of the RD-N2 model to boot linuxboot.
+  Additional parameters to the model are supplied using the ``-a`` command
+  line parameter:
+
+  ::
+
+    ./linuxboot.sh -p rdn2 -a "-C board.flash0.diagnostics=1"
+
+
+There are additional steps to be performed in order to boot the stage-1
+linuxboot kernel with u-root prompt. These steps are listed below:
+
+- Once the FVP model starts executing, wait till the prompt "Press ESCAPE for
+  boot options" on the *FVP terminal_s0*
+
+.. image:: images/linuxboot-image-1.png
+
+- Here, press Esc key to enter the UEFI menu. Enter the Boot Manager Menu by
+  selecting it using the arrow keys followed by pressing the Enter key.
+
+.. image:: images/linuxboot-image-2.png
+
+- In the Boot Manager Menu, select the UEFI shell. This will boot the stage-1
+  linux kernel with u-root prompt followed by stage-2 linux kernel with busybox.
+
+.. image:: images/linuxboot-image-3.png
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
+
+.. _Download sources: docs/infra/common/download-sources.rst
+.. _Platform Names: docs/infra/common/platform_names.rst
+.. _troubleshooting guide: docs/infra/common/troubleshooting-guide.rst
+.. _Linuxboot Book: https://github.com/linuxboot/book