Adding new learning path: visualizing-ethos-u-performance

assets/contributors.csv

@@ -91,3 +91,4 @@ Gian Marco Iodice,Arm,,,,
 Aude Vuilliomenet,Arm,,,,
 Andrew Kilroy,Arm,,,,
 Peter Harris,Arm,,,,
+Waheed Brown,Arm,https://github.com/armwaheed,https://www.linkedin.com/in/waheedbrown/,,

content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/1-overview.md

@@ -0,0 +1,25 @@
+---
+title: Overview
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Visualizing ML on Embedded Devices
+
+Selecting the best hardware for machine learning (ML) models depends on effective tools. You can visualize ML performance early in the development cycle by using Arm [Fixed Virtual Platforms](https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms) (FVPs).
+
+## TinyML
+
+This Learning Path uses TinyML. TinyML is machine learning tailored to function on devices with limited resources, constrained memory, low power, and fewer processing capabilities.
+
+For a learning path focused on creating and deploying your own TinyML models, please see [Introduction to TinyML on Arm using PyTorch and ExecuTorch](/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/)
+
+## Benefits and applications
+
+New products, like Arm's [Ethos-U85](https://www.arm.com/products/silicon-ip-cpu/ethos/ethos-u85) NPU are available on FVPs earlier than on physical devices. FVPs also have a graphical user iterface (GUI), which is useful for for ML performance visualization due to:
+- visual confirmation that your ML model is running on the desired device,
+- clearly indicated instruction counts,
+- confirmation of total execution time and
+- visually appealing output for prototypes and demos.

content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/2-env-setup.md

@@ -0,0 +1,78 @@
+---
+# User change
+title: "Install ExecuTorch"
+
+weight: 3
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+In this section, you will prepare a development environment to compile a machine learning model.
+
+## Introduction to ExecuTorch
+
+ExecuTorch is a lightweight runtime designed for efficient execution of PyTorch models on resource-constrained devices. It enables machine learning inference on embedded and edge platforms, making it well-suited for Arm-based hardware. Since Arm processors are widely used in mobile, IoT, and embedded applications, ExecuTorch leverages Arm's efficient CPU architectures to deliver optimized performance while maintaining low power consumption. By integrating with Arm's compute libraries, it ensures smooth execution of AI workloads on Arm-powered devices, from Cortex-M microcontrollers to Cortex-A application processors.
+
+## Install dependencies
+
+These instructions have been tested on Ubuntu 22.04, 24.04, and on Windows Subsystem for Linux (WSL).
+
+Python3 is required and comes installed with Ubuntu, but some additional packages are needed:
+
+```bash
+sudo apt update
+sudo apt install python-is-python3 python3-dev python3-venv gcc g++ make -y
+```
+
+## Create a virtual environment
+
+Create a Python virtual environment using `python venv`:
+
+```console
+python3 -m venv $HOME/executorch-venv
+source $HOME/executorch-venv/bin/activate
+```
+The prompt of your terminal now has `(executorch)` as a prefix to indicate the virtual environment is active.
+
+
+## Install Executorch
+
+From within the Python virtual environment, run the commands below to download the ExecuTorch repository and install the required packages:
+
+``` bash
+cd $HOME
+git clone https://github.com/pytorch/executorch.git
+cd executorch
+```
+
+Run the commands below to set up the ExecuTorch internal dependencies:
+
+```bash
+git submodule sync
+git submodule update --init
+./install_executorch.sh
+```
+
+{{% notice Note %}}
+If you run into an issue of `buck` running in a stale environment, reset it by running the following instructions:
+
+```bash
+ps aux | grep buck
+pkill -f buck
+```
+{{% /notice %}}
+
+After running the commands, `executorch` should be listed upon running `pip list`:
+
+```bash
+pip list | grep executorch
+```
+
+```output
+executorch         0.6.0a0+3eea1f1
+```
+
+## Next Steps
+
+Proceed to the next section to learn about and set up the virtualized hardware.

content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/3-env-setup-fvp.md

