Merge pull request #2072 from madeline-underwood/Run-and-debug

Run and debug FVP linux [JA to review]

Author: jasonrandrews

content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/_index.md

@@ -1,24 +1,20 @@
 ---
-title: Run and Debug a Linux Software Stack on Arm Virtual Platforms
+title: Debug Trusted Firmware-A and the Linux kernel on Arm FVP with Arm Development Studio 
 
-minutes_to_complete: 180
+minutes_to_complete: 60
 
-who_is_this_for: This introductory topic is designed for developers interested in running Linux on Arm Fixed Virtual Platforms (FVPs) and debugging Trusted Firmware-A and the Linux Kernel using Arm Development Studio.
+who_is_this_for: This topic is for developers who want to run Linux on Arm Fixed Virtual Platforms (FVPs) and debug both Trusted Firmware-A and the Linux kernel using Arm Development Studio.
 
 learning_objectives:
-    - Run a Linux software stack using Arm Fixed Virtual Platforms.
-    - Debug the firmware and Linux kernel using Arm Development Studio.
-
+    - Boot and run a Linux software stack on an Arm Fixed Virtual Platform (FVP).
+    - Debug Trusted Firmware-A and the Linux kernel using Arm Development Studio.
 prerequisites:
-    - A Linux computer with Arm Development Studio installed (works only on x86-64).
-    - Basic knowledge of Assembly and C language.
+    - A Linux-based x86-64 host computer with Arm Development Studio installed.
+    - Basic understanding of Assembly and C programming.
+   
 
 author: Qixiang Xu
 
-draft: true
-cascade:
-    draft: true
-
 ### Tags
 skilllevels: Introductory
 subjects: Embedded Linux

content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/_next-steps.md

@@ -3,6 +3,6 @@
 #       FIXED, DO NOT MODIFY THIS FILE
 # ================================================================================
 weight: 21                  # Set to always be larger than the content in this path to be at the end of the navigation.
-title: "Next Steps"         # Always the same, html page title.
+title: "Next steps"         # Always the same, html page title.
 layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
 ---

content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/debug.md

@@ -1,20 +1,20 @@
 ---
-title: Debug Software Stack
+title: Debug the software stack
 weight: 6
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Debug the Software Stack with Arm Development Studio
+## Debug the software stack with Arm Development Studio
 
 Once your software stack is running on the FVP, you can debug Trusted Firmware-A and the Linux kernel using Arm Development Studio (Arm DS).
 
