Commit 23d72504 authored by Vivek Kumar Gautam's avatar Vivek Kumar Gautam Committed by Thomas Abraham
Browse files

infra/common: document buildroot boot procedure



Add a new document that explains the procedure to boot buildroot target
filesystem distributions on the Neoverse reference design platforms.

Change-Id: I6f8d59cfb1ab3db140e2877b7bb36129c8dfce8b
Signed-off-by: Vivek Kumar Gautam's avatarVivek Gautam <vivek.gautam@arm.com>
parent 7a182f6e
Buildroot boot on Neoverse RD platforms
=======================================
.. contents::
What is Buildroot?
------------------
Buildroot is a simple, efficient and easy-to-use tool to generate a complete
Linux systems through cross-compilation. In order to achieve this, buildroot
is able to generate a cross-compilation toolchain, a root filesystem, a
Linux kernel image and a bootloader for a target and can be used for any
combination, independently, one can for example use an existing cross-
compilation toolchain, and build only the root filesystem with buildroot.
Buildroot supports numerous processors and their variants from various families
such as, PowerPC, MIPS, and ARM processors, etc. It comes with default
configurations for several boards available off-the-shelf.
Online documentation for buildroot can be found `here
<https://buildroot.org/docs.html>`_.
Overview of Buildroot Boot
--------------------------
Buildroot boot on Neoverse Reference Design platforms allows the use of
buildroot as the filesystem and boot the software stack on the fast model.
This document describes the procedure to build and execute the software
stack with buildroot as the root filesystem.
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-V1 | rdv1 |
+--------------------------+-------------------------+
| RD-V1-MC | rdv1mc |
+--------------------------+-------------------------+
| RD-N2 | rdn2 |
+--------------------------+-------------------------+
Sync the required 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 buildroot boot.
The disk image consists of two partitions. The first partition is a EFI
partition and contains grub. The second parition is a ext3 partition and
contains the linux kernel image. Examples on how to use the build command for
buildroot boot are listed below.
To build the software stack, the command to be used is
::
./build-scripts/rdinfra/build-test-buildroot.sh -p <platform> <command>
Supported command line options are listed below
* <platform>
- Supported platforms are listed in `Platform Names`_.
* <command>
- Supported commands are
- ``clean``
- ``build``
- ``package``
- ``all`` (all of the three above)
Examples of the build command are
- Command to clean, build and package the software stack needed for the
buildroot boot on RD-N2 platform:
::
./build-scripts/rdinfra/build-test-buildroot.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-buildroot.sh -p rdn2 build
- Command to package the previously built software stack and prepares the FIP
and the disk image.
::
./build-scripts/rdinfra/build-test-buildroot.sh -p rdn2 package
Modifying buildroot target filesystem (optional)
------------------------------------------------
Buildroot supports a number of pre-configured packages, customizations across
various components, supports a number of pre-configured packages, and also
allows adding or modifying files on the target filesystem. This provides the
ability to create a richer filesystem compared to busybox.
Though not recommended, for temporary modifications, it is possible to modify
the buildroot target filesystem directly and rebuild the image. The target file-
system is available under out/arm64/target/ directory in buildroot source. After
making required changes, build the software stack again to rebuild the target
filesystem image. Note: if the buildroot repo is cleaned, these changes will be
lost.
After the changes are made, run the build command for buildroot and package it.
Examples of the incremental build command are
- Command to perform an incremental build of the buildroot component included
in the software stack for the RD-N2 platform.
::
./build-scripts/build-buildroot.sh -p rdn2 build
- Command to package the previously built software stack and prepares the FIP
and the disk image.
::
./build-scripts/rdinfra/build-test-buildroot.sh -p rdn2 package
Booting with Buildroot as the filesystem
----------------------------------------
After the build of the platform software stack for buildroot boot is complete,
the following command starts the execution of the *selected platform fastmodel*
and the software boots up to the buildroot prompt. Examples on how to use the
command are listed below.
To boot up to the buildroot prompt, the command to be used is
- 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
- Launch buildroot boot:
::
./boot-buildroot.sh -p <platform> -a <additional_params> -n [true|false]
Supported command line options are listed below
* -p <platform>
- Supported platforms are listed in `Platform Names`_.
* -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> (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 with buildroot as the filesystem are as listed below.
- Command to start the execution of the RD-N2 model to boot up to the
buildroot prompt:
::
./boot-buildroot.sh -p rdn2
- Command to start the execution of the RD-N2 model to boot up to the
buildroot prompt with network enabled. The model supports virtio.net
allowing the software running within the model to access the network:
::
./boot-buildroot.sh -p rdn2 -n true
- Command to start the execution of the RD-N2 model with networking
enabled and to boot up to the buildroot prompt. Additional parameters
to the model are supplied using the ``-a`` command line parameter:
::
./boot-buildroot.sh -p rdn2 -n true -a "-C board.flash0.diagnostics=1"
--------------
*Copyright (c) 2021, Arm Limited. All rights reserved.*
.. _Download sources: docs/infra/common/download-sources.rst
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