Skip to content

Commit 1807eec

Browse files
TianlongLiangTianlongLiang
authored
Add an example of how to embed WAMR in Zephyr user mode (#3998)
1 parent 1958808 commit 1807eec

9 files changed

Lines changed: 486 additions & 1 deletion

File tree

‎product-mini/platforms/zephyr/simple/CMakeLists.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ if (NOT DEFINED WAMR_BUILD_LIBC_BUILTIN)
3232
endif ()
3333

3434
if (NOT DEFINED WAMR_BUILD_LIBC_WASI)
35-
# Disable libc wasi support by default
35+
# Disable libc wasi support by default, in the future,
36+
# it can be enabled if libc wasi file/socket/lock support is ready on Zephyr platform
3637
set (WAMR_BUILD_LIBC_WASI 0)
3738
endif ()
3839

‎product-mini/platforms/zephyr/user-mode/CMakeLists.txt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright (C) 2019 Intel Corporation. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
3+
4+
cmake_minimum_required(VERSION 3.13.1)
5+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
6+
7+
project(wamr_user_mode LANGUAGES C)
8+
9+
# Add the wamr-lib directory
10+
add_subdirectory(lib-wamr-zephyr)
11+
12+
# Link the wamr library to the app target
13+
target_link_libraries(app PRIVATE wamr_lib)
14+
15+
target_sources(app PRIVATE src/main.c)

‎product-mini/platforms/zephyr/user-mode/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# How to use WAMR with Zephyr in user mode
2+
3+
This example demonstrates how to build and run a WebAssembly application in user mode on Zephyr.
4+
5+
> Note: The user mode is not supported on all Zephyr boards. Please refer to the Zephyr documentation for more information.
6+
7+
## Setup
8+
9+
Please refer to the [previous WAMR Zephyr README.md](../simple/README.md) for general Zephyr setup instructions.
10+
11+
And refer to [official documentation of Zephyr user mode](https://docs.zephyrproject.org/latest/kernel/usermode/index.html) for more information about Zephyr user mode.
12+
13+
### Enable user mode
14+
15+
To enable Zephyr user mode, set the `CONFIG_USERSPACE` option to yes in the Zephyr configuration.
16+
17+
```conf
18+
CONFIG_USERSPACE=y
19+
```
20+
21+
And link the WAMR runtime as a separate library in CMakelists.txt.
22+
23+
```cmake
24+
...WAMR CMake set up...
25+
26+
zephyr_library_named (wamr_lib)
27+
28+
zephyr_library_sources (
29+
${WAMR_RUNTIME_LIB_SOURCE}
30+
wamr_lib.c
31+
)
32+
33+
zephyr_library_app_memory (wamr_partition)
34+
```
35+
36+
The `wamr_partition` is a memory partition that will be granted to the WAMR runtime. It is defined in the Zephyr application code.
37+
38+
```C
39+
K_APPMEM_PARTITION_DEFINE(wamr_partition);
40+
```
41+
42+
When creating a Zephyr thread, set the thread option to `K_USER` and the timeout to `K_FOREVER`. This can ensure that the `wamr_partition` is granted access to the thread before starting it with `k_thread_start`.
43+
44+
### Advantage of using WAMR runtime in Zephyr user mode thread
45+
46+
In a user-mode Zephyr thread, the application can only access a restricted partition of memory it granted to. It creates a sandbox for the WAMR runtime to run in, and the WAMR runtime can only access that memory space, meaning that all global variables in the WAMR runtime and both runtime and wasm app heap memory will be allocated from it. In this way, an extra layer of security is added to the wasm application on top of the wasm sandbox provided by WAMR.
47+
48+
### Example Targets
49+
50+
x86_64 QEMU (x86_64) is a 64-bit x86 target for emulating the x86_64 platform.
51+
52+
```shell
53+
west build -b qemu_x86_tiny . -p always -- -DWAMR_BUILD_TARGET=X86_32
54+
```
55+
56+
Use qemu to run the image.
57+
58+
```shell
59+
qemu-system-i386 -m 32 -cpu qemu32,+nx,+pae -machine pc -device isa-debug-exit,iobase=0xf4,iosize=0x04 -no-reboot -nographic -net none -pidfile qemu.pid -chardev stdio,id=con,mux=on -serial chardev:con -mon chardev=con,mode=readline -icount shift=5,align=off,sleep=off -rtc clock=vm -kernel ./build/zephyr/zephyr.elf
60+
```

‎product-mini/platforms/zephyr/user-mode/lib-wamr-zephyr/CMakeLists.txt‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Copyright (C) 2019 Intel Corporation. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
3+
4+
cmake_minimum_required(VERSION 3.8.2)
5+
6+
set (WAMR_BUILD_PLATFORM "zephyr")
7+
8+
# Build as X86_32 by default, change to "AARCH64[sub]", "ARM[sub]", "THUMB[sub]", "MIPS" or "XTENSA"
9+
# if we want to support arm, thumb, mips or xtensa
10+
if (NOT DEFINED WAMR_BUILD_TARGET)
11+
set (WAMR_BUILD_TARGET "X86_32")
12+
endif ()
13+
14+
if (NOT DEFINED WAMR_BUILD_INTERP)
15+
# Enable Interpreter by default
16+
set (WAMR_BUILD_INTERP 1)
17+
endif ()
18+
19+
if (NOT DEFINED WAMR_BUILD_AOT)
20+
# Enable AOT by default.
21+
set (WAMR_BUILD_AOT 1)
22+
endif ()
23+
24+
if (NOT DEFINED WAMR_BUILD_LIBC_BUILTIN)
25+
# Enable libc builtin support by default
26+
set (WAMR_BUILD_LIBC_BUILTIN 1)
27+
endif ()
28+
29+
if (NOT DEFINED WAMR_BUILD_LIBC_WASI)
30+
# Disable libc wasi support by default, in the future,
31+
# it can be enabled if libc wasi file/socket/lock support is ready on Zephyr platform
32+
set (WAMR_BUILD_LIBC_WASI 0)
33+
endif ()
34+
35+
if (WAMR_BUILD_TARGET STREQUAL "RISCV64_LP64" OR WAMR_BUILD_TARGET STREQUAL "RISCV32_ILP32")
36+
set (WAMR_BUILD_FAST_INTERP 1)
37+
endif ()
38+
39+
# Limited to global heap usage in Zephyr user mode
40+
set (WAMR_BUILD_GLOBAL_HEAP_POOL 1)
41+
42+
# Override the global heap size for small devices
43+
if (NOT DEFINED WAMR_BUILD_GLOBAL_HEAP_SIZE)
44+
set (WAMR_BUILD_GLOBAL_HEAP_SIZE 40960) # 40 KB
45+
endif ()
46+
47+
set (WAMR_ROOT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../../../..)
48+
49+
include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
50+
51+
# Embed WAMR as a Zephyr library
52+
zephyr_library_named (wamr_lib)
53+
54+
# Add source files to the library
55+
zephyr_library_sources (
56+
${WAMR_RUNTIME_LIB_SOURCE}
57+
wamr_lib.c
58+
)
59+
60+
# Specify the memory partition where all globals(including the WAMR global heap buffer)
61+
# in the library should be placed. This partition will be defined in the app source code
62+
# and added to the use-mode thread that uses the WAMR library.
63+
zephyr_library_app_memory (wamr_partition)

‎product-mini/platforms/zephyr/user-mode/lib-wamr-zephyr/test_wasm.h‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
/*
2+
* Copyright (C) 2019 Intel Corporation. All rights reserved.
3+
* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
4+
*/
5+
6+
/**
7+
* The byte array buffer is the file content of a test wasm binary file,
8+
* which is compiled by wasi-sdk toolchain from C source file of:
9+
* product-mini/app-samples/hello-world/main.c.
10+
*/
11+
unsigned char __aligned(4) wasm_test_file[] = {
12+
0x00, 0x61, 0x73, 0x6D, 0x01, 0x00, 0x00, 0x00, 0x01, 0x10, 0x03, 0x60,
13+
0x01, 0x7F, 0x01, 0x7F, 0x60, 0x02, 0x7F, 0x7F, 0x01, 0x7F, 0x60, 0x01,
14+
0x7F, 0x00, 0x02, 0x31, 0x04, 0x03, 0x65, 0x6E, 0x76, 0x04, 0x70, 0x75,
15+
0x74, 0x73, 0x00, 0x00, 0x03, 0x65, 0x6E, 0x76, 0x06, 0x6D, 0x61, 0x6C,
16+
0x6C, 0x6F, 0x63, 0x00, 0x00, 0x03, 0x65, 0x6E, 0x76, 0x06, 0x70, 0x72,
17+
0x69, 0x6E, 0x74, 0x66, 0x00, 0x01, 0x03, 0x65, 0x6E, 0x76, 0x04, 0x66,
18+
0x72, 0x65, 0x65, 0x00, 0x02, 0x03, 0x02, 0x01, 0x01, 0x04, 0x05, 0x01,
19+
0x70, 0x01, 0x01, 0x01, 0x05, 0x03, 0x01, 0x00, 0x01, 0x06, 0x13, 0x03,
20+
0x7F, 0x01, 0x41, 0xC0, 0x28, 0x0B, 0x7F, 0x00, 0x41, 0xBA, 0x08, 0x0B,
21+
0x7F, 0x00, 0x41, 0xC0, 0x28, 0x0B, 0x07, 0x2C, 0x04, 0x06, 0x6D, 0x65,
22+
0x6D, 0x6F, 0x72, 0x79, 0x02, 0x00, 0x0A, 0x5F, 0x5F, 0x64, 0x61, 0x74,
23+
0x61, 0x5F, 0x65, 0x6E, 0x64, 0x03, 0x01, 0x0B, 0x5F, 0x5F, 0x68, 0x65,
24+
0x61, 0x70, 0x5F, 0x62, 0x61, 0x73, 0x65, 0x03, 0x02, 0x04, 0x6D, 0x61,
25+
0x69, 0x6E, 0x00, 0x04, 0x0A, 0xB2, 0x01, 0x01, 0xAF, 0x01, 0x01, 0x03,
26+
0x7F, 0x23, 0x80, 0x80, 0x80, 0x80, 0x00, 0x41, 0x20, 0x6B, 0x22, 0x02,
27+
0x24, 0x80, 0x80, 0x80, 0x80, 0x00, 0x41, 0x9B, 0x88, 0x80, 0x80, 0x00,
28+
0x10, 0x80, 0x80, 0x80, 0x80, 0x00, 0x1A, 0x02, 0x40, 0x02, 0x40, 0x41,
29+
0x80, 0x08, 0x10, 0x81, 0x80, 0x80, 0x80, 0x00, 0x22, 0x03, 0x0D, 0x00,
30+
0x41, 0xA8, 0x88, 0x80, 0x80, 0x00, 0x10, 0x80, 0x80, 0x80, 0x80, 0x00,
31+
0x1A, 0x41, 0x7F, 0x21, 0x04, 0x0C, 0x01, 0x0B, 0x20, 0x02, 0x20, 0x03,
32+
0x36, 0x02, 0x10, 0x41, 0x80, 0x88, 0x80, 0x80, 0x00, 0x20, 0x02, 0x41,
33+
0x10, 0x6A, 0x10, 0x82, 0x80, 0x80, 0x80, 0x00, 0x1A, 0x41, 0x00, 0x21,
34+
0x04, 0x20, 0x03, 0x41, 0x04, 0x6A, 0x41, 0x00, 0x2F, 0x00, 0x91, 0x88,
35+
0x80, 0x80, 0x00, 0x3B, 0x00, 0x00, 0x20, 0x03, 0x41, 0x00, 0x28, 0x00,
36+
0x8D, 0x88, 0x80, 0x80, 0x00, 0x36, 0x00, 0x00, 0x20, 0x02, 0x20, 0x03,
37+
0x36, 0x02, 0x00, 0x41, 0x93, 0x88, 0x80, 0x80, 0x00, 0x20, 0x02, 0x10,
38+
0x82, 0x80, 0x80, 0x80, 0x00, 0x1A, 0x20, 0x03, 0x10, 0x83, 0x80, 0x80,
39+
0x80, 0x00, 0x0B, 0x20, 0x02, 0x41, 0x20, 0x6A, 0x24, 0x80, 0x80, 0x80,
40+
0x80, 0x00, 0x20, 0x04, 0x0B, 0x0B, 0x41, 0x01, 0x00, 0x41, 0x80, 0x08,
41+
0x0B, 0x3A, 0x62, 0x75, 0x66, 0x20, 0x70, 0x74, 0x72, 0x3A, 0x20, 0x25,
42+
0x70, 0x0A, 0x00, 0x31, 0x32, 0x33, 0x34, 0x0A, 0x00, 0x62, 0x75, 0x66,
43+
0x3A, 0x20, 0x25, 0x73, 0x00, 0x48, 0x65, 0x6C, 0x6C, 0x6F, 0x20, 0x77,
44+
0x6F, 0x72, 0x6C, 0x64, 0x21, 0x00, 0x6D, 0x61, 0x6C, 0x6C, 0x6F, 0x63,
45+
0x20, 0x62, 0x75, 0x66, 0x20, 0x66, 0x61, 0x69, 0x6C, 0x65, 0x64, 0x00
46+
};

‎product-mini/platforms/zephyr/user-mode/lib-wamr-zephyr/test_wasm_riscv64.h‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/*
2+
* Copyright (C) 2019 Intel Corporation. All rights reserved.
3+
* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
4+
*/
5+
6+
unsigned char __aligned(4) wasm_test_file[] = {
7+
0x00, 0x61, 0x73, 0x6D, 0x01, 0x00, 0x00, 0x00, 0x01, 0x10, 0x03, 0x60,
8+
0x01, 0x7F, 0x01, 0x7F, 0x60, 0x02, 0x7F, 0x7F, 0x01, 0x7F, 0x60, 0x01,
9+
0x7F, 0x00, 0x02, 0x31, 0x04, 0x03, 0x65, 0x6E, 0x76, 0x04, 0x70, 0x75,
10+
0x74, 0x73, 0x00, 0x00, 0x03, 0x65, 0x6E, 0x76, 0x06, 0x6D, 0x61, 0x6C,
11+
0x6C, 0x6F, 0x63, 0x00, 0x00, 0x03, 0x65, 0x6E, 0x76, 0x06, 0x70, 0x72,
12+
0x69, 0x6E, 0x74, 0x66, 0x00, 0x01, 0x03, 0x65, 0x6E, 0x76, 0x04, 0x66,
13+
0x72, 0x65, 0x65, 0x00, 0x02, 0x03, 0x02, 0x01, 0x01, 0x04, 0x05, 0x01,
14+
0x70, 0x01, 0x01, 0x01, 0x05, 0x03, 0x01, 0x00, 0x01, 0x06, 0x12, 0x03,
15+
0x7F, 0x01, 0x41, 0xC0, 0x01, 0x0B, 0x7F, 0x00, 0x41, 0x3A, 0x0B, 0x7F,
16+
0x00, 0x41, 0xC0, 0x01, 0x0B, 0x07, 0x2C, 0x04, 0x06, 0x6D, 0x65, 0x6D,
17+
0x6F, 0x72, 0x79, 0x02, 0x00, 0x04, 0x6D, 0x61, 0x69, 0x6E, 0x00, 0x04,
18+
0x0A, 0x5F, 0x5F, 0x64, 0x61, 0x74, 0x61, 0x5F, 0x65, 0x6E, 0x64, 0x03,
19+
0x01, 0x0B, 0x5F, 0x5F, 0x68, 0x65, 0x61, 0x70, 0x5F, 0x62, 0x61, 0x73,
20+
0x65, 0x03, 0x02, 0x0A, 0xB1, 0x01, 0x01, 0xAE, 0x01, 0x01, 0x03, 0x7F,
21+
0x23, 0x80, 0x80, 0x80, 0x80, 0x00, 0x41, 0x20, 0x6B, 0x22, 0x02, 0x24,
22+
0x80, 0x80, 0x80, 0x80, 0x00, 0x41, 0x9B, 0x80, 0x80, 0x80, 0x00, 0x10,
23+
0x80, 0x80, 0x80, 0x80, 0x00, 0x1A, 0x02, 0x40, 0x02, 0x40, 0x41, 0x10,
24+
0x10, 0x81, 0x80, 0x80, 0x80, 0x00, 0x22, 0x03, 0x0D, 0x00, 0x41, 0xA8,
25+
0x80, 0x80, 0x80, 0x00, 0x10, 0x80, 0x80, 0x80, 0x80, 0x00, 0x1A, 0x41,
26+
0x7F, 0x21, 0x04, 0x0C, 0x01, 0x0B, 0x20, 0x02, 0x20, 0x03, 0x36, 0x02,
27+
0x10, 0x41, 0x80, 0x80, 0x80, 0x80, 0x00, 0x20, 0x02, 0x41, 0x10, 0x6A,
28+
0x10, 0x82, 0x80, 0x80, 0x80, 0x00, 0x1A, 0x41, 0x00, 0x21, 0x04, 0x20,
29+
0x03, 0x41, 0x04, 0x6A, 0x41, 0x00, 0x2F, 0x00, 0x91, 0x80, 0x80, 0x80,
30+
0x00, 0x3B, 0x00, 0x00, 0x20, 0x03, 0x41, 0x00, 0x28, 0x00, 0x8D, 0x80,
31+
0x80, 0x80, 0x00, 0x36, 0x00, 0x00, 0x20, 0x02, 0x20, 0x03, 0x36, 0x02,
32+
0x00, 0x41, 0x93, 0x80, 0x80, 0x80, 0x00, 0x20, 0x02, 0x10, 0x82, 0x80,
33+
0x80, 0x80, 0x00, 0x1A, 0x20, 0x03, 0x10, 0x83, 0x80, 0x80, 0x80, 0x00,
34+
0x0B, 0x20, 0x02, 0x41, 0x20, 0x6A, 0x24, 0x80, 0x80, 0x80, 0x80, 0x00,
35+
0x20, 0x04, 0x0B, 0x0B, 0x40, 0x01, 0x00, 0x41, 0x00, 0x0B, 0x3A, 0x62,
36+
0x75, 0x66, 0x20, 0x70, 0x74, 0x72, 0x3A, 0x20, 0x25, 0x70, 0x0A, 0x00,
37+
0x31, 0x32, 0x33, 0x34, 0x0A, 0x00, 0x62, 0x75, 0x66, 0x3A, 0x20, 0x25,
38+
0x73, 0x00, 0x48, 0x65, 0x6C, 0x6C, 0x6F, 0x20, 0x77, 0x6F, 0x72, 0x6C,
39+
0x64, 0x21, 0x00, 0x6D, 0x61, 0x6C, 0x6C, 0x6F, 0x63, 0x20, 0x62, 0x75,
40+
0x66, 0x20, 0x66, 0x61, 0x69, 0x6C, 0x65, 0x64, 0x00
41+
};

0 commit comments

Comments
 (0)