@@ -0,0 +1,52 @@
+---
+# User change
+title: "Set up the Corstone-320 FVP on Linux"
+
+weight: 4 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+In this section, you will run scripts to set up the Corstone-320 reference package.
+
+The Corstone-320 Fixed Virtual Platform (FVP) is a pre-silicon software development environment for Arm-based microcontrollers. It provides a virtual representation of hardware, allowing developers to test and optimize software before actual hardware is available. Designed for AI and machine learning workloads, it includes support for Arm's Ethos-U NPU and Cortex-M processors, making it ideal for embedded AI applications. The FVP accelerates development by enabling early software validation and performance tuning in a flexible, simulation-based environment.
+
+The Corstone reference system is provided free of charge, although you will have to accept the license in the next step. For more information on Corstone-320, check out the [official documentation](https://developer.arm.com/documentation/109761/0000?lang=en).
+
+## Corstone-320 FVP Setup for ExecuTorch
+
+{{% notice macOS %}}
+
+Setting up FVPs on MacOS requires some extra steps, outlined in GitHub repo [VPs-on-Mac](https://github.com/Arm-Examples/FVPs-on-Mac/). macOS users must do this first, before setting up the Corestone-320 FVP.
+
+{{% /notice %}}
+
+Navigate to the Arm examples directory in the ExecuTorch repository. Run the following command.
+
+```bash
+cd $HOME/executorch/examples/arm
+./setup.sh --i-agree-to-the-contained-eula
+```
+
+After the script has finished running, it prints a command to run to finalize the installation. This step adds the FVP executables to your system path.
+
+```bash
+source $HOME/executorch/examples/arm/ethos-u-scratch/setup_path.sh
+```
+
+Test that the setup was successful by running the `run.sh` script for Ethos-U85, which is the target device for Corstone-320:
+
+{{% notice macOS %}}
+
+**Start Docker:** on macOS, FVPs run inside a Docker container.
+
+{{% /notice %}}
+
+```bash
+ ./examples/arm/run.sh --target=ethos-u85-256
+```
+
+You will see a number of examples run on the FVP.
+
+This confirms the installation, so you can now proceed to the Learning Path [Build a Simple PyTorch Model](/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/4-build-model/).

content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/4-how-executorch-works.md

@@ -0,0 +1,57 @@
+---
+# User change
+title: "How ExecuTorch Works"
+
+weight: 5 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+Source: [How ExecuTorch Works](https://docs.pytorch.org/executorch/stable/intro-how-it-works.html) (official PyTorch Documentation)
+1. **Export the model:**
+   * Generate a Graph
+   * A graph is series of operators (ReLU, quantize, etc.) eligible for delegation to an accelerator
+   * Your goal is to identify operators for acceleration on the Ethos-U NPU
+2. **Compile to ExecuTorch:**
+   * This is the ahead-of-time compiler
+   * This is why ExecuTorch inference is faster than PyTorch inference
+   * Delegate operators to an accelerator, like the Ethos-U NPU
+3. **Run on targeted device:**
+   * Deploy the ML model to the Fixed Virtual Platform (FVP) or physical device
+   * Execute operators on the CPU and delegated operators on the Ethos-U NPU
+
+**Diagram of How ExecuTorch Works**
+![How ExecuTorch works](./how-executorch-works-high-level.png)
+
+## Deploy a TinyML Model
+
+With your development environment set up, you can deploy a simple PyTorch model.
+
+This example deploys the [MobileNet V2](https://pytorch.org/hub/pytorch_vision_mobilenet_v2/) computer vision model. The model is a convolutional neural network (CNN) that extracts visual features from an image. It is used for image classification and object detection.
+
+The actual Python code for the MobileNet V2 model is in your local `executorch` repo: [executorch/examples/models/mobilenet_v2/model.py](https://github.com/pytorch/executorch/blob/main/examples/models/mobilenet_v2/model.py). You can deploy it using [run.sh](https://github.com/pytorch/executorch/blob/main/examples/arm/run.sh), just like you did in the previous step, with some extra parameters:
+
+{{% notice macOS %}}
+
+**Start Docker:** on macOS, FVPs run inside a Docker container.
+
+{{% /notice %}}
+
+```bash
+./examples/arm/run.sh \
+--aot_arm_compiler_flags="--delegate --quantize --intermediates mv2_u85/ --debug --evaluate" \
+--output=mv2_u85 \
+--target=ethos-u85-128 \
+--model_name=mv2
+```
+
+**Explanation of run.sh Parameters**
+|run.sh Parameter|Meaning / Context|
+|--------------|-----------------|
+|--aot_arm_compiler_flags|Passes a string of compiler options to the ExecuTorch Ahead-of-Time (AOT) compiler|
+|--delegate|Enables backend delegation|
+|--quantize|Converts the floating-point model to int8 quantized format using post-training quantization<br>**Essential for running on NPUs**|
+|--intermediates mv2_u85/|Directory where intermediate files (e.g., TOSA, YAMLs, debug graphs) will be saved<br>Useful output files for **manual debugging**|
+|--debug|Verbose debugging logging|
+|--evaluate|Validates model output, provides timing estimates|

content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/5-configure-fvp-gui.md

@@ -0,0 +1,94 @@
+---
+# User change
+title: "Configure the FVP GUI (optional)"
+
+weight: 6 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+## Find your IP address
+
+Note down your computer's IP address:
+```bash
+ip addr show <YOUR_INTERFACE_NAME>
+```
+To help you, here are some common WiFi interface names on Linux:
+|Interface Name|Meaning / Context|
+|--------------|-----------------|
+|wlan0|Legacy name (common on older systems)|
+|wlp2s0, wlp3s0|Predictable network naming scheme (modern systems)|
+|wlx<MAC>|Some systems name interfaces after MAC addresses|
+|wifi0, ath0|Very rare, specific to certain drivers (e.g., Atheros)|
+
+{{% notice macOS %}}
+
+Note down your `en0` IP address (or whichever network adapter is active):
+
+```bash
+ipconfig getifaddr en0 # Returns your Mac's WiFi IP address
+```
+
+{{% /notice %}}
+
+## Enable the FVP's GUI
+
+Edit the following parameters in [run_fvp.sh](https://github.com/pytorch/executorch/blob/d5fe5faadb8a46375d925b18827493cd65ec84ce/backends/arm/scripts/run_fvp.sh#L97-L102), to enable the Mobilenet V2 output on the FVP's GUI:
+
+```bash
+-C mps4_board.subsystem.ethosu.num_macs=${num_macs} \
+-C mps4_board.visualisation.disable-visualisation=1 \
+-C vis_hdlcd.disable_visualisation=1                \
+-C mps4_board.telnetterminal0.start_telnet=0        \
+-C mps4_board.uart0.out_file='-'                    \
+-C mps4_board.uart0.shutdown_on_eot=1               \
+```
+
+- Change `mps4_board.visualisation.disable-visualisation` to equal `0`
+- Change `vis_hdlcd.disable_visualisation` to equal `0`
+- Enter a `--display-ip` parameter and set it to your computer's IP address
+
+```bash
+-C mps4_board.subsystem.ethosu.num_macs=${num_macs} \
+-C mps4_board.visualisation.disable-visualisation=0 \
+-C vis_hdlcd.disable_visualisation=0                \
+-C mps4_board.telnetterminal0.start_telnet=0        \
+-C mps4_board.uart0.out_file='-'                    \
+-C mps4_board.uart0.shutdown_on_eot=1               \
+--display-ip <YOUR_IP_ADDRESS>                   \
+```
+
+## Deploy the model
+
+{{% notice macOS %}}
+
+- **Start Docker:** on macOS, FVPs run inside a Docker container.
+
+  **Do not use Colima Docker!**
+
+  - Make sure to use an [official version of Docker](https://www.docker.com/products/docker-desktop/) and not a free version like the [Colima](https://github.com/abiosoft/colima?tab=readme-ov-file) Docker container runtime
+  - `run.sh` assumes Docker Desktop style networking (`host.docker.internal`) which breaks with Colima
+  - Colima then breaks the FVP GUI
+
+- **Start XQuartz:** on macOS, the FVP GUI runs using XQuartz.
+
+  Start the xquartz.app and then configure XQuartz so that the FVP will accept connections from your Mac and localhost:
+  ```bash
+  xhost + <YOUR_IP_ADDRESS>
+  xhost + 127.0.0.1 # The Docker container seems to proxy through localhost
+  ```
+{{% /notice %}}
+
+Now run the Mobilenet V2 computer vision model, using [executorch/examples/arm/run.sh](https://github.com/pytorch/executorch/blob/main/examples/arm/run.sh):
+```bash
+./examples/arm/run.sh \
+--aot_arm_compiler_flags="--delegate --quantize --intermediates mv2_u85/ --debug --evaluate" \
+--output=mv2_u85 \
+--target=ethos-u85-128 \
+--model_name=mv2
+```
+
+Observe that the FVP loads the model file, compiles the PyTorch model to ExecuTorch `.pte` format and then shows an instruction count in the top right of the GUI:
+
+![Terminal and FVP output](./Terminal%20and%20FVP%20Output.jpg)