Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

NOISSUE - Add WAMR - Zephyr integration docs #7

Open
wants to merge 21 commits into
base: main
Choose a base branch
from
Prev Previous commit
Next Next commit
Add WAMR intergration
Signed-off-by: JeffMboya <jangina.mboya@gmail.com>
  • Loading branch information
JeffMboya committed Dec 18, 2024
commit df2d8a5d8890a963dfb2cedcc0560ecf40c3256e
192 changes: 192 additions & 0 deletions docs/zephyr-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,198 @@ Without ESP-IDF:

---

### integrate WebAssembly Micro Runtime (WAMR) with Zephyr,

### **1. Clone the WAMR Repository**

First, download the WAMR source code from its GitHub repository.

```bash
cd ~/zephyrproject
git clone https://github.com/bytecodealliance/wasm-micro-runtime.git
```

After cloning, your directory structure should look something like this:

```plaintext
~/zephyrproject/
├── zephyr/
├── modules/
├── wasm-micro-runtime/
```

Cloning the WAMR repository inside the `zephyrproject` folder is not strictly necessary, but it is a convenient practice because it keeps all related components in one place. If you prefer to clone WAMR elsewhere, you can still integrate it, but you must:

- Use the absolute path to the WAMR source in your `CMakeLists.txt` file.
- Ensure your build scripts and environment variables correctly point to the WAMR repository.

For example:

```bash
set(WAMR_ROOT /path/to/wasm-micro-runtime)
include(${WAMR_ROOT}/build-scripts/runtime_lib.cmake)
```

### **2. Configure WAMR in Your Zephyr Application**

Create or use an existing Zephyr application directory. Zephyr provides several sample applications. For this example, we'll use the `hello_world` application located at:

```bash
cd ~/zephyrproject/zephyr/samples/hello_world
```

In this directory, you will find a `CMakeLists.txt` file. Add the WAMR directory and include WAMR's source code at the end of the `CMakeLists.txt` file and save it.

```bash
set(WAMR_ROOT ${CMAKE_CURRENT_LIST_DIR}/../../../wasm-micro-runtime)
include(${WAMR_ROOT}/build-scripts/runtime_lib.cmake)
target_sources(app PRIVATE ${WAMR_RUNTIME_SOURCES})
target_include_directories(app PRIVATE ${WAMR_ROOT}/core/iwasm/include)
```

- `WAMR_ROOT`: Specifies the relative path to the WAMR repository
- `include`: Adds WAMR build scripts to include the runtime library
- `target_sources`: Adds WAMR runtime source files to the build process
- `target_include_directories`: Ensures the application can find WAMR's header files

Append these lines to `prj.conf`:

```bash
CONFIG_WASM_RUNTIME=y
CONFIG_WASM_MEMORY_POOL_SIZE=4096
CONFIG_WASM_MAIN_STACK_SIZE=2048
```

- `CONFIG_WASM_RUNTIME`: Enables the WebAssembly runtime.
- `CONFIG_WASM_MEMORY_POOL_SIZE`: Sets the memory pool size for running WebAssembly modules (adjust as needed for your application).
- `CONFIG_WASM_MAIN_STACK_SIZE`: Defines the stack size for the WAMR runtime's main execution.

---

### **3. Build WAMR for the ESP32-S3**

Before building, ensure both Zephyr and ESP-IDF environments are set up correctly.

#### **Step 1: Source the ESP-IDF Environment**

1. Ensure you are not inside the Zephyr virtual environment. If active, deactivate it:

```bash
deactivate
```

2. Source the ESP-IDF environment to set up its required tools:

```bash
source ~/esp/v5.3.2/esp-idf/export.sh
```

#### **Step 2: Source the Zephyr Virtual Environment**

```bash
source ~/zephyrproject/.venv/bin/activate
```

### **Important Notes**

- Zephyr and ESP-IDF environments must not be active simultaneously. Always deactivate one before activating the other.
- After sourcing each environment, confirm the active Python path to ensure the correct tools are in use.
- Use separate terminal sessions or deactivate/reactivate environments as needed when switching between Zephyr and ESP-IDF.

#### **Step 3: Build the Application**

1. Navigate to the root of your Zephyr workspace:

```bash
cd ~/zephyrproject
```

2. Build the application:

```bash
west build -b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world
```

Monitor the build output to ensure it completes without errors.

---

```bash
cd ~/zephyrproject
west build -b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world
```

---

### **4. Test with a WebAssembly Module**

1. **Create a WebAssembly Application:**
Use a tool like the `wasi-sdk` or any other WebAssembly compiler to create a `.wasm` file.

Example C program (`hello_world.c`):

```c
#include <stdio.h>
int main() {
printf("Hello, WebAssembly!\n");
return 0;
}
```

Compile to `.wasm`:

```bash
wasi-sdk -o hello_world.wasm hello_world.c
```

2. **Embed the `.wasm` Module in Your Application:**
Copy the `hello_world.wasm` file into your Zephyr application directory.

Update your application code to load and execute the WebAssembly module. Example in `main.c`:

```c
#include "iwasm.h"

extern const uint8_t wasm_module[];
extern const uint32_t wasm_module_size;

void main(void) {
RuntimeInitArgs init_args;
wasm_runtime_init(&init_args);

wasm_module_t module = wasm_runtime_load(wasm_module, wasm_module_size, NULL);
wasm_exec_env_t exec_env = wasm_runtime_create_exec_env(module, 1024);

wasm_runtime_call_wasm(exec_env, NULL, "main", 0, NULL);

wasm_runtime_destroy_exec_env(exec_env);
wasm_runtime_unload(module);
}
```

3. **Rebuild and Flash:**
```bash
west build -b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world
west flash
```

---

### **5. Monitor Output**

1. Open the serial monitor to observe the application logs:

```bash
west espressif monitor
```

2. Look for output from the `.wasm` module. Expected output:
```plaintext
Hello, WebAssembly!
```

---

### **Potential Pitfalls and Solutions**

#### **1. Permission Denied for `/dev/ttyUSB0`**
Expand Down