Merge pull request #811 from danielnguyen-arm/main

Add RD Infra quick start guide

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

@@ -0,0 +1,35 @@
+---
+title: Reference Design Debugging Guide
+
+minutes_to_complete: 20
+
+who_is_this_for: This is an introductory topic for software developers interested in testing the reference firmware stack.
+
+learning_objectives: 
+    - Create a debug connection
+    - Debug SCP
+    - Debug TF-A
+
+prerequisites:
+    - A computer running Linux. Any architecture can be used.
+    - Can boot reference design software stack on an FVP.
+
+author_primary: Daniel Nguyen
+
+### Tags
+skilllevels: Introductory
+subjects: Reference Design
+armips:
+    - Neoverse
+tools_software_languages:
+    - Arm Development Studio
+operatingsystems:
+    - Linux
+
+
+### 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/servers-and-cloud-computing/refinfra-debug/_next-steps.md

@@ -0,0 +1,19 @@
+---
+next_step_guidance: You can continue to learn about the reference design firmware stack. The neoverse reference design platform software documentation is a great next step.
+
+recommended_path: /learning-paths/PLACEHOLDER_CATEGORY/PLACEHOLDER_LEARNING_PATH/
+
+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: 21                  # set to always be larger than the content in this path, and one more than 'review'
+title: "Next Steps"         # Always the same
+layout: "learningpathall"   # All files under learning paths have this same wrapper
+---

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

@@ -0,0 +1,47 @@
+---
+review:
+    - questions:
+        question: >
+            What is the purpose of symbol files?
+        answers:
+            - "They provide a mapping between the binary code and the human-readable identifiers in the source code"
+            - "They are used to store the graphical symbols used in the user interface of the program"
+            - "They contain the compiled machine code that is directly executable by the computer"
+            - "All of the above"
+        correct_answer: 1
+        explanation: >
+            Symbol files enable debuggers to identify program locations, function names, and display source files during code execution.
+
+    - questions:
+        question: >
+            When debugging TrustedFirmware-A, how should the symbol files be loaded considering the offsets for the different exception levels that the BLs run at?
+        answers:
+            - "Load the files at the offset values specified in the source code"
+            - "Load the files at 0x0 because ATF uses absolute addresses for its symbols"
+            - "Load the files at the base address of the memory region"
+            - "The loading offset does not matter"
+        correct_answer: 2
+        explanation: >
+            ATF uses absolute addresses for its symbols so we ensure an offset of 0.
+               
+    - questions:
+        question: >
+            You've successfully added the symbol files, but the code is not stopping at the breakpoints. What could be a potential reason?
+        answers:
+            - "The symbol files are loaded into the incorrect virtual address space and memory offset"
+            - "You forgot to check Execute debugger commands"
+            - "All of the above"
+        correct_answer: 3
+        explanation: >
+            There could be multiple reasons. It's important to load the symbol files into the correct virtual address space and memory offset. If incorrect, the debugger won't be able to properly map the symbols to the correct locations in the code. The Execute debugger command ensures that the add-symbol-file command is actually being executed. 
+
+
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+title: "Review"                 # Always the same title
+weight: 20                      # Set to always be larger than the content in this path
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+---
+

content/learning-paths/servers-and-cloud-computing/refinfra-debug/create-a-debug-connection-1.md

