Arm backend: Update Zephyr example README.md

This move the sample part of the README to the actual sample folder.
This will allow adding more example without bloating the main README

Signed-off-by: Zingo Andersen <Zingo.Andersen@arm.com>
Change-Id: Id8d28cf7cd5eb30949155f324a65d42c065dc6ff

Author: zingo

.ci/scripts/zephyr-utils.sh

@@ -6,14 +6,18 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-# Run instruction from zephyr/README.md
+# Run instruction from a README.md file
 #
-# This contains some CI helper runtime functions to dig out and run commands
-# from zephyr/README.md
-# It also try to verify that zephyr/executorch.yaml is in sync and the snippets
-# in the README are sane with various regexps.
+# This contains CI helper runtime functions to dig out and run commands
+# from a README file.
 #
-# Main functions is run_command_block_from_zephyr_readme it will dig out the code between
+# Generic helper:
+# - run_command_block_from_readme
+#
+# Zephyr-specific validator:
+# - verify_zephyr_readme (checks zephyr/executorch.yaml snippet sync)
+#
+# Main function is run_command_block_from_readme. It digs out the code between
 # the two ''' after a blockheader text and run it
 #
 # .e.g. from this README.md snippet
@@ -26,7 +30,7 @@
 #
 # The blockheader is 'Install requirements' and the code block is 'pip install something ... \npip install something_else'
 # so if we run
-#   run_command_block_from_zephyr_readme 'Install requirements'
+#   run_command_block_from_readme path/to/README.md 'Install requirements'
 # it will run them one by one
 
 
@@ -56,10 +60,22 @@ _zephyr_utils_root_dir () {
     (cd "${script_dir}/../.." && pwd)
 }
 
