Merge pull request #1281 from ArmDeveloperEcosystem/main

Merge to production

.wordlist.txt

@@ -3187,4 +3187,32 @@ prem
 softmax
 subclassing
 tanh
-torchsummary
+torchsummary
+BatchNorm
+CrossEntropyLoss
+DataLoader
+Dobrescu
+ImageNet
+MCA
+MSE
+RThroughput
+Rin
+SGD
+TorchScript
+argmax
+certifi
+dataloader
+figsize
+hyperparameter
+jit
+matplotlib
+mca
+optim
+preprocess
+preprocessed
+pth
+pyplot
+scheduler's
+torchvision
+uOps
+unsqueeze

README.md

@@ -1,6 +1,6 @@
 The Arm Learning Paths website is available at https://learn.arm.com/
 
-# Arm Learning Paths 
+# Arm Learning Paths  
 
 This repository contains the source files for the Arm Learning Paths static website, serving learning based technical content for Arm software developers. 
 

assets/css/demo.css

@@ -245,6 +245,13 @@
     white-space: pre-wrap;
 }
 
+.char-limit-mesg {
+    font-size: 14px!important;
+    margin-top: 4px;
+    font-style: italic;
+}
+
+
 
 
 #notification-popup {

content/install-guides/cmsis-toolbox.md

@@ -123,26 +123,27 @@ Set environment variables as below. Note the exact name of the `TOOLCHAIN` varia
 | ------------------------------------------ | ------------------------------------- | --------------------------------------------- |
 | `<name>_TOOLCHAIN_<major>_<minor>_<patch>` | Path to toolchain binaries            | `<name>` = `AC6`, `GCC`, `IAR`, or `CLANG`    |
 | `CMSIS_PACK_ROOT`                          | Path to CMSIS-Pack root directory     | Use `cpackget init` to initialize             |
-| `CMSIS_COMPILER_ROOT`                      | Path to CMSIS-Toolbox `etc` directory |                                               |
 | `PATH`                                     | Add CMSIS-Toolbox `bin` to path       | Also path to `CMake` and `Ninja` if necessary |
+| `CMSIS_COMPILER_ROOT`                      | Path to CMSIS-Toolbox `etc` directory | Optional                                      |
+
 
 For example:
 {{< tabpane code=true >}}
   {{< tab header="Windows" language="shell">}}
 set AC6_TOOLCHAIN_6_22_0=%ProgramFiles%/ArmCompilerforEmbedded6.22/bin
 set CMSIS_PACK_ROOT=%LocalAppData%/Arm/Packs
-set CMSIS_COMPILER_ROOT=%UserProfile%/cmsis-toolbox-windows-amd64/etc
 set PATH=%PATH%;%UserProfile%/cmsis-toolbox-windows-amd64/bin
+set CMSIS_COMPILER_ROOT=%UserProfile%/cmsis-toolbox-windows-amd64/etc
   {{< /tab >}}
   {{< tab header="Linux/macOS" language="shell">}}
 export AC6_TOOLCHAIN_6_22_0=$HOME/ArmCompilerforEmbedded6.22/bin
 export CMSIS_PACK_ROOT=$HOME/packs
-export CMSIS_COMPILER_ROOT=$HOME/cmsis-toolbox-linux-arm64/etc
 export PATH=$HOME/cmsis-toolbox-linux-arm64/bin:$PATH
+export CMSIS_COMPILER_ROOT=$HOME/cmsis-toolbox-linux-arm64/etc
   {{< /tab >}}
 {{< /tabpane >}}
 
-Exact paths will depend on version installed and the install directory.
+Exact paths will depend on tools versions installed and their install locations.
 
 ## Initialize CMSIS-Pack directory
 

content/install-guides/topdown-tool.md

