pull request for zephyr executorch application in cs320 MPS4 platform

content/learning-paths/embedded-and-microcontrollers/zephyr_ml_cs320_mps4/_index.md

@@ -0,0 +1,69 @@
+---
+title: Deploying a Zephyr-Based ML Application on the Arm Corstone-320 MPS4 Platform with ExecuTorch
+
+minutes_to_complete: 45
+
+who_is_this_for: This is an introductory topic for embedded software developers who want to deploy a Zephyr-based ML Application on the Arm Corstone-320 MPS4 Platform with ExecuTorch.
+
+learning_objectives: 
+    - Set up a Zephyr ML application development environment for Corstone-320 MPS4.
+    - Pre-process the model for NPU delegate.
+    - Create and build Zephyr ML applications.
+    - Run ML inference on the Corstone-320 MPS4 platform.
+
+prerequisites:
+    - Basic familiarity with embedded C programming
+    - Refer to [Port Zephyr RTOS and run applications on the Arm Corstone-320 MPS4 platform](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/zephyr_cs320_mps4/) to get knowledge of Zephyr RTOS in Arm Corstone-320 MPS4 Platform.
+    - Familiarity with basic machine learning concepts
+    - A Corstone-320 MPS4 FPGA development board
+    - A Linux development environment, for example Ubuntu 22.04 or later
+    - Git and Python
+
+
+author: Sue Wu
+
+### Tags
+skilllevels: Introductory
+subjects: RTOS Fundamentals
+armips:
+  - Cortex-M
+  - Ethos-U
+tools_software_languages:
+  - Zephyr
+  - Executorch
+  - GCC
+  - C
+operatingsystems:
+  - Linux
+
+
+further_reading:
+  - resource:
+      title: Zephyr Project documentation
+      link: https://docs.zephyrproject.org/latest/index.html
+      type: website
+  - resource:
+      title: ExecuTorch sample applications
+      link: https://github.com/pytorch/executorch/tree/main/zephyr/samples
+      type: website
+  - resource:
+      title: Arm Corstone SSE-320 FPGA image for MPS4 (FI101)
+      link: https://developer.arm.com/downloads/view/FI101
+      type: website
+  - resource:
+      title: SSE-320 FPGA image for MPS4 application note
+      link: https://developer.arm.com/documentation/109762/0100/?lang=en
+      type: website
+  - resource:
+      title: Arm MPS4 FPGA prototyping board technical reference manual
+      link: https://developer.arm.com/documentation/102577/latest/
+      type: website
+
+
+
+### 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/embedded-and-microcontrollers/zephyr_ml_cs320_mps4/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # The weight controls the order of the pages. _index.md always has weight 1.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

content/learning-paths/embedded-and-microcontrollers/zephyr_ml_cs320_mps4/how-to-1.md

