Merge pull request #1688 from annietllnd/shrinkwrap

Update Void Linux on FVP LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/glibc-linux-fvp/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Glibc + Linux + FVP
+title: Build and test a custom Linux image on an FVP
 
 draft: true
 cascade:
@@ -8,32 +8,24 @@ cascade:
 minutes_to_complete: 60
 
 who_is_this_for: >
-  Developers who wish to run a Linux system (optionally using a custom kernel and
-  a C library) on an Arm Fixed Virtual Platform (FVP) model. For example, this
-  guide might be useful if you want to test patches for the Linux kernel or Glibc.
+  This is an advanced topic for developers who wish to run a Linux system (optionally using a custom kernel and
+  a C library) on an Arm Fixed Virtual Platform (FVP) model. This learning path might be useful to follow if you want to test patches for the Linux kernel or Glibc prior to having hardware available.
 
-learning_objectives: 
+learning_objectives:
   - Build the Linux kernel.
   - Install the Shrinkwrap tool, build firmware for the FVP and run it.
   - Configure and boot a Linux system on the FVP.
-  - Configure guest OS to make running Glibc tests easier.
+  - Configure guest OS and run Glibc tests.
   - Build Glibc and run tests on the system running on the FVP.
 
 prerequisites:
-  - An AArch64 or x86 host running a Linux system.
-  - GCC cross toolchain for the `aarch64-none-linux-gnu` target.
-  - Docker.
-  - Git to checkout sources.
-  - Make to build the tools.
-  - Bash for your shell.
-  - Python 3.x and `pip` to create a Python virtual environment.
-  - Common tools like `wget`, `unxz`, `truncate`.
+  - An AArch64 or x86_64 Linux machine. The instructions in this Learning Path have been tested on AArch64 Linux machine running Ubuntu 24.04.
 
 author: Yury Khrustalev
 
 ### Tags
 skilllevels: Advanced
-subjects: Architecture Enablement
+subjects: Performance and Architecture
 armips:
     - AArch64
 tools_software_languages:

content/learning-paths/servers-and-cloud-computing/glibc-linux-fvp/conventions.md

@@ -1,44 +1,49 @@
 ---
-title: Conventions
+title: Development environment
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-For a few things you may need root access on your host system to do minimal setup and
-install packages that are described in the following sections.
+In this section, you will install packages and review the directory structure used throughout the learning path.
 
-## Naming conventions
+## Install dependencies
 
-In the following sections we use host system to checkout sources and build various
-tools and we also make configuration changes to the guest system that will run on
-the Arm [Fixed Virtual Platform (FVP)][1] model.
+Run the following commands to make sure the necessary dependencies are installed on your host machine:
 
-Before we begin, it's important to describe the specifics of our setup making it easier
-to write commands and code examples. Wherever possible we use generic commands and code
-examples but in certain places we have to use hardcoded values and absolute paths.
+```bash
+sudo apt update && sudo apt install -y \
+    git make bash \
+    flex bison build-essential libssl-dev bc libelf-dev libncurses-dev \
+    python3 python3-pip python-is-python3 python3-venv wget xz-utils coreutils
+```
 
-Table 1. Directory layout
+Install GCC to cross compile Linux applications:
+```bash
+sudo apt install gcc-aarch64-linux-gnu -y
+```
+
+{{% notice Note%}}
+The GCC cross toolchain installation directory contains everything a cross toolchain would need, for example, the path to the `gcc` tool would be `/usr/bin/aarch64-linux-gnu-gcc`. 
+{{% /notice %}}
 
-| Path                                 | Description                                |
-|--------------------------------------|--------------------------------------------|
-| `/path/to/cross/gcc`                 | GCC cross toolchain installation directory |
-| `/home/user`                         | Home directory of your host non-root user  |
-| `/home/user/workspace`               | Workspace directory                        |
-| `/home/user/workspace/linux`         | Folder with the Linux kernel sources       |
-| `/home/user/workspace/linux-headers` | Directory for installing kernel headers    |
-| `/home/user/workspace/linux-build`   | Folder for the Linux kernel build output   |
-| `/home/user/workspace/glibc`         | Folder for the Glibc sources               |
-| `/home/user/workspace/glibc-build`   | Directory for the Glibc build output       |
+Install Docker, refer to the [Docker install guide](/install-guides/docker/).
 
 
+## Directory Structure
 
