Merge pull request #2268 from RonanSynnottArm/zenadebug

Zena CSS debug with Arm DS

Author: pareenaverma

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

@@ -0,0 +1,55 @@
+---
+title: Debug Arm Zena CSS Reference Software Stack with Arm Development Studio
+
+draft: true
+cascade:
+    draft: true
+    
+description: Learn how to set up a debug environment for Arm Zena CSS Reference Software Stack
+
+minutes_to_complete: 60
+
+who_is_this_for: This topic is for software developers who wish to use Arm Development Studio to explore and debug the Arm Zena CSS Reference Software Stack.
+
+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
+##    - Debug Linux application
+
+prerequisites:
+    - Ubuntu 22.04 host machine
+    - Arm Development Studio 2024.1 (or later) and an appropriate license
+    - A basic understanding of the Arm Zena CSS software stack and Arm processors
+
+author: Ronan Synnott
+
+### Tags
+skilllevels: Introductory
+subjects: 
+armips:
+    - Arm Zena CSS
+operatingsystems:
+    - Linux
+tools_software_languages:
+    - Arm Development Studio
+
+
+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
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/automotive/zenacssdebug/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       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.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

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

@@ -0,0 +1,63 @@
+---
+# User change
+title: "Model Configuration"
+
+weight: 4 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+# Debug Configuration
+
+Arm Development Studio requires a `Debug Configuration` of the target that it will connect to.
+
+As of 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.
+
+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 summarized below.
+
+## Launch FVP
+
+As per previous section, launch FVP with the Iris server enabled:
+
+```command
+kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100"
+```
+or if connecting to the FVP remotely:
+
+```command
+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.
+{{% /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.
+
+Click `Next`. Give the Database a meaningful name, and click `Finish`.
+
+## Debug Configuration
+
+Navigate to the same wizard as above, and select `Model Configuration`.
+
+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.
+
+Select `Iris` from the pulldown, and click `Next`.
+
+You will then be prompted to locate the model to connect to.
+
+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 %}}
+
+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.
+
+The debugger is now aware of the FVP and you are ready to debug.

content/learning-paths/automotive/zenacssdebug/configdb.png

@@ -0,0 +1,75 @@
+---
+# User change
+title: "Debug Connections"
+
+weight: 5 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+## Debug Connections
+
+You are now ready to create debug connections for each of the sub-systems within Zena CSS. This section 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.
+
+Development Studio has full support for Heterogeneous systems such as Zena CSS, and so you can connect to all processors simultaneously.
+
+### Debug connection project
+
+It may be sensible to create a project to store these connections (`.launch` files) in.
+
+Select `File` > `New...` > `Project` > `General` > `Project`, and give it a meaningful name (`Connections`).
+
+### RSE (Cortex-M55)
+
+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.
+
+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.
+{{% /notice %}}
+
+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 locate easily.
+
+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 we shall 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`.
+
+{{% notice Note %}}
+`127.0.0.1` is the same as `localhost`, that is the same host machine as is running the FVP.
+
+It is also possible to connect to a remote host by specifying appropriate IP address, and launching FVP with the `-A` option.
+
+`7100` is the default port number. You may need to change this if necessary.
+{{% /notice %}}
+
+Click `Apply` to save the connection information, and `Close`. Observe that `RSE.launch` is created inside the `Connections` project.
+
+### Safety Island (Cortex-R82AE)
+
+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.
+
+The procedure to create this connection is very similar to the above, other than to select `Bare Metal Debug` > `Arm_Cortex-R82AE` from the pull down.
+
+{{% notice %}}
+For convenience you can copy-and-paste `RSE.launch` as `SI.launch` and simply modify the CPU.
+{{% /notice %}}
+
+### Primary Compute (Cortex-A720AE)
+
+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.
+
+The application processors will be debugged in an SMP configuration with Linux Kernel awareness.
+
+As 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 debug the Linux kernel we 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/connect.md

