From 1935c6d34d29d823c30a036183a5952664fcbf5f Mon Sep 17 00:00:00 2001 From: JeffMboya Date: Wed, 18 Dec 2024 13:17:17 +0300 Subject: [PATCH 1/5] Add zephyr set-up docs Signed-off-by: JeffMboya --- docs/zephyr-setup.md | 300 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 300 insertions(+) create mode 100644 docs/zephyr-setup.md diff --git a/docs/zephyr-setup.md b/docs/zephyr-setup.md new file mode 100644 index 0000000..b15e6d5 --- /dev/null +++ b/docs/zephyr-setup.md @@ -0,0 +1,300 @@ +# Setting Up Zephyr with ESP-IDF for ESP32 + +### **1. Set Up Zephyr Development Environment** + +#### Install Dependencies on your development machine + +1. Update your system: + + ```bash + sudo apt update + sudo apt upgrade + ``` + +2. Install the required tools: + + ```bash + sudo apt install --no-install-recommends git cmake ninja-build gperf \ + ccache dfu-util device-tree-compiler wget \ + python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ + make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1 + ``` + +3. Verify tool versions: + ```bash + cmake --version + python3 --version + dtc --version + ``` + Ensure versions meet the minimum requirements: CMake 3.20.5, Python 3.10, and Devicetree Compiler 1.4.6. + +#### Get Zephyr and Python Dependencies on your development machine + +1. Create a Zephyr workspace and clone the repository: + + ```bash + west init ~/zephyrproject + cd ~/zephyrproject + west update + ``` + +2. Set up a Python virtual environment: + + ```bash + sudo apt install python3-venv + python3 -m venv ~/zephyrproject/.venv + source ~/zephyrproject/.venv/bin/activate + pip install west + ``` + +3. Export Zephyr CMake package: + + ```bash + west zephyr-export + ``` + +4. Install Python dependencies: + + ```bash + west packages pip --install + ``` + +5. Install the Zephyr SDK: + + ```bash + cd ~/zephyrproject/zephyr + west sdk install + ``` + +6. Fetch Espressif binary blobs: + + ```bash + west blobs fetch hal_espressif + ``` + + The `ZEPHYR_BASE` variable is required to locate Zephyr's core build system, CMake scripts, and modules. Without it, the Zephyr tools (west) will fail to build applications. Confirm the `ZEPHYR_BASE` Environment Variable + + ```bash + echo $ZEPHYR_BASE + ``` + + If It’s Not Set: + +- Activate your Zephyr virtual environment: + + ```bash + source ~/zephyrproject/.venv/bin/activate + ``` + +- Set the ZEPHYR_BASE variable: + + ```bash + export ZEPHYR_BASE=~/zephyrproject/zephyr + ``` + + To make it peremanent, add the following line to your shell configuration file (`.bashrc` or `.zshrc`): + + ```bash + export ZEPHYR_BASE=/home/jeff/zephyrproject/zephyr + ``` + + For more detailed information, refer to the official [Zephyr Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). + +--- + +### **2. Install ESP-IDF on your development machine** + +Do not install ESP-IDF inside the Zephyr virtual environment. ESP-IDF is a separate development framework with its own setup and toolchain requirements, which should be installed and managed globally or in its own isolated environment. Global Installation (Preferred). This way, its tools and environment are available for any project on the ESP32, including Zephyr. + +Without ESP-IDF: + +- You cannot compile or flash code for the ESP32. +- Zephyr won’t be able to recognize or support the ESP32-S3 during build or runtime. + +#### Option 1: Using VS Code Extension (Recommended) + +1. Install the ESP-IDF extension: + + - Navigate to **View > Extensions** in VS Code. + - Search for "ESP-IDF Extension" and install it. + +2. Configure the ESP-IDF extension: + + - Open **Command Palette** (`Ctrl+Shift+P` or `Cmd+Shift+P`). + - Run `ESP-IDF: Configure ESP-IDF Extension`. + - Follow the setup wizard to download and install ESP-IDF. + +3. Ensure correct paths for IDF: + + - Set `IDF_PATH` and `IDF_TOOLS_PATH` appropriately (default: `$HOME/.espressif`). + +4. Add OpenOCD rules for Linux. The command typically looks like: + + ```bash + sudo cp --update=none /home//.espressif/tools/openocd-esp32//share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/ + ``` + + then reload udev rules to apply the changes: + + ```bash + sudo udevadm control --reload-rules + sudo udevadm trigger + ``` + + For more detailed information, refer to the official [ESP-IDF Extension Guide](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/installation.html). + +#### Option 2: Manual Installation + +1. Download ESP-IDF: + + ```bash + mkdir -p ~/esp + cd ~/esp + wget https://github.com/espressif/esp-idf/releases/download/v5.3.2/esp-idf-v5.3.2.zip + unzip esp-idf-v5.3.2.zip -d v5.3.2 + ``` + + Ensure the directory structure is correct after unzipping. The export script requires paths to be consistent. + +2. Export the ESP-IDF environment: + + ```bash + source ~/esp/v5.3.2/esp-idf/export.sh + ``` + + Run this command in every new terminal session, or automate it by adding the export command to your shell's startup script (~/.bashrc, ~/.zshrc, etc.). + +3. Verify the installation: + + Check the installed ESP-IDF version: + + ```bash + idf.py --version + + ``` + + If the `idf.py` command fails with `command not found`, source the ESP-IDF Environment in VS Code. To avoid manually sourcing the `export.sh` script every time you open a terminal: + + - Open your shell configuration file (`~/.zshrc` or `~/.bashrc`): + ```bash + nano ~/.zshrc + ``` + - Add this line at the bottom: + ```bash + source ~/esp/v5.3.2/esp-idf/export.sh + ``` + - Save and reload the shell configuration: + + ```bash + source ~/.zshrc + ``` + + - Once the environment is sourced: + + - Check the Xtensa toolchain: + ```bash + xtensa-esp32s3-elf-gcc --version + ``` + - Verify `idf.py` again: + ```bash + idf.py --version + ``` + +--- + +### **3. Test the Setup Using the Hello World Program** + +#### Build and Flash Hello World + +1. Navigate to your Zephyr workspace: + + ```bash + cd ~/zephyrproject + ``` + +2. Activate the virtual environment: + + ```bash + source .venv/bin/activate + ``` + + Build and flash the Zephyr Hello World application inside your Zephyr virtual environment. This ensures that Zephyr tools (e.g., west, CMake) and configurations are properly used during the build process. + +3. Build the Hello World sample: + + ```bash + west build -b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world + ``` + + For the ESP32-S3-DevKitC, the build system expects either of these qualified targets: + + - `esp32s3_devkitc/esp32s3/procpu` (for the primary processor core) + - `esp32s3_devkitc/esp32s3/appcpu` (for the application processor core) + +4. Flash the firmware: + ```bash + west flash + ``` + +#### Monitor the Output + +1. Monitor the serial output: + + ```bash + west espressif monitor + ``` + +2. Expected Output: + + ```plaintext + ***** Booting Zephyr OS build v4.0.0-2253-g62f90c62ab8a ***** + Hello World! esp32s3_devkitc/esp32s3/procpu + ``` + +3. To exit the monitor, press `Ctrl + ]`. + +--- + +### **Potential Pitfalls and Solutions** + +#### **1. Permission Denied for `/dev/ttyUSB0`** + +- **Cause**: User does not have access to the serial port. +- **Solution**: + 1. Add your user to the `dialout` group: + ```bash + sudo usermod -aG dialout $USER + ``` + 2. Log out and log back in or restart the system. + +#### **2. `west` Not Found** + +- **Cause**: Zephyr virtual environment is not activated. +- **Solution**: + - Activate the virtual environment: + ```bash + source ~/zephyrproject/.venv/bin/activate + ``` + +#### **3. Build Fails with Missing Board Qualifiers** + +- **Cause**: Incorrect board target specified. +- **Solution**: + - Use the correct board target, for example: + ```bash + west build -b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world + ``` + +#### **4. Serial Port Already in Use** + +- **Cause**: Another process is using `/dev/ttyUSB0`. +- **Solution**: + 1. Identify the process using the port: + ```bash + lsof /dev/ttyUSB0 + ``` + 2. Kill the process: + ```bash + kill + ``` + 3. Retry flashing. From abd302c354fb92bd05f9aa5c43a784fb82ce825c Mon Sep 17 00:00:00 2001 From: JeffMboya Date: Thu, 9 Jan 2025 11:15:04 +0300 Subject: [PATCH 2/5] Add embed-proplet docs Signed-off-by: JeffMboya --- docs/embed-proplet | 49 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/embed-proplet diff --git a/docs/embed-proplet b/docs/embed-proplet new file mode 100644 index 0000000..5db0df2 --- /dev/null +++ b/docs/embed-proplet @@ -0,0 +1,49 @@ +When running: + +```bash +west build -b esp32s3_devkitc/esp32s3/procpu -p auto . +``` + +CMake might stop with: + +``` +Could NOT find Threads (missing: Threads_FOUND) +... +FATAL ERROR: command exited with status 1: ... +``` + +This is triggered by WAMR’s top-level `CMakeLists.txt` in `wasm-micro-runtime/`, specifically the lines: + +```cmake +set (THREADS_PREFER_PTHREAD_FLAG ON) +find_package(Threads REQUIRED) +``` + +because `WAMR` tries to detect and link `pthread` on the `host` system (Linux, Windows, macOS). + +- However, on `Zephyr`, especially for an `ESP32-S3` target, we do not use the host’s pthread library at all. There’s no concept of a local Linux “Threads” library in a cross-compile for an Xtensa SoC. +- So CMake’s `find_package(Threads REQUIRED)` fails with “Could NOT find Threads” because there’s no suitable host pthread dev package to fulfill that requirement in the cross-compilation environment. + +Installing host pthread dev files sometimes helps in a purely local scenario, but it can still fail or is semantically incorrect for embedded cross-builds. + +The Solution is to bypass `find_package(Threads REQUIRED)` on Zephyr. So, in your WAMR repo file `wasm-micro-runtime/CMakeLists.txt`, locate where it calls: + +```cmake +find_package(Threads REQUIRED) +``` + +and wrap that call in a conditional so it does not run on Zephyr: + +```cmake +if (NOT WAMR_BUILD_PLATFORM STREQUAL "zephyr") + set (THREADS_PREFER_PTHREAD_FLAG ON) + find_package(Threads REQUIRED) +endif() +``` + +then clean and rebuild: + +```bash +rm -rf build +west build -b esp32s3_devkitc/esp32s3/procpu -p auto . +``` From f31821d906c7ceb4ec09e99fa485972e9219fdef Mon Sep 17 00:00:00 2001 From: JeffMboya Date: Thu, 9 Jan 2025 11:22:09 +0300 Subject: [PATCH 3/5] Remove additional file Signed-off-by: JeffMboya --- docs/zephyr-setup.md | 300 ------------------------------------------- 1 file changed, 300 deletions(-) delete mode 100644 docs/zephyr-setup.md diff --git a/docs/zephyr-setup.md b/docs/zephyr-setup.md deleted file mode 100644 index b15e6d5..0000000 --- a/docs/zephyr-setup.md +++ /dev/null @@ -1,300 +0,0 @@ -# Setting Up Zephyr with ESP-IDF for ESP32 - -### **1. Set Up Zephyr Development Environment** - -#### Install Dependencies on your development machine - -1. Update your system: - - ```bash - sudo apt update - sudo apt upgrade - ``` - -2. Install the required tools: - - ```bash - sudo apt install --no-install-recommends git cmake ninja-build gperf \ - ccache dfu-util device-tree-compiler wget \ - python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ - make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1 - ``` - -3. Verify tool versions: - ```bash - cmake --version - python3 --version - dtc --version - ``` - Ensure versions meet the minimum requirements: CMake 3.20.5, Python 3.10, and Devicetree Compiler 1.4.6. - -#### Get Zephyr and Python Dependencies on your development machine - -1. Create a Zephyr workspace and clone the repository: - - ```bash - west init ~/zephyrproject - cd ~/zephyrproject - west update - ``` - -2. Set up a Python virtual environment: - - ```bash - sudo apt install python3-venv - python3 -m venv ~/zephyrproject/.venv - source ~/zephyrproject/.venv/bin/activate - pip install west - ``` - -3. Export Zephyr CMake package: - - ```bash - west zephyr-export - ``` - -4. Install Python dependencies: - - ```bash - west packages pip --install - ``` - -5. Install the Zephyr SDK: - - ```bash - cd ~/zephyrproject/zephyr - west sdk install - ``` - -6. Fetch Espressif binary blobs: - - ```bash - west blobs fetch hal_espressif - ``` - - The `ZEPHYR_BASE` variable is required to locate Zephyr's core build system, CMake scripts, and modules. Without it, the Zephyr tools (west) will fail to build applications. Confirm the `ZEPHYR_BASE` Environment Variable - - ```bash - echo $ZEPHYR_BASE - ``` - - If It’s Not Set: - -- Activate your Zephyr virtual environment: - - ```bash - source ~/zephyrproject/.venv/bin/activate - ``` - -- Set the ZEPHYR_BASE variable: - - ```bash - export ZEPHYR_BASE=~/zephyrproject/zephyr - ``` - - To make it peremanent, add the following line to your shell configuration file (`.bashrc` or `.zshrc`): - - ```bash - export ZEPHYR_BASE=/home/jeff/zephyrproject/zephyr - ``` - - For more detailed information, refer to the official [Zephyr Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). - ---- - -### **2. Install ESP-IDF on your development machine** - -Do not install ESP-IDF inside the Zephyr virtual environment. ESP-IDF is a separate development framework with its own setup and toolchain requirements, which should be installed and managed globally or in its own isolated environment. Global Installation (Preferred). This way, its tools and environment are available for any project on the ESP32, including Zephyr. - -Without ESP-IDF: - -- You cannot compile or flash code for the ESP32. -- Zephyr won’t be able to recognize or support the ESP32-S3 during build or runtime. - -#### Option 1: Using VS Code Extension (Recommended) - -1. Install the ESP-IDF extension: - - - Navigate to **View > Extensions** in VS Code. - - Search for "ESP-IDF Extension" and install it. - -2. Configure the ESP-IDF extension: - - - Open **Command Palette** (`Ctrl+Shift+P` or `Cmd+Shift+P`). - - Run `ESP-IDF: Configure ESP-IDF Extension`. - - Follow the setup wizard to download and install ESP-IDF. - -3. Ensure correct paths for IDF: - - - Set `IDF_PATH` and `IDF_TOOLS_PATH` appropriately (default: `$HOME/.espressif`). - -4. Add OpenOCD rules for Linux. The command typically looks like: - - ```bash - sudo cp --update=none /home//.espressif/tools/openocd-esp32//share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/ - ``` - - then reload udev rules to apply the changes: - - ```bash - sudo udevadm control --reload-rules - sudo udevadm trigger - ``` - - For more detailed information, refer to the official [ESP-IDF Extension Guide](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/installation.html). - -#### Option 2: Manual Installation - -1. Download ESP-IDF: - - ```bash - mkdir -p ~/esp - cd ~/esp - wget https://github.com/espressif/esp-idf/releases/download/v5.3.2/esp-idf-v5.3.2.zip - unzip esp-idf-v5.3.2.zip -d v5.3.2 - ``` - - Ensure the directory structure is correct after unzipping. The export script requires paths to be consistent. - -2. Export the ESP-IDF environment: - - ```bash - source ~/esp/v5.3.2/esp-idf/export.sh - ``` - - Run this command in every new terminal session, or automate it by adding the export command to your shell's startup script (~/.bashrc, ~/.zshrc, etc.). - -3. Verify the installation: - - Check the installed ESP-IDF version: - - ```bash - idf.py --version - - ``` - - If the `idf.py` command fails with `command not found`, source the ESP-IDF Environment in VS Code. To avoid manually sourcing the `export.sh` script every time you open a terminal: - - - Open your shell configuration file (`~/.zshrc` or `~/.bashrc`): - ```bash - nano ~/.zshrc - ``` - - Add this line at the bottom: - ```bash - source ~/esp/v5.3.2/esp-idf/export.sh - ``` - - Save and reload the shell configuration: - - ```bash - source ~/.zshrc - ``` - - - Once the environment is sourced: - - - Check the Xtensa toolchain: - ```bash - xtensa-esp32s3-elf-gcc --version - ``` - - Verify `idf.py` again: - ```bash - idf.py --version - ``` - ---- - -### **3. Test the Setup Using the Hello World Program** - -#### Build and Flash Hello World - -1. Navigate to your Zephyr workspace: - - ```bash - cd ~/zephyrproject - ``` - -2. Activate the virtual environment: - - ```bash - source .venv/bin/activate - ``` - - Build and flash the Zephyr Hello World application inside your Zephyr virtual environment. This ensures that Zephyr tools (e.g., west, CMake) and configurations are properly used during the build process. - -3. Build the Hello World sample: - - ```bash - west build -b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world - ``` - - For the ESP32-S3-DevKitC, the build system expects either of these qualified targets: - - - `esp32s3_devkitc/esp32s3/procpu` (for the primary processor core) - - `esp32s3_devkitc/esp32s3/appcpu` (for the application processor core) - -4. Flash the firmware: - ```bash - west flash - ``` - -#### Monitor the Output - -1. Monitor the serial output: - - ```bash - west espressif monitor - ``` - -2. Expected Output: - - ```plaintext - ***** Booting Zephyr OS build v4.0.0-2253-g62f90c62ab8a ***** - Hello World! esp32s3_devkitc/esp32s3/procpu - ``` - -3. To exit the monitor, press `Ctrl + ]`. - ---- - -### **Potential Pitfalls and Solutions** - -#### **1. Permission Denied for `/dev/ttyUSB0`** - -- **Cause**: User does not have access to the serial port. -- **Solution**: - 1. Add your user to the `dialout` group: - ```bash - sudo usermod -aG dialout $USER - ``` - 2. Log out and log back in or restart the system. - -#### **2. `west` Not Found** - -- **Cause**: Zephyr virtual environment is not activated. -- **Solution**: - - Activate the virtual environment: - ```bash - source ~/zephyrproject/.venv/bin/activate - ``` - -#### **3. Build Fails with Missing Board Qualifiers** - -- **Cause**: Incorrect board target specified. -- **Solution**: - - Use the correct board target, for example: - ```bash - west build -b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world - ``` - -#### **4. Serial Port Already in Use** - -- **Cause**: Another process is using `/dev/ttyUSB0`. -- **Solution**: - 1. Identify the process using the port: - ```bash - lsof /dev/ttyUSB0 - ``` - 2. Kill the process: - ```bash - kill - ``` - 3. Retry flashing. From c325711eb068394edbdb49dd775257dfc33770cf Mon Sep 17 00:00:00 2001 From: JeffMboya Date: Thu, 9 Jan 2025 12:37:42 +0300 Subject: [PATCH 4/5] Add dynamic linking --- docs/embed-proplet | 48 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/embed-proplet b/docs/embed-proplet index 5db0df2..54815c7 100644 --- a/docs/embed-proplet +++ b/docs/embed-proplet @@ -47,3 +47,51 @@ then clean and rebuild: rm -rf build west build -b esp32s3_devkitc/esp32s3/procpu -p auto . ``` + +# Dynamic Linking + +Zephyr does not support dynamic linking on most embedded targets (including ESP32-S3). When WAMR’s CMakeLists tries: + +```cmake +add_library(iwasm_shared SHARED ...) +``` + +you see the warning: + +``` +ADD_LIBRARY called with SHARED option but the target platform does not support +dynamic linking. Building a STATIC library instead. This may lead to problems. +``` + +This is harmless on Zephyr—it just forces the shared library to become a static library—but it can be confusing. To fix it, you should skip building a shared library entirely when you are on Zephyr. + +In your `modules/wamr/wasm-micro-runtime/CMakeLists.txt`, right after you set `WAMR_BUILD_PLATFORM="zephyr"`, force shared libs off: + +```cmake +if (WAMR_BUILD_PLATFORM STREQUAL "zephyr") + set(WAMR_BUILD_SHARED 0 CACHE BOOL "Disable shared library on Zephyr" FORCE) +endif () +``` + +If that’s in place, the `if (WAMR_BUILD_SHARED)` block that calls: + +```cmake +add_library (iwasm_shared SHARED ${WAMR_RUNTIME_LIB_SOURCE}) +... +``` + +will not run. Hence, no “shared library” warning on Zephyr. + +Alternatively, you can guard the `iwasm_shared` block with: + +```cmake +# SHARED LIBRARY +if (WAMR_BUILD_SHARED AND NOT WAMR_BUILD_PLATFORM STREQUAL "zephyr") + add_library (iwasm_shared SHARED ${WAMR_RUNTIME_LIB_SOURCE}) + ... +endif () +``` + +That way, the shared library part is skipped on Zephyr. + +Either approach ensures the warning disappears, and you end up only with a static WAMR build (`iwasm_static`) on Zephyr, which is what you actually need. From 110bdb7afa5a1fd2ad8ea0e29753da4c37d9a7c3 Mon Sep 17 00:00:00 2001 From: JeffMboya Date: Sun, 12 Jan 2025 13:44:35 +0300 Subject: [PATCH 5/5] Document config files --- docs/embed-proplet | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/embed-proplet b/docs/embed-proplet index 54815c7..fe123d7 100644 --- a/docs/embed-proplet +++ b/docs/embed-proplet @@ -95,3 +95,32 @@ endif () That way, the shared library part is skipped on Zephyr. Either approach ensures the warning disappears, and you end up only with a static WAMR build (`iwasm_static`) on Zephyr, which is what you actually need. + +# Configuration Files + +Configuration options are split between `prj.conf` and `esp32s3-devkitc.conf`, which Zephyr's build system merges based on the board and build target. Follow best practices to avoid conflicting settings. + +## **Purpose of Each File** + +1. **`prj.conf`:** + + - Application-specific settings. + - Defines project-specific features, libraries, and behaviors. + +2. **`esp32s3-devkitc.conf`:** + + - Board-specific settings. + - Configures hardware-specific options for the ESP32-S3. + +3. **`esp32s3-devkitc.overlay`:** + - Extends or modifies the board's Devicetree source. + +### **Configuration Hierarchy** + +Zephyr processes files in this order: + +1. **Default Kconfig files**: Zephyr subsystems and modules. +2. **Board files**: `esp32s3-devkitc.conf` overrides defaults. +3. **Application files**: `prj.conf` overrides earlier settings. + +If a setting appears in both `prj.conf` and `esp32s3-devkitc.conf`, the value in `prj.conf` takes precedence. Avoid duplicate definitions to prevent conflicts.