@@ -84,13 +84,13 @@ cd telemetry-solution/tools/topdown_tool
 Install `topdown-tool` in `/usr/local/bin` using:
 
 ```console
-pip3 install -e .
+sudo pip3 install -e .
 ```
 
 {{% notice Note %}}
 If you are getting errors on the environment being externally managed, try creating a virtual environment.
 ```
-sudo apt install python3-venv
+sudo apt install python3-venv -y
 python3 -m venv topdown-venv
 source topdown-venv/bin/activate
 pip3 install -e .

content/learning-paths/cross-platform/mca-godbolt/_index.md

@@ -0,0 +1,45 @@
+---
+title: Learn about LLVM Machine Code Analyzer
+
+minutes_to_complete: 60
+
+who_is_this_for: This is an introductory topic for developers who want to diagnose performance issues of Arm programs using LLVM Machine Code Analyzer (MCA) and Compiler Explorer.
+
+learning_objectives:
+    - Estimate the hardware resource pressure and the number of cycles taken to execute your code snippet using llvm-mca.
+    - Describe how this estimate can help diagnose possible performance issues.
+    - Use Compiler Explorer to run llvm-mca.
+
+prerequisites:
+    - Familiarity with Arm assembly.
+    - LLVM version 16 or newer, which includes support for Neoverse V2.
+
+author_primary: Rin Dobrescu
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Neoverse
+    - Cortex-A
+tools_software_languages:
+    - assembly
+    - llvm-mca
+operatingsystems:
+    - Linux
+    - Windows
+    - macOS
+
+### Cross-platform metadata only
+shared_path: true
+shared_between:
+    - servers-and-cloud-computing
+    - laptops-and-desktops
+    - smartphones-and-mobile
+
+### 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/cross-platform/mca-godbolt/_next-steps.md

@@ -0,0 +1,20 @@
+---
+next_step_guidance: >
+    To learn more about performance analysis, proceed to:
+
+recommended_path: /learning-paths/servers-and-cloud-computing/top-down-n1
+
+further_reading:
+    - resource:
+        title: Arm Neoverse V2 Software Optimization Guide
+        link: https://developer.arm.com/documentation/109898/0300/?lang=en
+        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/cross-platform/mca-godbolt/_review.md

@@ -0,0 +1,41 @@
+---
+review:
+    - questions:
+        question: >
+            How can using MCA be useful?
+        answers:
+            - It can provide a performance estimation that can be used to understand and improve performance.
+            - It can provide an improved version of a given code snippet.
+        correct_answer: 1
+        explanation: >
+            MCA simulates the execution of a given snippet of assembly in a loop and provides performance measurements that can then be used to understand and improve performance.
+
+    - questions:
+        question: >
+            MCA can offer performance metrics for the following as input:
+        answers:
+            - A snippet of code, the language does not matter.
+            - A snippet of assembly code.
+        correct_answer: 2
+        explanation: >
+            MCA takes assembly code as input.
+
+    - questions:
+        question: >
+            When using Compiler Explorer, what does llvm-mca take as input?
+        answers:
+            - The source code provided.
+            - The disassembly of the source code.
+        correct_answer: 2
+        explanation: >
+            Compiler explorer takes as input the source code, compiles it and shows the disassembly output. It then can run llvm-mca on the disassembly of the source code.
+
+
+
+# ================================================================================
+#       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/cross-platform/mca-godbolt/background.md

@@ -0,0 +1,33 @@
+---
+title: Background
+weight: 2
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+### Terminology
+
+Before you get started, familiarize yourself with the terms below:
+
+- **Instruction scheduling**: If two instructions appear in a sequence in a program, but are independent from each other, the compiler can swap them without affecting the program's behavior. The goal of instruction scheduling is to find a valid permutation of the program instructions that also optimizes the program's performance, by making use of processor resources.
+
+- **Pipeline**: A pipeline is the mechanism used by the processor to execute instructions. Pipelining makes efficient use of processor resources by dividing instructions into stages that can overlap and be processed in parallel, reducing the time it takes for instructions to execute. Instructions can only be executed if the required data is available, otherwise this leads to a delay in execution called a pipeline stall.
+
+- **Resource pressure**: Resources refer to the hardware units used to execute instructions. If instructions in a program all rely on the same resources, then it leads to pressure. Execution is slowed down as instructions must wait until the unit they need becomes available.
+
+- **Data dependency**: Data dependency refers to the relationship between instructions. When an instruction requires data from a previous instruction this creates a data dependency.
+
+
+### What is Machine Code Analyzer (MCA)?
+
+Machine Code Analyzer (MCA) is a performance analysis tool that uses information available in [LLVM](https://github.com/llvm/llvm-project) to measure performance on a specific CPU.
+
+
+### How can MCA be useful?
+
+MCA takes as input a snippet of assembly code and then simulates the execution of that code in a loop of iterations, and the default is 100. 
+
+MCA then outputs a performance report, which contains information such as the latency and throughput of the assembly block and the resource usage for each instruction. 
+
+Using this information, you can identify bottlenecks in performance such as resource pressure and data dependencies. There are many options you can give MCA to get performance metrics. The options are explained in the [llvm-mca documentation](https://llvm.org/docs/CommandGuide/llvm-mca.html).
+

content/learning-paths/cross-platform/mca-godbolt/mca_on_godbolt.md

@@ -0,0 +1,61 @@
+---
+title: Use MCA with Compiler Explorer
+weight: 4
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+### What is Compiler Explorer?
+
+Compiler Explorer is an interactive online compiler that is compatible with code in C/C++, Java, Python, and many other programming languages. It allows you to see what the code looks like after being compiled in real time. 
+
+Compiler Explorer supports multiple compilers and has many tools available, including `llvm-mca`.
+
+### Running MCA in Compiler Explorer
+
+To access Compiler Explorer, open a browser and go to https://godbolt.org. 
+
+This leads you to the page shown below in Figure 1. Your view might be slightly different. 
+
+![godbolt open alt-text#center](open.png "Figure 1. Compiler Explorer")
+
+The left side of the page contains the source code. In Figure 1, the language is set to C++, but you can click on the programming language to select a different language for the source code. 
+
+Copy the code below and paste it into Compiler Explorer as C++ source code:
+
+```C
+int func(int a, int b, int c, int d, int e, int f) {
+    a = a + b;
+    a = a + c;
+    a = a + d;
+    a = a + e;
+    a = a + f;
+    return a;
+}
+```
+
+The right side of the page contains the disassembly output from the compiler. 
+
+You can change the compiler by clicking on it and selecting a different one. 
+
+Select `armv8-a clang(trunk)` as the compiler to see Arm instructions. 
+
+Next, update the compiler flags by typing `-O3` in the `Compiler options` box. 
+
+You can view the full set of options passed to the compiler by clicking on the green tick next to the compiler. 
+
+Click the `Add tool` drop-down button to add `llvm-mca` as a tool as shown in Figure 2 below:
+
+![tool mca alt-text#center](tool-mca.png "Figure 2. Assembly in Compiler Explorer")
+
+To add more flags to `llvm-mca`, click on the `Arguments` button and type them in. 
+
+Add `-mcpu=neoverse-v2`, as well as any other flags you choose to pass to `llvm-mca`. 
+
+To find what CPUs are supported you can check the [clang documentation](https://clang.llvm.org/docs/CommandGuide/clang.html#cmdoption-print-supported-cpus). 
+
+The right side of the page now contains the output from running `llvm-mca` on the disassembly of the source code, as shown in Figure 3 below:
+
+![argument mca alt-text#center](mca-arguments.png "Figure 3. MCA in Compiler Explorer")
+
+You are now able to run `llvm-mca` using Compiler Explorer. This is helpful when you want to try different compiler versions without installing them.