@@ -0,0 +1,22 @@
+---
+title: Create a Debug Connection
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Create a Debug Connection
+{{% notice %}}
+In this example, we will be working with the RD-N2 platform.
+{{% /notice %}}
+
+1. Modify the rdinfra/model-scripts/rdinfra/platforms/rdn2/run_model.sh.
+1. Remove –R parameter from PARAMS= section. That makes FVP stop while cores are in reset and wait for the debug connection.
+
+![modify parameters alt-text#center](images/modify_params.png "Figure 1. Modify run_model.sh")
+
+{{% notice %}}
+FVPS do not completely model the IMP DEF behavior that RTL does. FVPs also do not model cycles/performance or AXI/ACE/AHB/CHI bus level transactions.
+{{% /notice %}}
+

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

@@ -0,0 +1,45 @@
+---
+title: Debugging BL1
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Debugging BL1 
+In the **Edit configuration and launch** panel, in the **Connection** tab, select the correct
+target. In this example, we are selecting the **ARM_Neoverse-N2_0**. 
+
+![select target alt-text#center](images/select_target.png "Figure 1. Select target")
+
+Next, we'll add debug symbols. In the **Debugger** tab, check the **Execute debugger commands**, and add the following commands.
+
+{{% notice %}}
+If you wish to add platform specific debug files, the memory locations are in their respective ``platform_h.def`` file.
+{{% /notice %}}
+
+```
+add-symbol-file "/<workspace>/rd-infra/tf-a/build/rdn2/debug/bl1/bl1.elf" EL3:0x0
+add-symbol-file "/<workspace>/rd-infra/tf-a/build/rdn2/debug/bl2/bl2.elf" EL1S:0x0
+add-symbol-file "/<workspace>/rd-infra/tf-a/build/rdn2/debug/bl31/bl31.elf" EL3:0x0
+```
+
+![tfa symbols alt-text#center](images/tfa-symbols.png "Figure 2. Load TF-A symbols")
+
+These commands load the symbol files and specify the memory address where the symbols should be loaded.
+Replacing <workspace> with the path to your workspace directory.
+The EL and number at the end of each command (e.g. ``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 ensure an offset of 0.
+
+After connecting to the running model, see that it has stopped. Set a breakpoint on the next instruction of
+the TF-A and press run. In this debug panel, you will find common debugging functions like stepping, skipping, and others.
+
+![debug options alt-text#center](images/debug_options.png "Figure 3. Debug options")
+
+Observe the SCP console output. After SCP de-asserts reset for the NeoverseN2 Core 0, it stops on the breakpoint.
+
+![scp terminal alt-text#center](images/scp_terminal.png "Figure 4. SCP terminal")
+
+Finally, set a breakpoint in the function you wish to debug. In this example, we'll set a breakpoint at ``bl1_main()`` and continue. 
+
+![bl1 breakpoint alt-text#center](images/bl1_breakpoint.png "Figure 5. BL1 breakpoint")

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

@@ -0,0 +1,23 @@
+---
+title: Debugging BL31
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Debugging BL31 
+Setting a breakpoint for BL1 was simple enough, but how do we set a breakpoint for BL31? In the
+tabs panel at the bottom, click the plus and add other tabs. Here are multiple other tabs
+available such as Register View, Memory View, and others. For this example, we are only interested in the **Functions** tab.
+
+![add functions alt-text#center](images/add_functions.png "Figure 1. Add functions tab")
+
+From here, search for ``bl31_entrypoint`` using the flashlight icon and set a breakpoint. Press continue. 
+
+![bl31 breakpoint 1 alt-text#center](images/bl31_breakpoint-1.png "Figure 2. BL31 breakpoint 1")
+
+Observe the application processor console output. TF-A will proceed from BL1 to BL2 to BL31.
+After reaching BL31, NeoverseN2 Core 0 stops on the breakpoint.
+
+![bl31 breakpoint 2 alt-text#center](images/bl31_breakpoint-2.png "Figure 3. BL31 breakpoint 2")

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

@@ -0,0 +1,51 @@
+---
+title: Debugging BL33 / UEFI
+weight: 6
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Debugging BL33 / UEFI
+Adding symbol files for UEFI requires you to boot the FVP once without debugging to retrieve the symbol file
+locations and memory addresses. After booting the FVP, notice that in the non secure AP console output,
+the UEFI load system helpfully shows where each driver is relocated to. In fact the UEFI load system pre-formats
+the output into add-symbol-file directives that can just be copy-pasted!
+
+The log files are stored in:
+```bash
+/<workspace>/rd-infra/model-scripts/rdinfra/platforms/rdn2/rdn2
+```
+
+Since we are interested in the ``uart-0-nsec`` console, we can use ``grep`` to find all the symbol files. 
+```bash
+grep add-symbol-file refinfra-*-uart-0-nsec-*
+```
+
+![grep uart logs alt-text#center](images/grep.png "Figure 1. Grep UART logs")
+
+We can then copy these lines and append them to the list of symbol files like before.
+Note that UEFI runs in EL2, so we must modify the end of the line to be ``EL2:<address>``.
+
+![uefi symbol files alt-text#center](images/uefi_symbol_files.png "Figure 3. Add uefi symbol files")
+
+ArmDS currently has [BETA] support for DWARF 5 formats. EDK2 builds the debug files in DWARF 5
+format. In order to properly load the debug files, follow the
+instructions [here](https://developer.arm.com/documentation/101470/2023-0/Reference/Standards-compliance-in-Arm-Debugger)
+
+These instructions state that you must enable the LLVM DWARF parser to use DWARF 5 format.
+To enable the LLVM DWARF parser, do the following. In the Arm Development Studio IDE, 
+
+1. Select **Window**  > **Preferences**. 
+2. Then, in the **Preferences** dialog box, navigate to **Arm DS** > **Debugger** > **DWARF Parser**. 
+3. Select the **Use LLVM DWARF parser** checkbox and click **Apply and Close**.
+
+![enable llvm alt-text#center](images/enable_llvm.png "Figure 4. Enable LLVM")
+
+Once the debugger is connected, see the functions tab. Here you can search for functions to
+set breakpoints. For example, let's set a breakpoint at the entry point to PEI. 
+
+![peicore alt-text#center](images/peicore.png "Figure 5. PeiCore functions")
+
+You will see that it has stopped at the breakpoint.
+

content/learning-paths/servers-and-cloud-computing/refinfra-debug/debugging-scp-2.md

@@ -0,0 +1,63 @@
+---
+title: Debugging SCP
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Debugging SCP
+{{% notice %}}
+At the time of writing this guide, SCP firmware debug uses "-Og" argument. This optimizes some variables. That makes debugging difficult. To replace "-Og" with "-O0", do the following:
+
+* Navigate to ``rd-infra/scp/cmake/Toolchain``
+* See <compiler>_Baremetal.cmake files
+* Modify the one for the compiler you use. For example, for GCC modify GNU-Baremetal.cmake:
+
+``string(APPEND CMAKE_${language}_FLAGS_DEBUG_INIT "-Og")`` 
+
+to 
+
+``string(APPEND CMAKE_${language}_FLAGS_DEBUG_INIT "-O0")``
+{{% /notice %}}
+
+After starting the model, click **Create a new debug connection...** from the **Debug Control** panel.
+
+![new debug connection alt-text#center](images/new_debug_connection.png "Figure 1. New debug connection")
+
+Create a connection name. You may choose any name you prefer.
+
+![debug connection name alt-text#center](images/debug_connection_name.png "Figure 2. Debug connection name")
+
+Next, click on **Add a new model...**.
+
+![add new model alt-text#center](images/add_new_model.png "Figure 3. Add new model")
+
+Make sure the Model Interface is selected to be **CADI**. 
+Click **Browse for model running on local host**.
+Select the correct model and click finish.
+
+![connect model alt-text#center](images/connect_model.png "Figure 4. Connect model")
+
+In the **Edit configuration and launch** panel, in the **Connection** tab, select the correct target. In this example, select **ARM_Cortex-M7_1**. 
+
+![select target alt-text#center](images/select_cortexm7.png "Figure 5. Select target")
+
+In the **Files** panel, select **Load Symbols from file**, **File System**, and select the **SCP RAMFW ELF** file, located at ``rd-infra/scp/output/rdn2/0/scp_ramfw/bin/rdn2-bl2.elf``.
+
+![scp symbols alt-text#center](images/scp_symbols.png "Figure 6. Load SCP symbols")
+
+Select apply then debug. DS will now connect to the model and start debugging.
+
+Once connected, we can set breakpoints in the source code. This can be done by searching for the function in the **Functions** tab, or by double clicking next to the line number.
+
+Here, you can see that we've set a breakpoint at ``cmn700_discovery()``. You'll see that it has stopped at that breakpoint upon continuing the code.
+
+![scp breakpoint 1 alt-text#center](images/scp_breakpoint1.png "Figure 7. cmn700_discovery() breakpoint")
+
+We'll set another breakpoint at a debug print statement. 
+
+![scp breakpoint 2 alt-text#center](images/scp_breakpoint2.png "Figure 8. SCP breakpoint 2")
+
+You can see the output in the SCP UART window.
+

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

@@ -0,0 +1,35 @@
+---
+title: Reference Design Quick Start
+
+minutes_to_complete: 30
+
+who_is_this_for: This is an introductory topic for software developers interested in testing the reference firmware stack.
+
+learning_objectives: 
+    - Setup your environment
+    - Build the reference firmware stack
+    - Test the reference firmware stack
+
+prerequisites:
+    - A computer running Linux. Any architecture can be used.
+
+author_primary: Tom Pilar
+
+### Tags
+skilllevels: Introductory
+subjects: Reference Design
+armips:
+    - Neoverse
+tools_software_languages:
+    - Docker
+    - Arm Development Studio
+operatingsystems:
+    - Linux
+
+
+### 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/servers-and-cloud-computing/refinfra-quick-start/_next-steps.md

@@ -0,0 +1,18 @@
+---
+next_step_guidance: You can continue leraning about the reference design firmware stack. The Learning Path using Arm Development Studio to debug the firmware is a great next step.
+
+recommended_path: /learning-paths/servers-and-cloud-computing/refinfra-debug/
+
+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: 21                  # set to always be larger than the content in this path, and one more than 'review'
+title: "Next Steps"         # Always the same
+layout: "learningpathall"   # All files under learning paths have this same wrapper
+---