@@ -0,0 +1,56 @@
+---
+# User change
+title: "Launch FVP"
+
+weight: 3 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+## Launch FVP
+
+From the [documentation](https://arm-auto-solutions.docs.arm.com/en/v2.0/rd-aspen/user_guide/reproduce.html#run-the-fvp) the default command to launch the FVP (within the virtual environment) with the software stack loaded is:
+
+```command
+kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose"
+```
+
+It is sensible to continue to use this method to launch the FVP whilst debugging. However this command as shown does not enable the Iris debug server inside the model, and so will not be debuggable.
+
+Additional command options are necessary.
+
+We will use the following. See output of `FVP_RD_Aspen --help` for full list and explanation. Options are case-sensitive.
+
+| 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) |
+
+### Launch FVP with additional options
+
+To launch the FVP with additional options, modify the above command by adding `--` and then the options.
+
+For example, to launch the model with the debug server and hold at the initial reset condition:
+
+```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):
+
+```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:
+
+```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).
+{{% /notice %}}

content/learning-paths/automotive/zenacssdebug/debugger_commands.png

@@ -0,0 +1,69 @@
+---
+# User change
+title: "Debug Primary Compute and Linux"
+
+weight: 8 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+## Debug Primary Compute
+
+The Primary Compute application processors (`Cortex-A720AE`) are the final processors to be enabled.
+
+As before we can connect whilst powered down and monitor the point that they are enabled.
+
+You can debug the initialization code and/or the final Linux Operating System (OS) threads.
+
+### Connect debugger to target
+
+Use the following debugger commands in the `Primary_init.launch` to load the symbols for the `BL2` initialization code, setting a breakpoint at `bl2_entrypoint`.
+
+Note that an address "offset" is used to specify the exception level that the image is relevant to. If the processor changes exception level, the debug information would need to also be loaded to the corresponding EL address space.
+
+For example the processors start in `EL3` and move to `EL2N` when the Linux kernel is enabled.
+
+``` text
+stop
+add-symbol-file /arm-auto-solutions/build/tmp_baremetal/work/fvp_rd_aspen-poky-linux/trusted-firmware-a/2.11.0+git/image/firmware/bl2.elf EL3:0x0
+tbreak bl2_entrypoint
+```
+{{% notice Note %}}
+Exact paths may differ for your set up.
+{{% /notice %}}
+
+Run the code to the `bl2_entrypoint` and you can debug as expected.
+
+### Debug Linux kernel modules
+
+To make use of the OS awareness, disconnect `Primary_init` and connect to `Primary_Linux` as created previously. Load the symbols from `vmlinux` image.
+
+``` text
+stop
+add-symbol-file /arm-auto-solutions/build/tmp_baremetal/work/fvp_rd_aspen-poky-linux/linux-yocto/6.6.54+git/linux-fvp_rd_aspen-standard-build/vmlinux EL2N:0x0
+set substitute-path /usr/src/kernel/ /arm-auto-solutions/build/tmp_baremetal/work-shared/fvp-rd-aspen/kernel-source/
+```
+Run the FVP until the OS prompt appears.
+
+{{% notice %}}
+If only interested in kernel debug, modify the launch command for the FVP to include `--run` to start execution immediately.
+
+``` command
+kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100 --run"
+```
+{{% /notice %}}
+
+You can now enable the `Threads` view in the `Debug Control` pane.
+
+Right-click on the connection, and select `Display Threads`. You can also do this by entering `thread` in the `Command` pane.
+
+The view will then change from listing the 16 application processors to the OS threads.
+
+{{% notice Note %}}
+A warning of the form:
+``` text
+WARNING(ROS60): Could not enable OS support as the OS does not appear to be initialized. This might be caused by a mismatch between the loaded symbols and the code on the target or because the OS is not up and running. Enabling OS support will be re-attempted when the target next stops.
+```
+may be emitted if the OS is not booted when you connect. It can safely be ignored.
+{{% /notice %}}