-_zephyr_utils_readme_path () {
+_utils_path_from_root () {
+  local path="$1"
   local root_dir
+
+  if [[ -z "${path}" || "${path}" == "." ]]; then
+    echo "ERROR: Path argument must be a non-empty file path" >&2
+    return 1
+  fi
+
+  if [[ "${path}" = /* ]]; then
+    printf '%s\n' "${path}"
+    return 0
+  fi
+
   root_dir="$(_zephyr_utils_root_dir)"
-  printf '%s/zephyr/README.md\n' "${root_dir}"
+  printf '%s/%s\n' "${root_dir}" "${path}"
 }
 
 _zephyr_utils_ensure_file () {
@@ -117,28 +133,37 @@ _zephyr_utils_run_simple_commands () {
   return 0
 }
 
-run_command_block_from_zephyr_readme () {
-  local blockheader="$1"
+run_command_block_from_readme () {
+  local readme_path="$1"
+  local blockheader="$2"
+  local block
+
+  if [[ -z "${readme_path}" || -z "${blockheader}" ]]; then
+    echo "ERROR: Usage: run_command_block_from_readme <readme_path> <block_header_regex>" >&2
+    return 1
+  fi
+
+  readme_path="$(_utils_path_from_root "${readme_path}")" || return 1
 
-  echo "Run block '${blockheader}' from zephyr/README.md"
+  echo "Run block '${blockheader}' from ${readme_path}"
 
-  readme_path="$(_zephyr_utils_readme_path)"
   _zephyr_utils_ensure_file "${readme_path}" "README.md" || return 1
 
   block="$(_zephyr_utils_extract_block "${readme_path}" "${blockheader}")"
-
-  if [[ -z "${block}" ]]; then
-    echo "ERROR: Failed to locate ${blockheader} block in ${readme_path}" >&2
-    return 1
+  if [[ -n "${block}" ]]; then
+    _zephyr_utils_run_simple_commands "${block}" "${blockheader}"
+    return $?
   fi
-  _zephyr_utils_run_simple_commands "${block}" "${blockheader}"
+
+  echo "ERROR: Failed to locate ${blockheader} block in ${readme_path}" >&2
+  return 1
 }
 
 # Check that zephyr/executorch.yaml match zephyr/README.md
 verify_zephyr_readme () {
   local readme_path manifest_path snippet
 
-  readme_path="$(_zephyr_utils_readme_path)"
+  readme_path="$(_utils_path_from_root "zephyr/README.md")" || return 1
   manifest_path="$(_zephyr_utils_root_dir)/zephyr/executorch.yaml"
 
   _zephyr_utils_ensure_file "${readme_path}" "README" || return 1

.github/workflows/trunk.yml

@@ -85,6 +85,8 @@ jobs:
         fi
 
         export EXECUTORCH_PROJ_ROOT=$(realpath $(pwd))
+        ZEPHYR_README_PATH="zephyr/README.md"
+        ZEPHYR_SAMPLES_README_PATH="zephyr/samples/hello-executorch/README.md"
 
         # Source utility scripts
         . .ci/scripts/utils.sh
@@ -93,9 +95,9 @@ jobs:
         # check that zephyr/README.md and zephyr/executorch.yaml are in sync
         verify_zephyr_readme
 
-        # Based on instruction in zephyr/README.md
+        # Based on instructions in zephyr/README.md and zephyr/samples/hello-executorch/README.md
 
-        run_command_block_from_zephyr_readme "<!-- RUN install_reqs -->"
+        run_command_block_from_readme "${ZEPHYR_README_PATH}" "<!-- RUN install_reqs -->"
 
         # Make sure to backup the zephyr_scratch folder if it exists to allow for local
         # testing that does not lose code/data
@@ -128,11 +130,11 @@ jobs:
 
         cd ${ZEPHYR_PROJ_ROOT}
 
-        run_command_block_from_zephyr_readme "<!-- RUN west_init -->"
+        run_command_block_from_readme "${ZEPHYR_README_PATH}" "<!-- RUN west_init -->"
 
         cp ${EXECUTORCH_PROJ_ROOT}/zephyr/executorch.yaml zephyr/submanifests/
 
-        run_command_block_from_zephyr_readme "<!-- RUN west_config -->"
+        run_command_block_from_readme "${ZEPHYR_README_PATH}" "<!-- RUN west_config -->"
 
         # Switch to executorch in this PR e.g. replace modules/lib/executorch with the root folder of this repo
         # instead of doing a re-checkout and figure out the correct commit hash etc
@@ -148,9 +150,9 @@ jobs:
           git config --global user.email "github_executorch@arm.com"
         fi
 
-        run_command_block_from_zephyr_readme "<!-- RUN install_executorch -->"
+        run_command_block_from_readme "${ZEPHYR_README_PATH}" "<!-- RUN install_executorch -->"
 
-        run_command_block_from_zephyr_readme "<!-- RUN install_arm_tools -->"
+        run_command_block_from_readme "${ZEPHYR_README_PATH}" "<!-- RUN install_arm_tools -->"
 
         for TARGET in "${TARGETS[@]}"; do
           TARGET="$(echo "$TARGET" | xargs)" # trim whitespace
@@ -168,13 +170,13 @@ jobs:
           fi
 
           echo "---- ${TARGET} Board ${BOARD} FVP setup ----"
-          run_command_block_from_zephyr_readme "<!-- RUN setup_${BOARD}_fvp -->"
+          run_command_block_from_readme "${ZEPHYR_SAMPLES_README_PATH}" "<!-- RUN setup_${BOARD}_fvp -->"
 
           echo "---- ${TARGET} Create PTE ----"
-          run_command_block_from_zephyr_readme "<!-- RUN test_${TARGET}_generate_pte -->"
+          run_command_block_from_readme "${ZEPHYR_SAMPLES_README_PATH}" "<!-- RUN test_${TARGET}_generate_pte -->"
 
           echo "---- ${TARGET} Build and run ----"
-          run_command_block_from_zephyr_readme "<!-- RUN test_${TARGET}_build_and_run -->"
+          run_command_block_from_readme "${ZEPHYR_SAMPLES_README_PATH}" "<!-- RUN test_${TARGET}_build_and_run -->"
         done
 
   test-models-linux-aarch64:

zephyr/README.md

@@ -71,11 +71,11 @@ git submodule update --init --recursive
 cd ../../..
 ```
 
-## Prepare Ethos™-U tools like Vela compiler and Corstone™ 300/320 FVP
+## Prepare Ethos-U tools like Vela compiler and Corstone 300/320 FVP
 
-This is needed to convert python models to PTE files for Ethos™-Ux5 and also installs Corstone™ 300/320 FVP so you can run and test.
+This is needed to convert python models to PTE files for Ethos-Ux5 and also installs Corstone 300/320 FVP so you can run and test.
 
-Make sure to read and agree to the Corstone™ eula
+Make sure to read and agree to the Corstone eula
 
 Install TOSA, vela and FVPs
 <!-- RUN install_arm_tools -->
@@ -84,145 +84,10 @@ modules/lib/executorch/examples/arm/setup.sh --i-agree-to-the-contained-eula
 . modules/lib/executorch/examples/arm/arm-scratch/setup_path.sh
 ```
 
-# Running a sample application
+# Running sample applications
 
-To run you need to point of the path to the installed Corstone&trade; FVP and you can then use west to build and run. You point out the model PTE file you want to run with -DET_PTE_FILE_PATH= see below.
-
-The magic to include and use Ethos-U backend is to set
-CONFIG_ETHOS_U=y/n
-This is done in the example depending on the board you build for so it you build for a different board then the ones below you might want to add a board config file, or add this line to the prj.conf
-
-## Corstone&trade; 300 FVP (Ethos&trade;-U55)
-
-### Setup FVP paths
-
-Set up FVP paths and macs used, this will also set shutdown_on_eot so the FVP auto stops after it has run the example.
-
-Config Zephyr Corstone300 FVP
-<!-- RUN setup_corstone300_fvp -->
-```
-export FVP_ROOT=$PWD/modules/lib/executorch/examples/arm/arm-scratch/FVP-corstone300
-export ARMFVP_BIN_PATH=${FVP_ROOT}/models/Linux64_GCC-9.3
-export ARMFVP_EXTRA_FLAGS="-C mps3_board.uart0.shutdown_on_eot=1 -C ethosu.num_macs=128"
-```
-
-### Ethos-U55
-
-#### Prepare a PTE model file
-
-Prepare the Ethos-U55 PTE model
-<!-- RUN test_ethos-u55_generate_pte -->
-```
-python -m modules.lib.executorch.examples.arm.aot_arm_compiler --model_name=modules/lib/executorch/zephyr/samples/hello-executorch/models/add.py --quantize --delegate --target=ethos-u55-128 --output=add_u55_128.pte
-```
-
-`--delegate` tells the aot_arm_compiler to use Ethos-U backend and `-t ethos-u55-128` specify the used Ethos-U variant and numbers of macs used, this must match you hardware or FVP config.
-
-#### Build and run
-
-Run the Ethos-U55 PTE model
-<!-- RUN test_ethos-u55_build_and_run -->
-```
-west build -b mps3/corstone300/fvp modules/lib/executorch/zephyr/samples/hello-executorch -t run -- -DET_PTE_FILE_PATH=add_u55_128.pte
-```
-
-### Cortex-M55
-
-#### Prepare a PTE model file
-
-Prepare the Cortex-M55 PTE model
-<!-- RUN test_cortex-m55_generate_pte -->
-```
-python -m modules.lib.executorch.examples.arm.aot_arm_compiler --model_name=modules/lib/executorch/zephyr/samples/hello-executorch/models/add.py --quantize --target=cortex-m55+int8 --output=add_m55.pte
-```
-
-`--target=cortex-m55+int8` selects the Cortex-M/CMSIS-NN portable kernel path (no NPU delegation). This produces a `.pte` optimised for Cortex-M55 with INT8 quantisation.
-
-#### Build and run
-
-Run the Cortex-M55 PTE model
-<!-- RUN test_cortex-m55_build_and_run -->
-```
-west build -b mps3/corstone300/fvp modules/lib/executorch/zephyr/samples/hello-executorch -t run -- -DET_PTE_FILE_PATH=add_m55.pte
-```
-
-## Corstone&trade; 320 FVP (Ethos&trade;-U85)
-
-### Setup FVP paths
-
-Set up FVP paths, libs and macs used, this will also set shutdown_on_eot so the FVP auto stops after it has run the example.
-
-Config Zephyr Corstone320 FVP
-<!-- RUN setup_corstone320_fvp -->
-```
-export FVP_ROOT=$PWD/modules/lib/executorch/examples/arm/arm-scratch/FVP-corstone320
-export ARMFVP_BIN_PATH=${FVP_ROOT}/models/Linux64_GCC-9.3
-export LD_LIBRARY_PATH=${FVP_ROOT}/python/lib:${ARMFVP_BIN_PATH}:${LD_LIBRARY_PATH}
-export ARMFVP_EXTRA_FLAGS="-C mps4_board.uart0.shutdown_on_eot=1 -C mps4_board.subsystem.ethosu.num_macs=256"
-```
-
-### Ethos-U85
-
-#### Prepare a PTE model file
-
-Prepare the Ethos-U85 PTE model
-<!-- RUN test_ethos-u85_generate_pte -->
-```
-python -m modules.lib.executorch.examples.arm.aot_arm_compiler --model_name=modules/lib/executorch/zephyr/samples/hello-executorch/models/add.py --quantize --delegate --target=ethos-u85-256 --output=add_u85_256.pte
-```
-
-`--delegate` tells the aot_arm_compiler to use Ethos-U backend and `-t ethos-u85-256` specify the used Ethos-U variant and numbers of macs used, this must match you hardware or FVP config.
-
-#### Build and run
-
-Run the Ethos-U85 PTE model
-<!-- RUN test_ethos-u85_build_and_run -->
-```
-west build -b mps4/corstone320/fvp modules/lib/executorch/zephyr/samples/hello-executorch -t run -- -DET_PTE_FILE_PATH=add_u85_256.pte
-```
-
-## STM Nucleo n657x0_q
-
-### Run west config and update:
-
-You need to add hal_stm32 driver to Zephyr
-```
-west config manifest.project-filter -- -.*,+zephyr,+executorch,+cmsis,+cmsis_6,+cmsis-nn,+hal_stm32
-west update
-```
-
-### Setup tools
-
-Follow and make sure tools are setup according to this:
-
-https://docs.zephyrproject.org/latest/boards/st/nucleo_n657x0_q/doc/index.html
-
-Test the samples/hello_world in that guide to make sure all tools work.
-
-Please note that the ZephyrOS made a fix for the signing tool version v2.21.0 after the v4.3 release in 20 Nov 2025. Make sure to use a later version of ZephyrOS that contains it.
-Also note that the signing tool must be in your path for it to auto sign your elf.
-
-```
-export PATH=$PATH:~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin
-```
-
-### Prepare a PTE model file
-
-Prepare the Cortex-M55 PTE model
-```
-python -m modules.lib.executorch.examples.arm.aot_arm_compiler --model_name=modules/lib/executorch/zephyr/samples/hello-executorch/models/add.py --quantize --target=cortex-m55+int8 --output=add_m55.pte
-```
-
-`--target=cortex-m55+int8` selects the Cortex-M/CMSIS-NN portable kernel path (no NPU delegation).
-
-#### Build and run
-
-Run the Cortex-M55 PTE model
-```
-west build -b nucleo_n657x0_q modules/lib/executorch/zephyr/samples/hello-executorch -- -DET_PTE_FILE_PATH=add_m55.pte
-west flash
-```
-This will run the simple add model on your hardware one and print the output on the serial consol.
+Build and run instructions for simple Zephyr minimal example setup is documented in
+[`zephyr/samples/hello-executorch/README.md`](samples/hello-executorch/README.md).
 
 ## Notable files