@@ -0,0 +1,110 @@
+---
+title: Set up the platform and software
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Platform and Software Setup
+
+The Arm Corstone SSE-320 FPGA image for MPS4 (FI101) is an FPGA implementation that runs on the MPS4 board. The image includes an Arm Cortex-M85 processor, an Arm Ethos-U85 NPU, and a range of peripheral components. It provides a practical hardware platform for developing and evaluating machine learning applications.
+
+Download the latest Corstone-320 FPGA image and review the platform documentation:
+
+- [Arm Corstone SSE-320 with Cortex-M85 and Ethos-U85: Example FPGA (FI101)](https://developer.arm.com/downloads/view/FI101)
+- [SSE-320 FPGA Image for MPS4 Application Note](https://developer.arm.com/documentation/109762/0100/?lang=en)
+- [Arm MPS4 FPGA Prototyping Board Technical Reference Manual](https://developer.arm.com/documentation/102577/latest/)
+- [Arm Corstone SSE-320 Example Subsystem Software Programmers Guide](https://developer.arm.com/documentation/109759/latest/)
+
+
+This section describes the software and development environment that you need to deploy a Zephyr-based machine learning application on this platform.
+
+### Zephyr workspace and board target set up
+
+Follow the [Port Zephyr RTOS and run applications on the Arm Corstone-320 MPS4 platform ](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/zephyr_cs320_mps4/how-to-1/) to set up the Zephyr workspace for the Arm Corstone-320 MPS4 platform. The Zephyr version used is V4.3.0.
+
+### ExecuTorch integration in the Zephyr tree
+
+ExecuTorch is integrated into the Zephyr workspace as an external module located in `modules/lib/executorch`. The module provides the ExecuTorch runtime, the Arm backend, the Ethos-U delegate, build scripts, and sample applications. You can build the sample applications using the Zephyr build system.
+
+To add ExecuTorch as a Zephyr module, create `executorch.yaml` in `zephyr/submanifests` with the following content:
+
+```yaml
+manifest:
+  projects:
+    - name: executorch
+      url: https://github.com/pytorch/executorch
+      revision: main
+      path: modules/lib/executorch
+```
+
+Run the following commands to fetch the ExecuTorch repository and its submodules. The commands place the ExecuTorch source tree in `modules/lib/executorch`.
+
+```bash
+west update
+cd modules/lib/executorch
+git submodule sync
+git submodule update --init --recursive
+./install_executorch.sh
+```
+
+
+### Set up the Arm/Ethos-U toolchain
+ExecuTorch includes a setup script that downloads the Arm GNU Toolchain, the TOSA Serialization Library, the Ethos-U Vela graph compiler, and other utilities.
+
+Run the following commands to download, install, and configure these tools on your system.
+
+```bash
+./examples/arm/setup.sh --i-agree-to-the-contained-eula
+source modules/lib/executorch/examples/arm/arm-scratch/setup_path.sh
+```
+
+## Pre-process the PyTorch Model for NPU delegation 
+The ExecuTorch [Ahead-of-Time (AOT)](https://github.com/pytorch/executorch/blob/main/examples/arm/aot_arm_compiler.py) pipeline takes a PyTorch Model (a torch.nn.Module) and produces a .pte binary file. The ExecuTorch runtime uses this file for inference.
+
+The following example shows a simple PyTorch model, `add.py`, that performs a single addition.
+
+```python
+import torch
+
+b = 2
+
+class myModelAdd(torch.nn.Module):
+    def __init__(self):
+        super().__init__()
+
+    def forward(self, x):
+        return x + x + b
+
+
+ModelUnderTest = myModelAdd()
+ModelInputs = (torch.ones(5),)
+```
+Run the following commands to quantize the model and export it through the Ahead-of-Time (AOT) flow using the Ethos-U backend.
+
+```bash
+source ~/zephyrproject/.venv/bin/activate
+python3 -m executorch.backends.arm.scripts.aot_arm_compiler \
+  --model_name=examples/arm/example_modules/add.py \
+  -t ethos-u85-1024 \
+  --delegate \
+  --quantize \
+  --memory_mode=Sram_Only \
+  -o add_u85_1024_sram_only.pte
+```
+**Key parameters:**
+
+| Parameter | Value | Notes |
+|-----------|-------|-------|
+| `--model_name` | path to `.py` model file | Use absolute or workspace-relative path |
+| `-t` / `--target` | `ethos-u85-1024` | Must match `CONFIG_ETHOS_U85_1024=y` in Kconfig |
+| `--delegate` | (flag) | Enables Ethos-U NPU delegation via ArmBackend |
+| `--quantize` | (flag) | Applies INT8 symmetric quantisation |
+| `--memory_mode` | `Shared_Sram` or `Sram_Only` | Vela memory layout; must match the runtime build |
+| `--system_config` | `Ethos_U85_SYS_DRAM_Mid` | Optional; selects Vela system config from `vela.ini` |
+| `-o` | output filename | Saved in the project root by default |
+
+The `add_u85_1024_sram_only.pte` file contains the model graph, quantized weights, and a Vela-compiled command stream. The Ethos-U85 executes the command stream directly.
+
+

content/learning-paths/embedded-and-microcontrollers/zephyr_ml_cs320_mps4/how-to-2.md

@@ -0,0 +1,150 @@
+---
+title: Deoploy ML applicaton in the Corstone-320 MPS4 platform
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Port hello-executorch for mps4/corstone320/fpga platform
+
+[hello-executorch](https://github.com/pytorch/executorch/tree/main/zephyr/samples/hello-executorch) is a ML sample application in ExecuTorch. It deploys a model using the ExecuTorch runtime. We port the application to the Corstone-320 MPS4 platform to validate the ML application workflow on this platform.
+
+### Change NPU region configuration settings for the project
+The `ethosu_config_select()` function is a weak function defined in the Ethos-U driver file `ethosu_device_u85.c`. It configures the `QCONFIG` and `REGIONCFG` registers for the Ethos-U85.
+
+Because the model is preprocessed in SRAM-only mode, all command streams, weights, and scratch data must reside in SRAM on the Corstone-320 platform. Therefore, we override `ethosu_config_select()` in the application to configure the AXI regions for the command stream and memory regions required by SRAM-only mode.
+
+Create a new file, `ethosu_config_corstone320.c`, in the `hello-executorch/src` directory with the following content:
+
+```C
+unsigned int ethosu_config_select(uint64_t address, int index)
+{
+    (void)(address);  /* Not used in fixed configuration */
+
+    assert(index >= -1 && index <= 7);
+
+    switch (index)
+    {
+    case -1:
+        /* QCONFIG: Command stream uses region 1 (SRAM path). Value = 1 */
+        return 1;
+
+    case 0:
+        /* REGIONCFG_0: Read-only data region uses SRAM. Value = 1 */
+        return 1;
+
+    case 1:
+      /* REGIONCFG_1: scratch/input/output buffer uses SRAM via MEM_ATTR[0]. */
+        return 0；
+    case 2:
+     /* REGIONCFG_2: fast scratch uses SRAM via MEM_ATTR[0]. */
+        return 0;
+    case 3:
+    case 4:
+    case 5:
+    case 6:
+    case 7:
+        /* Other regions are not used by this model; keep them on SRAM. */
+        return 0;
+
+    default:
+        /* Should not reach here due to assert */
+        return 0;
+    }
+}
+```
+
+add the `ethosu_config_corstone320.c` in the CMakeLists.txt as follows
+
+```makefile
+set(app_sources
+    src/arm_executor_runner.cpp
+    src/ethosu_config_corstone320.c
+    ${EXECUTORCH_DIR}/examples/arm/executor_runner/arm_memory_allocator.cpp
+)
+```
+
+
+### Add the zephyr configuration files for MPS4 CS320 platform
+
+Create the board-specific Kconfig file `boards/mps4_corstone320_fpga.conf` and add the following content:
+
+```
+CONFIG_ETHOS_U=y
+CONFIG_ETHOS_U85_1024=y
+CONFIG_EXECUTORCH_METHOD_ALLOCATOR_POOL_SIZE=1048576
+CONFIG_EXECUTORCH_TEMP_ALLOCATOR_POOL_SIZE=32768
+```
+Add the following settings to `prj.conf` to enable logging:
+
+```
+CONFIG_LOG=y
+CONFIG_LOG_MODE_IMMEDIATE=y
+CONFIG_LOG_DEFAULT_LEVEL=3
+CONFIG_CONSOLE=y
+CONFIG_SERIAL=y
+CONFIG_UART_CONSOLE=y
+CONFIG_PRINTK=y
+
+CONFIG_ASSERT=y
+CONFIG_FAULT_DUMP=2
+```
+
+### Build the project 
+
+Build the `hello-executorch` application by following these steps:
+
+1. Activate the Python virtual environment for Zephyr.
+2. Set the toolchain environment variables. Replace `<toolchain_install_path>` with the directory where you installed the Arm GNU Toolchain.
+
+```bash
+	export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
+	export GNUARMEMB_TOOLCHAIN_PATH=arm-gnu-toolchain-13.2.Rel1-x86_64-arm-none-eabi install path/
+```
+3. Build the sample application for the Corstone-320 FPGA variant:
+
+```bash
+west build -p always \
+  -b mps4/corstone320/fpga \
+  -d build_hello_et_fpga \
+  modules/lib/executorch/zephyr/samples/hello-executorch \
+  -- -DET_PTE_FILE_PATH=add_u85_1024_sram_only.pte
+  -DSYSTEM_CONFIG=Ethos_U85_SYS_DRAM_Mid \
+  -DMEMORY_MODE=Sram_Only
+```
+
+After a successful build, the output file `zephyr.elf` is available in `build_hello_et_fpga/zephyr/`.
+The ELF image contains the Zephyr kernel, the Ethos-U driver, the ExecuTorch runtime, the generated `.pte` file, and the ML application.
+
+
+### Run the application on the MPS4 board
+1. Download the board files from [FI101](https://developer.arm.com/downloads/view/FI101?sortBy=availableBy&revision=r1p0-00eac0-2), 
+2. Set up the MPS4 platform according to the [Using the FI101 on MPS4 board](https://developer.arm.com/documentation/109762/0100/?lang=en).
+
+For the `hello-executorch` application, place the vector table in the FPGA boot ROM at address 0x11000000, and place the remaining code and data in SRAM at address 0x31000000. Create vector.bin and app.bin from zephyr.elf by using arm-none-eabi-objcopy.
+
+Update images.txt under /MB/HBI0376B/FI101 to load the two images:
+
+```
+IMAGE0PORT: 2
+IMAGE0ADDRESS: 0x00_1100_0000           ; Address to load into
+IMAGE0UPDATE: RAM                       
+IMAGE0FILE: \SOFTWARE\vector.bin        ; Image/data to be loaded
+
+IMAGE1PORT: 1
+IMAGE1ADDRESS: 0x31000000               ; Address to load into
+IMAGE1UPDATE: RAM
+IMAGE1FILE: \SOFTWARE\app.bin           ; Image/data to be loaded
+
+```
+
+Copy vector.bin and app.bin to \SOFTWARE, then power on the board.
+If the setup is correct, the UART console prints the model delegate flow, similar to the following example:
+
+ ![alt text](image.png)   
+
+## What you accomplished
+In this Learning Path, you learned how to deploy a Zephyr-based ML application on the Arm Corstone-320 MPS4 platform using ExecuTorch. You learned how to preprocess a model for Ethos-U NPU delegation, develop a Zephyr-based ML application, and integrate the ExecuTorch runtime.
+
+These steps help you validate ML applications on the platform and provide a foundation for developing more advanced ML workloads.