Ready for review

RonanSynnottArm · RonanSynnottArm · commit 137c3f644a7b · 2025-08-19T13:44:26.000+09:00
diff --git a/content/learning-paths/automotive/zenacssdebug/_index.md b/content/learning-paths/automotive/zenacssdebug/_index.md
@@ -17,7 +17,7 @@ learning_objectives:
 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
+    - A basic understanding of the Arm Zena CSS software stack and Arm processors
 
 author: Ronan Synnott
 
diff --git a/content/learning-paths/automotive/zenacssdebug/config.md b/content/learning-paths/automotive/zenacssdebug/config.md
@@ -30,8 +30,6 @@ Debug Configurations are stored in a configuration database. You must first crea
 
 Navigate to `File` > `New` > `Other`, and then select `Configuration Database` > `Configuration Database` from the drop-down list.
 
-![New Configuration Database](configdb.png)
-
 Click `Next`. Give the Database a meaningful name, and click `Finish`.
 
 ## Debug Configuration
diff --git a/content/learning-paths/automotive/zenacssdebug/connect.md b/content/learning-paths/automotive/zenacssdebug/connect.md
@@ -8,6 +8,8 @@ weight: 5 # 1 is first, 2 is second, etc.
 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.
@@ -18,7 +20,7 @@ It may be sensible to create a project to store these connections (`.launch` fil
 
 Select `File` > `New...` > `Project` > `General` > `Project`, and give it a meaningful name (`Connections`).
 
-## RSE (Cortex-M55)
+### 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.
 
@@ -41,27 +43,33 @@ As we shall be later launching the FVP with the software stack loaded, select `C
 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`. It is also possible to connect to a remote host by specifying appropriate address.
+`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)
+### 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.
 
-You can copy-and-paste `RSE.launch` as `SI.launch` and open to change the CPU.
+{{% notice %}}
+For convenience you can copy-and-paste `RSE.launch` as `SI.launch` and simply modify the CPU.
+{{% /notice %}}
 
-## Primary Compute (Cortex-A720AE)
+### 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.launch` connection and scroll to `Linux Kernel Debug` > `ARM_Cortex-A720AEx16 SMP Cluster 1`.
+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.
 
-This will connect to all Cortex-A720AE processors present in the FVP, though only cores 0-3 are used.
+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.
diff --git a/content/learning-paths/automotive/zenacssdebug/debugger_commands.png b/content/learning-paths/automotive/zenacssdebug/debugger_commands.png
diff --git a/content/learning-paths/automotive/zenacssdebug/launch.md b/content/learning-paths/automotive/zenacssdebug/launch.md
@@ -8,24 +8,28 @@ weight: 3 # 1 is first, 2 is second, etc.
 layout: "learningpathall"
 ---
 
-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 with the software stack loaded is:
+## 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"
 ```
 
-However this does not enable the Iris debug server inside the model, and so will not be debuggable. Additional command options are necessary.
+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) |
+| `--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
+### Launch FVP with additional options
 
 To launch the FVP with additional options, modify the above command by adding `--` and then the options.
 
diff --git a/content/learning-paths/automotive/zenacssdebug/primarycompute.md b/content/learning-paths/automotive/zenacssdebug/primarycompute.md
@@ -0,0 +1,70 @@
+---
+# User change
+title: "Debug Primary Compute and Linux OS"
+
+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 operating system 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 are relevant to. If code changes exception level, debug info would need to also be loaded to the corresponding EL address space.
+
+For example the processors start in `EL3` and moves 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
+```
+
+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 %}}
diff --git a/content/learning-paths/automotive/zenacssdebug/rse.md b/content/learning-paths/automotive/zenacssdebug/rse.md
@@ -0,0 +1,83 @@
+---
+# User change
+title: "Debug RSE from reset"
+
+weight: 6 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+## Debug RSE from reset
+
+Let us start by debugging the initial code that executes on the Cortex-M55 within the RSE block.
+
+### Launch FVP
+
+Start a new `tmux` session for the FVP (if necessary):
+```command
+tmux new-session -s arm-auto-solutions
+```
+and navigate to your code repository.
+
+To debug from reset, launch the FVP with the Iris server but do not run. This will hold the FVP in the initial reset condition.
+
+```command
+kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100"
+```
+The FVP will start and emit various informational messages. Once initialized you should see something similar to:
+
+```output
+...
+Info: RD_Aspen: RD_Aspen.css.smb.rse_flashloader: FlashLoader: Saved 64MB to file '~/arm-auto-solutions/build/tmp_baremetal/deploy/images/fvp-rd-aspen/rse-flash-image.img'
+
+Info: RD_Aspen: RD_Aspen.ros.flash_loader: FlashLoader: Saved 128MB to file '~/arm-auto-solutions/build/tmp_baremetal/deploy/images/fvp-rd-aspen/ap-flash-image.img'
+```
+
+Note that execution has not started.
+
+### Connect the debugger
+
+Using the `RSE` connection created in the previous section, connect the debugger to the FVP. Observe that the processor is stopped before the first instruction has been executed.
+
+In fact, the FVP is configured to have the vector table (`VTOR_S`) start at `0x11000000`, and it you inspect memory at that address the vector table will be populated. However no debug information is visible. Debug information must be loaded.
+
+In the `Debug Pane`, select `Load...` from the pane menu, and select `Add Symbols file`.
+
+Browse to the `bl1_1.axf` file which is likely at:
+
+``` bash
+/arm-auto-solutions/build/tmp_baremetal/work/fvp_rd_aspen-poky-linux/trusted-firmware-m/2.1.0/build/bin/bl1_1.axf
+```
+Debug symbols will be loaded, but likely no source will be displayed. This is because the build was performed within the virtual environment but the debugger is running outside of that.
+
+You will be prompted to enter a path substitution to locate the sources. You can refer to the lowest common path so that all subsequent source files will also be located successfully.
+
+``` bash
+/usr/src/debug/trusted-firmware-m/2.1.0/
+/arm-auto-solutions/build/tmp_baremetal/work/fvp_rd_aspen-poky-linux/trusted-firmware-m/2.1.0/git/tfm/"
+```
+Finally, to perform a single instruction step (`stepi`) to allow the processor to fetch the address of the `Reset_Handler` and stop there.
+
+You can now step through the code, set breakpoints, and inspect the target as the code proceeds.
+
+### Automate setup
+
+For convenience, it is possible to automate these actions every time you connect by entering them as `Debugger Commands` in the `.launch` configuration.
+
+Open (double-click) the `.launch` file, and navigate to the `Debugger` pane.
+
+Enable `Execute debugger commands`, and enter the following (note pathing for your setup). You can copy the exact commands from the `Command` or `History` pane whilst performing the above GUI configuration.
+
+It is recommended to have an explicit `stop` command as symbols cannot be loaded whilst the target is running.
+
+``` text
+stop
+
+add-symbol-file /arm-auto-solutions/build/tmp_baremetal/work/fvp_rd_aspen-poky-linux/trusted-firmware-m/2.1.0/build/bin/bl1_1.axf
+
+set substitute-path /usr/src/debug/trusted-firmware-m/2.1.0/ /arm-auto-solutions/build/tmp_baremetal/work/fvp_rd_aspen-poky-linux/trusted-firmware-m/2.1.0/git/tfm/
+
+stepi
+```
+![Debugger pane](debugger_commands.png)
diff --git a/content/learning-paths/automotive/zenacssdebug/safetyisland.md b/content/learning-paths/automotive/zenacssdebug/safetyisland.md
@@ -0,0 +1,67 @@
+---
+# User change
+title: "Debug Safety Island code"
+
+weight: 7 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+## Debug Safety Island code from beginning
+
+The Safety Island (Cortex-R82AE) is released from reset by the RSE code, and so the RSE code must proceed to that point before the Safety Island core can execute.
+
+### Launch FVP
+
+If necessary, restart the FVP in the reset state as before, and reconnect `RSE`.
+
+```command
+kas shell -c "../layers/meta-arm/scripts/runfvp -t tmux --verbose -- --iris-server --iris-port 7100"
+```
+
+Set up the `SI` connection in a similar way as the `RSE` connection. Use the following commands in the `Debugger` pane. This will load debug symbols and performing the necessary path substitution. You can then set a breakpoint on the entry point of the `SI` code, `arch_exception_reset`.
+
+``` text
+stop
+
+add-symbol-file /arm-auto-solutions/build/tmp_baremetal/deploy/images/fvp-rd-aspen/si0_ramfw.elf
+
+set substitute-path /usr/src/debug/scp-firmware/2.14.0/ /arm-auto-solutions/build/tmp_baremetal/work/fvp_rd_aspen-poky-linux/scp-firmware/2.14.0/git/
+
+b arch_exception_reset
+```
+
+### Start execution
+
+Select the `RSE` connection in the `Debug Control` pane, and start execution (this will be unavailable in the `SI` connection, as that is currently powered down).
+
+The `RSE` code will run until the point that the `SI` is enabled. This is reflected in the output log.
+
+``` output
+[INF] BL2: SI CL0 post load start
+```
+
+#### Full output log
+
+``` output
+Trying ::1...
+Trying 127.0.0.1...
+Connected to localhost.
+Escape character is '^]'.
+[INF] Starting TF-M BL1_1
+[INF] Jumping to BL1_2
+[INF] Starting TF-M BL1_2
+[INF] Attempting to boot image 0
+[INF] BL2 image decrypted successfully
+[INF] BL2 image validated successfully
+[INF] Jumping to BL2
+[INF] Starting bootloader
+[INF] PSA Crypto init done, sig_type: EC-P256
+[INF] BL2: SI CL0 pre load start
+[INF] BL2: SI CL0 pre load complete
+[INF] Primary   slot: version=0.0.7+0
+[INF] Secondary slot: version=0.0.7+0
+[INF] Image 3 RAM loading to 0x70083c00 is succeeded.
+[INF] Image 3 loaded from the primary slot
+[INF] BL2: SI CL0 post load start
+```