-We presume that the GCC cross toolchain installation directory contains everything a
-cross toolchain would need, for example, the path to the `gcc` tool would be
-`/path/to/cross/gcc/bin/aarch64-none-linux-gnu-gcc`.
+In the following sections you will checkout sources and build various tools on your Linux host machine. Before you begin, lets look at the directory structure of where you will build the different parts of software stack needed to run this learning path.
+
+Table 1. Directory layout
 
-In the next steps we create a Python virtual environment. It doesn't matter where
-it is located, but to avoid ambiguity let's presume it is in `~/workspace/venv`.
+| Path                                 | Description                           |
+|--------------------------------------|---------------------------------------|
+| `$HOME`                         | Home directory of your host non-root user  |
+| `$HOME/workspace`               | Workspace directory                        |
+| `$HOME/workspace/linux`         | Folder with the Linux kernel sources       |
+| `$HOME/workspace/linux-headers` | Directory for installing kernel headers    |
+| `$HOME/workspace/linux-build`   | Folder for the Linux kernel build output   |
+| `$HOME/workspace/glibc`         | Folder for the Glibc sources               |
+| `$HOME/workspace/glibc-build`   | Directory for the Glibc build output       |
 
-[1]: https://developer.arm.com/downloads/-/arm-ecosystem-fvps

content/learning-paths/servers-and-cloud-computing/glibc-linux-fvp/fvp.md

@@ -1,5 +1,5 @@
 ---
-title: Boot Linux on FVP
+title: Boot Linux on the FVP
 weight: 5
 
 ### FIXED, DO NOT MODIFY
@@ -8,30 +8,29 @@ layout: learningpathall
 
 ## Introduction
 
-During this step, we set up everything for the FVP to run and then boot the Linux system
-using the kernel and the root file system that we prepared earlier.
+During this step, you will set up everything for the FVP to run and then boot the Linux system
+using the kernel and the root file system that you prepared earlier in the earlier sections.
 
