Merge pull request #1281 from ArmDeveloperEcosystem/main

Merge to production

Author: pareenaverma

.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).
+