Merge pull request #1668 from jasonrandrews/review

Review debugging Neoverse N2 ref design Learning Path

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/refinfra-debug/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Debug Neoverse N2 Reference Design with Arm Development Studio
 
-minutes_to_complete: 20
+minutes_to_complete: 30
 
 who_is_this_for: This is an advanced topic for software developers who are interested in debugging the Arm Neoverse N2 Reference Firmware Stack.
 
@@ -25,20 +25,16 @@ armips:
     - Neoverse
 tools_software_languages:
     - Arm Development Studio
-    - Runbook
 
 operatingsystems:
     - Linux
 
-
 further_reading:
     - resource:
         title: Neoverse Reference Design Platform Software Documentation
         link: https://neoverse-reference-design.docs.arm.com/en/latest/index.html
         type: documentation
 
-
-
 ### FIXED, DO NOT MODIFY
 # ================================================================================
 weight: 1                       # _index.md always has weight of 1 to order correctly

content/learning-paths/servers-and-cloud-computing/refinfra-debug/debugging-bl1-3.md

@@ -53,13 +53,13 @@ If you would like to add platform-specific debug files, the memory locations are
 
 These commands load the symbol files and specify the memory address location, updating **workspace** to include the path to your own workspace directory.
 
-The `EL` (Exception Level) and number at the end of each command, for example, `EL3:0`, ensure the symbols are loaded into the correct virtual address space and at the correct memory offset. ATF uses absolute addresses for its symbols so we use an offset of 0.
+The `EL` (Exception Level) and number at the end of each command, for example, `EL3:0`, ensure the symbols are loaded into the correct virtual address space and at the correct memory offset. ATF uses absolute addresses for its symbols so you can use an offset of 0.
 
 When you connect the debugger, the primary CPU will be "spinning" on a ``b .`` instruction from the one you manually added to the ``bl1_entrypoint`` function.
 
 In this debug panel, you can find common debugging functions like stepping and skipping.
 
-Set a breakpoint in the function you would like to debug. In this example, we set a breakpoint at ``bl1_main()``.
+Set a breakpoint in the function you would like to debug. In this example, you can set a breakpoint at ``bl1_main()``.
 
 Simply interrupt the CPU and enter debug command `set $pc += 4'; you can now step through and debug the TF-A boot flow.
 

content/learning-paths/servers-and-cloud-computing/refinfra-debug/debugging-bl31-4.md

@@ -7,11 +7,11 @@ layout: learningpathall
 ---
 
 ## Debugging BL31 
-Setting a breakpoint for BL1 is simple, but how do we set a breakpoint for BL31?
+Setting a breakpoint for BL1 is simple, but how can you set a breakpoint for BL31?
 
 In the tabs panel at the bottom, click the plus **(`+`)** and **add other views**. Here there are multiple views available such as **Register View** and **Memory View**.
 
-For this example, we are only interested in the **Functions** view.
+For this example, you are only interested in the **Functions** view.
 
 ![add functions alt-text#center](images/add_functions.png "Figure 1. Add functions tab")
 

content/learning-paths/servers-and-cloud-computing/refinfra-debug/debugging-bl33-uefi-5.md

@@ -19,7 +19,7 @@ The log files are stored in:
 <workspace>/rd-infra/model-scripts/rdinfra/platforms/rdn2/rdn2
 ```
 
-Following the previous chapter, we should still be in TF-A. In the Commands window, execute the following command to break at the start of UEFI: ``break EL2N:0xE0000000``. Execute until we are in EL2N address space. This is because the script depends on the current address space when loading in symbols.
+Following the previous section, you should still be in TF-A. In the Commands window, execute the following command to break at the start of UEFI: ``break EL2N:0xE0000000``. Execute until we are in EL2N address space. This is because the script depends on the current address space when loading in symbols.
 
 In Arm DS, go to the scripts tab and hit "Import a script or directory" then "Import a DS or Jython script"
 

content/learning-paths/servers-and-cloud-computing/refinfra-debug/setup-1.md

@@ -1,25 +1,26 @@
 ---
-title: Set up environment
+title: Set up your development environment
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-To follow this learning path, you need Arm Development Studio installed, and an appropriate license. See the [Arm Development Studio Install Guide](/install-guides/armds) for instructions. Screenshots in this tutorial are from Arm Development Studio 2023.0.
+To debug the Neoverse N2 reference firmware, you need Arm Development Studio installed, and an appropriate license. See the [Arm Development Studio Install Guide](/install-guides/armds) for instructions. Screenshots are from Arm Development Studio 2023.0.
 
-You also need the Neoverse RD-N2 Reference Design Software Stack set up, and an associated FVP (Fixed Virtual Platform). For further information, see [Get started with the Neoverse Reference Design Software Stack](/learning-paths/servers-and-cloud-computing/refinfra-quick-start/). 
+You also need the Neoverse RD-N2 Reference Design Software Stack set up, and an associated FVP (Fixed Virtual Platform). You should be familiar with [Get started with the Neoverse Reference Design Software Stack](/learning-paths/servers-and-cloud-computing/refinfra-quick-start/) before you start debugging.
 
 ## SCP/LCP/RSE debug
 
-Modify this run script:
+If you want to debug SCP/LCP/RSE, you need to modify the run script:
 
-```bash
+```console
 rdinfra/model-scripts/rdinfra/platforms/rdn2/run_model.sh
 ```
-Remove the `–R` parameter from the `PARAMS=` section. 
 
-In the original script, this option was used to allow the FVP to continue to execute and not wait for the debug connection.
+To prepare for debugging, remove the `–R` parameter from the `PARAMS=` section. 
+
+When `-R` is used, the FVP continues execution and does not wait for the debug connection.
 
 ![modify parameters alt-text#center](images/modify_params.png "Figure 1. Modify run_model.sh")
 
@@ -28,18 +29,21 @@ To start a `CADI` debug server, use the `-S` option. For an `Iris` debug server,
 {{% /notice %}}
 
 Run the script to launch the model:
+
 ```bash
 ./run_model.sh
 ```
 
 ## AP debug
 
-If you remove the -R flag, RSE CPU wait is on hold and the APs will be powered off. You will have to kick-off the run, then it starts booting from RSE to AP cores. In this case, do *not* remove the -R flag.
+To debug the AP, you do not want to remove the `-R` flag. 
+
+If you remove the `-R` flag, RSE CPU waits and the APs will be powered off. You will have to kick-off the run, then it starts booting from RSE to AP cores. 
 
 This will be explained further in BL1, BL31, and BL33 chapters.
 
 {{% notice FVP Accuracy %}}
-FVPS do not completely model the `IMP DEF` behavior that RTL does.
+FVPs do not model the `IMP DEF` behavior with the same level of detail included in the RTL design. 
 
-FVPs also do not model cycles, performance, or `AXI/ACE/AHB/CHI` bus-level transactions.
+FVPs do not model cycles, performance, or `AXI/ACE/AHB/CHI` level transactions.
 {{% /notice %}}