-Arm [Fixed Virtual Platform (FVP)][1] is a model that allows you to access functionality
-of Armv8.x or v9.x hardware. We use the Armv-A Base Rev C Architecture Envelope Model (AEM).
+Arm [Fixed Virtual Platform (FVP)](https://developer.arm.com/downloads/-/arm-ecosystem-fvps) is a model that allows you to access functionality
+of Armv8.x or v9.x hardware. You will use the Armv-A Base Rev C Architecture Envelope Model (AEM).
 
 In addition to the model itself, you also need the device tree and the firmware. To simplify
-building these components, we use a tool called [Shrinkwrap][2].
+building these components, you will use a tool called [Shrinkwrap](https://gitlab.arm.com/tooling/shrinkwrap).
 
-This tool comes with a detailed [user guide][3] that covers all of its features and
-configuration options. Here, we provide a short quick-start guide.
+This tool comes with a detailed [user guide](https://shrinkwrap.docs.arm.com/en/latest/) that covers all of its features and
+configuration options. You will also leverage this tool to run and boot the images you prepared on the FVP.
 
-We also rely on a Docker container to facilitate the building of the firmware and
+Shrinkwrap can be used in a few different ways. One of the ways is to use a Docker container to facilitate the building of the firmware and
 running the FVP. This helps avoid installing all the dependencies on your host system.
-Shrinkwrap can be used without Docker but it requires extra steps to ensure that all
-dependencies are of the right version and are installed correctly.
 
 ## Install Shrinkwrap
 
-First, we install prerequisites in a Python virtual environment using Python 3.x:
+First, install prerequisites in a Python virtual environment using Python 3.x:
 
 ```bash
-python -m venv ~/workspace/venv
-source ~/workspace/venv/bin/activate
+cd $HOME
+python -m venv $HOME/workspace/venv
+source $HOME/workspace/venv/bin/activate
 pip install -U pip setuptools wheel
 pip install pyyaml termcolor tuxmake
 ```
@@ -41,7 +40,7 @@ repository. Run this command in the workspace directory:
 
 ```bash
 git clone https://git.gitlab.arm.com/tooling/shrinkwrap.git
-export PATH=${PATH}:$(pwd)/shrinkwrap/shrinkwrap
+export PATH=${PATH}:${HOME}/workspace/shrinkwrap/shrinkwrap
 ```
 
 Putting Shrinkwrap's main executable on your `PATH` is all you need to install the tool.
@@ -52,12 +51,15 @@ is activated, then run this command:
 shrinkwrap --version
 ```
 
-## Build firmware for FVP
+You should see a version printed.
 
-Before proceeding, ensure that Docker is installed and usable. Follow the installation
-instructions for your distro [here][4].
+```output
+shrinkwrap v1.0.0
+```
+
+## Build firmware for the FVP
 
-Now, we use the Shrinkwrap tool to build the firmware, the third essential ingredient in our
+Now, you can use the Shrinkwrap tool to build the firmware, the third essential ingredient in our
 setup. The following step needs to be done once although you will need to repeat it if you
 want to rebuild the firmware:
 
@@ -78,17 +80,17 @@ the components including the device tree for the FVP.
 At this point, we have everything required to boot our system. Shrinkwrap uses so called overlay
 configuration files. The following file instructs Shrinkwrap to connect all the pieces together
 and locate the kernel image, and rootfs. It can also be used to tweak any of the FVP
-parameters. Save this file as `~/workspace/aarch64.yaml`:
+parameters. Create a file in $HOME/workspace directory called `aarch64.yaml` using a text editor of your choice. Copy the contents shown below into the file:
 
 ```yaml
 run:
   rtvars:
     ROOTFS:
-      value: /home/user/workspace/rootfs.img
+      value: ~/workspace/rootfs.img
     CMDLINE:
       value: ip=dhcp kpti=off root=/dev/vda2 console=ttyAMA0
     KERNEL:
-      value: /home/user/workspace/linux-build/arch/arm64/boot/Image
+      value: ~/workspace/linux-build/arch/arm64/boot/Image
   params:
     -C bp.hostbridge.userNetworking: 1
     -C bp.hostbridge.userNetPorts: 8022=22,8123=8123
@@ -108,15 +110,15 @@ The most important parts in this configuration file are:
    You can add more ports as needed.
 
 The FVP has many parameters that can be tweaked in this config by adding a `-C param: value`
-line to the `params` section. Refer to the [Fast Models Fixed Virtual Platforms Reference Guide][5]
+line to the `params` section. Refer to the [Fast Models Fixed Virtual Platforms Reference Guide](https://developer.arm.com/documentation/100966/latest/Getting-Started-with-Fixed-Virtual-Platforms/Configuring-the-model).
 for more details.
 
 ## Run FVP with Shrinkwrap
 
 To run the FVP using Docker, execute the following command:
 
 ```bash
-shrinkwrap run ns-edk2.yaml --overlay ~/workspace/aarch64.yaml
+shrinkwrap run ns-edk2.yaml --overlay $HOME/workspace/aarch64.yaml
 ```
 
 At first, Shrinkwrap starts a Docker container and runs the FVP in it. At the beginning
@@ -156,9 +158,6 @@ uname -a
 cat /proc/cpuinfo
 ```
 
-We will do more setup during the next step. This additional setup is optional but it
-helps prepare our guest system for running Glibc tests and doing other complex tasks.
-
 ## Powering down
 
 You can always press `Ctrl+]` to stop Shrinkwrap in the terminal where Shrinkwrap is
@@ -171,8 +170,6 @@ from the root console of your guest system, for example:
 ssh [email protected] -p 8022 poweroff
 ```
 
-[1]: https://developer.arm.com/downloads/-/arm-ecosystem-fvps
-[2]: https://gitlab.arm.com/tooling/shrinkwrap
-[3]: https://shrinkwrap.docs.arm.com/en/latest/
-[4]: https://docs.docker.com/engine/install/
-[5]: https://developer.arm.com/documentation/100966/latest/Getting-Started-with-Fixed-Virtual-Platforms/Configuring-the-model
+Continue to the next section for additional setup. The remaining steps are optional but it
+helps prepare our guest system for running Glibc tests and doing other complex tasks.
+