-### Step 1: Install Arm Development Studio
+## Install Arm Development Studio
 
 Download and install the latest version from the [Arm Development Studio download page](https://developer.arm.com/downloads/view/DS000B).
 
-DWARF 5 is enabled by default in GCC 11 and later. Arm DS v2022.2 or newer is recommended to support DWARF 5 debug information.
+DWARF 5 is enabled by default in GCC 11 and later. Arm DS v2022.2 or later is recommended to support DWARF 5 debug information.
 
 
 
@@ -24,11 +24,14 @@ Launch Arm DS:
 ```
 
 
-### Step 2: Create a Debug Configuration
-1.	Open Arm DS, go to Run > Debug Configurations.
-2.	Select Generic Arm C/C++ Application and create a new configuration.
-3.	In the Connection tab:
-    - Choose your FVP model (e.g., Base_A55x4).
+## Create a debug configuration
+
+To create a debug configuration, follow these steps:
+
+1.	Open Arm DS, go to **Run** > **Debug Configurations**.
+2.	Select **Generic Arm C/C++ Application** and create a new configuration.
+3.	In the **Connection** tab:
+    - Choose your FVP model (for example, Base_A55x4)
     - Enter model parameters:
 
 ```output
@@ -50,29 +53,29 @@ Launch Arm DS:
 --data cluster0.cpu0=<SRC_PATH>/output/aemfvp-a/aemfvp-a/fvp-base-revc.dtb@0x83000000
 ```
 
-### Step 3: Load Debug Symbols
+## Load debug symbols
 
-In the Debugger tab:
-- Select “Connect only to the target.”
-- Enable Execute debugger commands and add:
+In the **Debugger** tab:
+- Select **Connect only to the target**.
+- Enable Execute debugger commands, and add:
 ```output
 add-symbol-file "~/arm/sw/cpufvp-a/arm-tf/build/fvp/debug/bl1/bl1.elf" EL3:0
 add-symbol-file "~/arm/sw/cpufvp-a/arm-tf/build/fvp/debug/bl2/bl2.elf" EL1S:0
 add-symbol-file "~/arm/sw/cpufvp-a/arm-tf/build/fvp/debug/bl31/bl31.elf" EL3:0
 add-symbol-file "~/arm/sw/cpufvp-a/linux/out/aemfvp-a/defconfig/vmlinux" EL2N:0
 ```
 
-Click Apply and then Close.
+Select **Apply** and then **Close**.
 
-### Step 4: Start Debugging
+## Start debugging
 
-1.	In the Debug Control view, double-click your new configuration.
-2.	Wait for the target to connect and symbols to load.
+1.	In the **Debug Control** view, double-click your new configuration.
+2.	Wait for the target to connect and the symbols to load.
 3.	Set breakpoints, step through code, and inspect registers or memory.
 
-You might get the following error when starting the debug connection.
+You might get the following error when starting the debug connection:
 
-![Connection Failed Screen #center](failed.png)
+![Connection Failed Screen #center](failed.png "Connection Failed error message")
 
 This means your Arm FVP is not provided by default in the Arm DS installation. Set the `PATH` in this case:
 
@@ -86,4 +89,4 @@ Ensure your FVP instance is running and matches the model and parameters selecte
 
 After these steps, you can debug the software stack as shown in the following figure:
 
-![FVP running #center](Select_target.png)
+![FVP running #center](Select_target.png "Debug interface in GUI")

content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/intro.md

@@ -6,41 +6,60 @@ weight: 2
 layout: learningpathall
 ---
 
-Arm Fixed Virtual Platforms (FVPs) are simulation models that let you run and test full software stacks on Arm systems before physical hardware is available. They replicate the behavior of Arm CPUs, memory, and peripherals using fast binary translation.
+## What are Arm Fixed Virtual Platforms (FVPs)?
 
-### Why Use FVPs?
-FVPs are useful for developers who want to:
-- Prototype software before silicon availability
-- Debug firmware and kernel issues
-- Simulate multicore systems
+Arm Fixed Virtual Platforms (FVPs) are fast, functional simulation models of Arm hardware. They give you the ability to develop, test, and debug full software stacks. This includes firmware, bootloaders, and operating systems - all without the need for access to physical Arm silicon. FVPs replicate Arm CPU behavior, memory, and peripherals using fast binary translation.
 
-FVPs provide a programmer's view of the hardware, making them ideal for system bring-up, kernel porting, and low-level debugging.
+## Why use FVPs?
+FVPs are ideal for early software development and system debugging. 
 
-### Freely Available Arm Ecosystem FVPs
-Several pre-built Armv8-A FVPs can be downloaded for free from the [Arm Ecosystem Models](https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms#Downloads) page. Categories include:
+Developers can use FVPs to do the following tasks:
+
+- Prototype firmware and OS code before silicon is available
+- Debug complex boot sequences and kernel issues
+- Simulate multi-core systems to analyze performance and thread scheduling
+
+FVPs provide a programmer's view of the hardware, making them ideal for the following:
+
+* System bring-up
+* Kernel porting
+* Low-level debug tasks
+
+## How can I get access to the Arm FVPs?
+
+You can download prebuilt Armv8-A FVPs at no cost from the [Arm Ecosystem Models](https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms#Downloads) page. 
+
+Available categories include:
 - Architecture
 - Automotive
 - Infrastructure
 - IoT
 
-A popular model is the **AEMv8-A Base Platform RevC**, which supports Armv8.7 and Armv9-A. The [Arm reference software stack](https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-docs/-/blob/master/docs/aemfvp-a/user-guide.rst) is designed for this model.
+A popular model is AEMv8-A Base Platform RevC, which simulates generic Armv8.7-A and Armv9-A CPUs and is fully supported by Arm's open-source [reference software stack](https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-docs/-/blob/master/docs/aemfvp-a/user-guide.rst).
 
-### CPU-Specific Arm Base FVPs
-Other FVPs target specific CPU types and come pre-configured with a fixed number of cores. These are often called **CPU FVPs**.
+## CPU-specific Arm-based FVPs
+Some FVPs target specific CPU implementations and include fixed core counts. These are known as CPU FVPs.
 
-Here are some examples:
+Examples include:
 - FVP_Base_Cortex-A55x4
 - FVP_Base_Cortex-A72x4
 - FVP_Base_Cortex-A78x4
 - FVP_Base_Cortex-A510x4+Cortex-A710x4
 
 To use these, request access via [[email protected]](mailto:[email protected]).
 
-### Setting Up Your Environment
-This Learning Path uses the [Arm reference software stack](https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-docs/-/blob/master/docs/aemfvp-a/user-guide.rst).
+## Set up your environment
+This Learning Path uses the open-source Arm reference software stack, which includes the following:
+
+* Prebuilt Linux images
+* Firmware
+* Configuration files
 
 To get started:
-1. Follow the software user guide to download the stack.
-2. Set up the required toolchain and environment variables.
 
-Once configured, you’ll be ready to run and debug Linux on your selected Arm FVP model.
+* Follow the [software user guide](https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-docs/-/blob/master/docs/aemfvp-a/user-guide.rst) to download the stack.
+* Set up your toolchain
+* Export environment variables
+* Verify your build dependencies
+
+Once setup is complete, you’ll be ready to boot and debug Linux on your selected Arm FVP model.

content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/modify.md

@@ -1,39 +1,45 @@
 ---
-title: Modify device tree for Linux
+title: Modify the device tree for CPU FVPs
 weight: 4
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Modify the Device Tree for CPU FVPs
+## Ensure the device tree matches your FVP model
 
-To run Linux on Arm CPU FVPs, you need to adjust the device tree to match the hardware features of these platforms. This involves removing unsupported nodes (like SMMU (System Memory Management Unit)and PCI (Peripheral Component Interconnect)) and ensuring CPU affinity values are set correctly.
+To run Linux on Arm CPU FVPs, you need to adjust the device tree to match the hardware features of these platforms. This involves removing unsupported nodes, such as the System Memory Management Unit (SMMU) and Peripheral Component Interconnect (PCI), and ensuring that the CPU affinity values are set correctly.
 
-### Step 1: Remove PCI and SMMU Nodes
+### Remove PCI and SMMU nodes
 
-CPU FVPs don't support PCI and SMMU. If you don't remove these nodes, Linux will crash at boot with a kernel panic.
+CPU FVPs don't support PCI or SMMU. If you leave these nodes in the device tree, Linux will crash at boot with a kernel panic.
+
+So to workaround this, you need to remove PCI and SMMU nodes:
+
+Open the device tree file in a text editor:
 
-1. Open the device tree file in a text editor:
 ```bash
 vim linux/arch/arm64/boot/dts/arm/fvp-base-revc.dts
 ```
-2.	Delete the following two blocks:
+Remove the following nodes:
+
 - `pci@40000000`
 - `iommu@2b400000`
 
-{{% notice warning %}}
-If you skip this, you’ll get an error like:
+{{% notice Warning %}}
+If you skip this step, you might encounter an error like:
 
 ```output
 Kernel panic - not syncing: Attempted to kill init! exitcode=0x0000000b
 ```
 {{% /notice %}}
 
-### Step 2: Set CPU Affinity Values
+### Set CPU affinity values
+
+Each FVP model uses specific CPU affinity values. If these don’t match the values in the device tree, some of the CPU cores won’t boot.
+
+Find the correct affinities:
 
-Each FVP model uses specific CPU affinity values. If these don’t match what’s in the device tree, some CPU cores won’t boot.
-1.	Find the correct affinities:
 ```bash
 FVP_Base_Cortex-A55x4 -l | grep pctl.CPU-affinities
 ```
@@ -43,19 +49,19 @@ Example output:
 pctl.CPU-affinities=0.0.0.0, 0.0.1.0, 0.0.2.0, 0.0.3.0
 ```
 
-2.	Convert each to hex for the reg field:
+Convert each to hex for the `reg` field:
 
 ```output
 0x0, 0x0100, 0x0200, 0x0300
 ```
 
-3.	Update the CPU nodes in your device tree file to use these reg values.
+Update the CPU nodes in your device tree file to use these `reg` values.
 
-{{% notice tip %}}
-To avoid boot errors like psci: failed to boot CPUx (-22), make sure every cpu@xxx entry matches the FVP layout.
+{{% notice Tip %}}
+To avoid boot errors such as `psci: failed to boot CPUx (-22)`, make sure every `cpu@xxx` entry matches the FVP layout.
 {{% /notice %}}
 
-### Step 3: Rebuild Linux
+### Rebuild Linux
 
 After editing the device tree, rebuild Linux:
 

content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/run.md

@@ -1,24 +1,26 @@
 ---
-title: Run Software Stack
+title: Run the Linux software stack on an FVP
 weight: 5
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
 
-## Run the Linux Software Stack on an FVP
+## Launch the Linux software stack on an FVP
 
 Once you've built the Linux stack with the correct configuration, you're ready to run it on an Arm CPU Fixed Virtual Platform (FVP).
 
-### Step 1: Verify the Build Output
+Replace <SRC_PATH> with the root path to your workspace, and <PATH_TO_LOG> with the location where you want to save the UART output logs.
+
+## Verify the build output
 
 After building, check the output directory to make sure the expected files were generated:
 
 ```bash
 tree output/aemfvp-a/aemfvp-a/
 ```
-Expected output:
+The expected output is:
 
 ```output
 output/aemfvp-a/aemfvp-a/
@@ -35,9 +37,10 @@ output/aemfvp-a/aemfvp-a/
 └── uefi.bin -> ../components/aemfvp-a/uefi.bin
 ```
 
-### Step 2: Run the Software Stack
+## Run the software stack
 
 To launch the software stack on the FVP, use a command like the following:
+
 ```bash
 FVP_Base_Cortex-A55x4 \
 -C pctl.startup=0.0.0.0 \
@@ -59,15 +62,19 @@ FVP_Base_Cortex-A55x4 \
 ```
 This will boot Trusted Firmware-A, UEFI/U-Boot, Linux, and BusyBox in sequence.
 
-### Step 3: Troubleshoot FVP Launch Issues
+## Troubleshoot FVP launch issues
 
-Different FVP models use different CPU instance names. If you see an error like:
+Different FVP models use different CPU instance names. 
+
+If you see an error like:
 
 ```output
-Warning: target instance not found: 'FVP_Base_Cortex_A65AEx4_Cortex_A76AEx4.cluster0.cpu0' (data: 'output/aemfvp-a/aemfvp-a/fvp-base-revc.dtb')
+Warning: target instance not found: 'FVP_Base_Cortex_A65AEx4_Cortex_A76AEx4.cluster0.cpu0' (data: 'output/aemfvp-a/aemfvp-afvp-base-revc.dtb')
 ```
 
-You need to identify the correct instance name for your platform. Run:
+Identify the correct instance name for your platform. 
+
+Run:
 
 ```bash
 FVP_Base_Cortex-A65AEx4+Cortex-A76AEx4 -l | grep RVBARADDR | grep cpu0
@@ -86,12 +93,12 @@ Update your --data parameters accordingly:
 --data cluster0.subcluster0.cpu0.thread0=<SRC_PATH>/output/aemfvp-a/aemfvp-a/fvp-base-revc.dtb@0x83000000
 ```
 
-{{% notice tip %}}
-Always confirm the CPU instance name when switching between different FVP models.
+{{% notice Tip %}}
+Always check the name of the CPU instance when switching between different FVP models.
 {{% /notice %}}
 
-### Optional: Use the GUI
+## Use the GUI (optional)
 
 You can also run the FVP using its graphical user interface:
 
-![GUI #center](FVP.png)
+![GUI #center](FVP.png "View of the FVP GUI")