Merge pull request #2338 from madeline-underwood/zena_css

Zena CSS_JA to approve

Author: jasonrandrews

content/learning-paths/automotive/zenacssdebug/_index.md

@@ -1,49 +1,46 @@
 ---
 title: Debug Arm Zena CSS Reference Software Stack with Arm Development Studio
 
-draft: true
-cascade:
-    draft: true
 
 minutes_to_complete: 60
 
-who_is_this_for: This is an introductory topic for software developers who wish to use Arm Development Studio to explore and debug the Arm Zena CSS Reference Software Stack.
+who_is_this_for: This introductory topic is for software developers who want to use Arm Development Studio to explore and debug the Arm Zena Compute Subsystem (CSS) Reference Software Stack on a Fixed Virtual Platform (FVP).
 
-learning_objectives: 
-    - Set up debug configuration for the Arm Zena CSS FVP
-    - Debug Runtime Security Engine (RSE) from boot time
-    - Debug Safety Island (SI)
-    - Debug Linux OS on Primary Compute cores
+learning_objectives:
+  - Set up and save a debug configuration for the Arm Zena CSS FVP
+  - Start Runtime Security Engine (RSE) debug at reset and step through early boot
+  - Attach to and debug Safety Island (SI) firmware
+  - Attach to the Linux kernel on the primary compute cores and debug user space processes
 
 prerequisites:
-    - Ubuntu 22.04 host machine
-    - You will need [Arm Development Studio 2024.1 (or later)](/install-guides/armds) and an appropriate license
-    - A basic understanding of the Arm Zena CSS software stack and Arm processors
+  - Ubuntu 22.04 host machine
+  - Arm Development Studio 2024.1 or later with a valid license - for support see the [Install Guide for ADS](/install-guides/armds) 
+  - Basic understanding of the Arm Zena CSS software stack, Armv8-A/Armv9-A cores, and Linux
 
 author: Ronan Synnott
 
 ### Tags
 skilllevels: Introductory
 subjects: Performance and Architecture
 armips:
-    - Cortex-A
-    - Cortex-R
+  - Cortex-A
+  - Cortex-R
 operatingsystems:
-    - Linux
+  - Linux
 tools_software_languages:
-    - Arm Development Studio
-    - Arm Zena CSS
-
+  - Arm Development Studio
+  - Arm Zena CSS
+  - FVP
 
 further_reading:
-    - resource:
-        title: Arm Zena Compute System (CSS)
-        link: https://developer.arm.com/Compute%20Subsystems/Arm%20Zena%20Compute%20Subsystem
-        type: website
-    - resource:
-        title: Arm Development Studio
-        link: https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio
-        type: website
+  - resource:
+      title: Arm Zena Compute Subsystem (CSS)
+      link: https://developer.arm.com/Compute%20Subsystems/Arm%20Zena%20Compute%20Subsystem
+      type: website
+  - resource:
+      title: Arm Development Studio
+      link: https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio
+      type: website
 
 
 ### FIXED, DO NOT MODIFY

content/learning-paths/automotive/zenacssdebug/config.md

@@ -1,63 +1,64 @@
 ---
 # User change
-title: "Model Configuration"
+title: "Configure the model"
 
 weight: 4 # 1 is first, 2 is second, etc.
 
 # Do not modify these elements
 layout: "learningpathall"
 ---
 
-# Debug Configuration
+## Set up a debug configuration for the Zena CSS FVP
 
-Arm Development Studio requires a `Debug Configuration` of the target that it will connect to.
+Now you'll walk through setting up an Arm Development Studio debug configuration for the Zena CSS FVP using the Iris interface. This is a fast, reliable path to a working configuration.
 
-As of Arm Development Studio version 2025.0, there is no such configuration provided 'out-of-the-box' for the Zena CSS FVP. However creating such a configuration is straight forward.
+As of Arm Development Studio 2025.0, there is no out-of-the-box configuration for the Zena CSS FVP. Creating one, however, is straightforward.
 
