Commit 7a305dc0 authored by shriram-k-arm's avatar shriram-k-arm Committed by Vijayenthiran Subramaniam
Browse files

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-arm's avatarShriram K <shriram.k@arm.com>
Change-Id: Ie89140985a877cc616f3e54d8b6c36d976249274
parent 16cd7992
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
Markdown is supported
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