-See the Arm Development Studio [Getting Started Guide](https://developer.arm.com/documentation/101469/latest/Migrating-from-DS-5-to-Arm-Development-Studio/Connect-to-new-or-custom-models) for full instructions, but they are also summarized below.
+For full guidance, see the Arm Development Studio [Getting Started Guide](https://developer.arm.com/documentation/101469/latest/Migrating-from-DS-5-to-Arm-Development-Studio/Connect-to-new-or-custom-models). A concise, task-focused version is below.
 
-## Launch FVP
+## Launch the FVP (with Iris)
 
-As per previous section, launch FVP with the Iris server enabled:
+Launch the FVP with the Iris server enabled:
 
-```command
+```bash
 kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100"
 ```
-or if connecting to the FVP remotely:
+If connecting to the FVP remotely, you can use this command:
 
-```command
+```bash
 kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100 -A"
 ```
+
 {{% notice Note %}}
-A local connection is assumed for the remainder of this learning path.
+This example modeled below uses a local connection for the remaining steps.
 {{% /notice %}}
 
-## Configuration Database
-
-Debug Configurations are stored in a configuration database. You must first create a local database in which to store the configuration.
-
-Navigate to `File` > `New` > `Other`, and then select `Configuration Database` > `Configuration Database` from the drop-down list.
+## Create a configuration database in Arm Development Studio
 
-Click `Next`. Give the Database a name, and click `Finish`.
+Debug configurations are stored in a configuration database. Create a local database to store your model configuration:
 
-## Debug Configuration
+- In Arm Development Studio, go to **File > New > Other**.
+- Select **Configuration Database > Configuration Database**.
+- Click **Next**, enter a **Name**, then click **Finish**.
 
-Navigate to the same wizard as above, and select `Model Configuration`.
+## Create a model configuration for Zena CSS FVP (Iris)
 
-Click `Next`, and you will be prompted to select the above `Configuration Database`. Click `Next` again, and you will be prompted to select a Model Interface.
+- Open the same wizard (**File > New > Other**), then choose **Configuration Database > Model Configuration**.
+- Click **Next**, select the **Configuration Database** you created, then click **Next**.
+- For **Model Interface**, choose **Iris**, then click **Next**.
+- Choose **Browse for model running on local host**. The debugger detects and interrogates the FVP.  
+- If connecting remotely, choose **Connect to model running on either local or remote host** and provide the host and port.
 
-Select `Iris` from the pulldown, and click `Next`.
+Arm Development Studio generates a `model.mdf` file that enumerates all CPUs in the FVP.
 
-You will then be prompted to locate the model to connect to.
+Optionally, update **Manufacturer Name** (for example, `Arm`) and **Platform Name** (for example, `Zena_CSS_FVP`). Then **Save** and **Import** the model into the configuration database.
 
-Select `Browse for model running on local host`. The FVP will be detected and interrogated by the debugger.
-
-{{% notice Note %}}
-Use `Connect to model running on either local or remote host` if connecting remotely.
+{{% notice Tip %}}
+If the FVP is not detected, verify the Iris server is running on the expected port (`7100` by default) and that your firewall allows local connections. For remote connections, confirm the host is reachable and the port is open.
 {{% /notice %}}
 
 A `model.mdf` file will be created that identifies all CPUs within the FVP.
 
-You can change the `Manufacturer Name` and `Platform Name` to something more meaningful (such as `Arm` and `Zena_CSS_FVP`), then `Save`, and `Import` into the configuration database.
+You can change the **Manufacturer Name** and **Platform Name** to something more meaningful (such as `Arm` and `Zena_CSS_FVP`), then **Save**, and **Import** into the configuration database.
 
 The debugger is now aware of the FVP and you are ready to debug.

content/learning-paths/automotive/zenacssdebug/connect.md

@@ -1,75 +1,86 @@
 ---
 # User change
-title: "Debug Connections"
+title: "Create debug connections"
 
 weight: 5 # 1 is first, 2 is second, etc.
 
 # Do not modify these elements
 layout: "learningpathall"
 ---
 
-## Debug Connections
+## Overview
 
 You are now ready to create debug connections for each of the sub-systems within Zena CSS. In this section you will create the connections, which will be subsequently enhanced in the following section. You may prefer to fully set up one such connection before moving to others.
 
-Arm Development Studio has full support for Heterogeneous systems such as Zena CSS, and so you can connect to all processors simultaneously.
+Arm Development Studio has full support for heterogeneous systems such as Zena CSS, and so you can connect to all processors simultaneously.
 
-### Debug connection project
+## Create a project for connection files
 
-First, create a project to store these connections (`.launch` files) in.
+First, create a project to store these connections (`.launch` files).
 
-Select `File` > `New...` > `Project` > `General` > `Project`, and give it a meaningful name (`Connections`).
+Select **File** > **New...** > **Project** > **General** > **Project**, and give it a meaningful name (for example, `Connections`).
 
-### RSE (Cortex-M55)
+## Create an RSE (Cortex-M55) model connection
 
-Runtime Security Engine (RSE) is based on [Cortex-M55](https://developer.arm.com/Processors/Cortex-M55) core and is a security subsystem fulfilling the role of Root of Trust.
+Runtime Security Engine (RSE) is based on the [Cortex-M55](https://developer.arm.com/Processors/Cortex-M55) core and is a security subsystem fulfilling the role of Root of Trust.
 
-Select `File` > `New` > `Model Connection`.
+Select **File** > **New** > **Model Connection**.
 
 {{% notice Note %}}
-You can also use `File` > `New` > `Other` > `Arm Debugger` > `Model Connection`, or
-
-`Create a debug connection...` shortcut in the `Debug Control` pane.
+You can also use **File** > **New** > **Other** > **Arm Debugger** > **Model Connection**, or the **Create a debug connection**... shortcut in the **Debug Control** pane.
 {{% /notice %}}
 
-Specify a connection name (`RSE`), and associate with the above `Connections` project. Click `Next`.
+Specify a connection name (`RSE`), and associate with the above `Connections` project. Click **Next**.
 
-Locate the FVP based on the name you gave it previously (`Zena_CSS_FVP`). The text filter can help you locate it easily.
+Locate the FVP based on the name you gave it previously (`Zena_CSS_FVP`). You can use the text filter to locate it quickly.
 
-You will then be presented with the `Edit configuration` pane. In the `Connection` tab, scroll down to locate `Bare Metal Debug` > `Arm_Cortex-M55`.
+You will then be presented with the **Edit configuration** pane. In the **Connection** tab, scroll down to locate **Bare Metal Debug** > **Arm_Cortex-M55**.
 
-As you will be later launching the FVP with the software stack loaded, select `Connect to an already running model`.
+As you will be later launching the FVP with the software stack loaded, select **Connect to an already running model**.
 
-Assuming the same host will be running both the FVP and the debugger, specify the `Connection address` as the default `127.0.0.1:7100`.
+Assuming the same host will be running both the FVP and the debugger, specify the **Connection address** as the default `127.0.0.1:7100`.
 
 {{% notice Note %}}
-`127.0.0.1` is the same as `localhost`, that is the same host machine as is running the FVP.
+`127.0.0.1` is the same as `localhost`, which targets the host running the FVP. For a remote FVP, specify the remote IP address and start the FVP with `-A`. Port `7100` is the default Iris port and can be adjusted if needed.
+{{% /notice %}}
+
+Arm Development Studio creates `RSE.launch` inside the **Connections** project.
+
+## Create a Safety Island (Cortex-R82AE) model connection
 
-It is also possible to connect to a remote host by specifying appropriate IP address, and launching FVP with the `-A` option.
+The Safety Island is based on the [Cortex-R82AE](https://developer.arm.com/Processors/Cortex-R82AE) core and manages power, clocks, and CMN control.
 
-`7100` is the default port number. You may need to change this if necessary.
+Follow the same steps as for RSE, with this change:
+
+In **Edit configuration**, expand **Bare Metal Debug** and select **Arm_Cortex-R82AE**.
+
+{{% notice Tip %}}
+To save time, copy `RSE.launch` to `SI.launch` and update the CPU selection to **Arm_Cortex-R82AE**.
 {{% /notice %}}
 
-Click `Apply` to save the connection information, and `Close`. Observe that `RSE.launch` is created inside the `Connections` project.
+## Create Primary compute (Cortex-A720AE) connections
 
-### Safety Island (Cortex-R82AE)
+Primary compute comprises four clusters intended to run a rich OS such as Linux. Each cluster has four [Cortex-A720AE](https://developer.arm.com/Processors/Cortex-A720AE) cores alongside a [DSU-120AE](https://developer.arm.com/Processors/DSU-120AE) DynamIQ Shared Unit.
 
-The Safety Island is a subsystem based on [Cortex-R82AE](https://developer.arm.com/Processors/Cortex-R82AE) core. The software running on the Safety Island is responsible for power, clock and CMN control.
+You will create two connections: one for bare-metal initialization and one with Linux kernel awareness for SMP debug.
 
-The procedure to create this connection is very similar to the above, other than to select `Bare Metal Debug` > `Arm_Cortex-R82AE` from the drop-down.
+### Primary init (bare metal, CPU0 only)
 
-{{% notice %}}
-For convenience you can copy-and-paste `RSE.launch` as `SI.launch` and just modify the CPU.
-{{% /notice %}}
+Create `Primary_init.launch`:
+
+- Select **File > New > Model Connection**.
+- Select your `Zena_CSS_FVP` model.
+- In **Edit configuration**, expand **Bare Metal Debug** and select **ARM_Cortex-A720AE_0** to attach to CPU0 only. This leaves other CPUs running.
 
-### Primary Compute (Cortex-A720AE)
+### Primary Linux (SMP, OS awareness)
 
-The Primary Compute consists of four processor clusters to run a rich OS such as Linux. Each processor cluster includes four [Cortex-A720AE](https://developer.arm.com/Processors/Cortex-A720AE) cores and a [DSU-120AE](https://developer.arm.com/Processors/DSU-120AE) DynamIQ Shared Unit.
+Create **Primary_Linux.launch** for Linux kernel debug with OS awareness:
 
-The application processors will be debugged in an SMP configuration with Linux Kernel awareness.
+- Use **File > New > Model Connection**.
+- Select your **Zena_CSS_FVP** model.
+- In **Edit configuration**, expand **Linux Kernel Debug** and choose **ARM_Cortex-A720AEx16 SMP Cluster 1**.  
+  This connects to all 16 Cortex-A720AE processors described in the FVP. Only cores 0 to 3 are used by the default Linux configuration.
 
-As shown above, create `Primary_init.launch` connection and scroll to `Bare Metal Debug` > `ARM_Cortex-A720AE_0`. This will connect to just CPU0, leaving the other CPUs free to run.
+To learn more about OS awareness in Arm Debugger, see the [OS awareness documentation](https://developer.arm.com/documentation/101470/latest/Debugging-Embedded-Systems/About-OS-awareness).
 
-To debug the Linux kernel you can make use of the [OS awareness](https://developer.arm.com/documentation/101470/latest/Debugging-Embedded-Systems/About-OS-awareness) feature of the Arm Debugger.
 
-Create `Primary_Linux.launch` connection and scroll to `Linux Kernel Debug` > `ARM_Cortex-A720AEx16 SMP Cluster 1`. This will connect to all 16 `Cortex-A720AE` processors present in the FVP, though only cores 0-3 are used.

content/learning-paths/automotive/zenacssdebug/launch.md

@@ -1,56 +1,53 @@
 ---
 # User change
-title: "Launch FVP"
+title: "Launch the FVP"
 
 weight: 3 # 1 is first, 2 is second, etc.
 
 # Do not modify these elements
 layout: "learningpathall"
 ---
 
-## Launch FVP
+## Start the FVP from the build environment
 
-You can now launch the FVP within the virtual environment with the software stack loaded:
+You can launch the FVP within the build environment with the software stack loaded:
 
 ```command
 kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose"
 ```
-Refer to the [documentation](https://arm-auto-solutions.docs.arm.com/en/v2.0/rd-aspen/user_guide/reproduce.html#run-the-fvp) for more details.
-While you can continue to use this method to launch the FVP whilst debugging, this command does not enable the Iris debug server inside the model, and so will not be debuggable.
 
-Additional command options are necessary.
+See the [Arm Zena CSS User Guide](https://arm-auto-solutions.docs.arm.com/en/v2.0/rd-aspen/user_guide/reproduce.html#run-the-fvp) for further information.
 
-You will use the following. See output of `FVP_RD_Aspen --help` for full list and explanation. Options are case-sensitive.
+While you can continue to use this method during debugging, it does not enable the Iris debug server in the model, so the system cannot be debugged from Arm Development Studio. Additional command-line options are required.
 
-| Option                | Alias    | Notes                                         |
-|---------------------- |--------- |---------------------------------------------- |
-| `--iris-server`       | `-I`     | Start Iris Debug Server                       |
-| `--iris-port`         |          | Specify a port number (default = `7100`)      |
-| `--run`               | `-R`     | Run simulation when debug server started      |
-| `--iris-allow-remote` | `-A`     | Allow remote connections (if different hosts) |
+You will use the following options (see `FVP_RD_Aspen --help` for the full list). Options are case-sensitive.
 
-### Launch FVP with additional options
+| Option                  | Alias | Notes                                                 |
+|-------------------------|:-----:|-------------------------------------------------------|
+| `--iris-server`         | `-I`  | Start the Iris debug server                           |
+| `--iris-port <port>`    |       | Set the Iris port (default `7100`)                    |
+| `--run`                 | `-R`  | Run the simulation when the debug server starts       |
+| `--iris-allow-remote`   | `-A`  | Allow remote connections (only if required)           |
 
-To launch the FVP with additional options, modify the above command by adding `--` and then the options.
+## Enable the Iris debug server for Arm Development Studio
 
-For example, to launch the model with the debug server and hold at the initial reset condition:
+Append `--` to pass model options through `runfvp`.
 
+Start the model with the debug server and hold at reset:
 ```command
 kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100"
 ```
 
-To launch the model and start running (so that it can start to boot up):
-
+Start the model with the debug server and begin execution so that boot can progress:
 ```command
 kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100 --run"
 ```
 
-To launch the model so that remote hosts can access it (not recommended if not needed), using options aliases:
-
+If required, allow remote debug connections using option aliases:
 ```command
 kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- -I -A --iris-port 7100"
 ```
 
 {{% notice Note %}}
-It is recommended to specify the port number used even if it is the default as that must match the debug connection setting (see later).
+Even when using the default, specify the Iris port explicitly so it matches your debugger connection settings. If you enable remote connections, ensure your firewall allows inbound access to the chosen port.
 {{% /notice %}}