Skip to content

Commit a970cb4

Browse files
casarolicasaroli
committed
docs: design
Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com>
1 parent 8bd37cf commit a970cb4

1 file changed

Lines changed: 211 additions & 0 deletions

File tree

‎docs/Design.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Design
2+
3+
Ocre is provided as a library to be included in other applications.
4+
5+
Some applications are provided as examples or templates. Please refer to each application's documentation for more information.
6+
7+
## Components
8+
9+
The Ocre library is divided into several components:
10+
11+
- **Ocre Common**: common code reused across Ocre components
12+
- **Ocre Platform**: platform-specific code
13+
- Zephyr: platform-specific code for Zephyr systems
14+
- POSIX: platform-specific code for POSIX systems like Linux
15+
- **Ocre Core**: the main Ocre library
16+
- Ocre Library (`ocre/library.h`): initialization and context lifecycle
17+
- Ocre Context (`ocre/context.h`): container management within a working directory
18+
- Ocre Container (`ocre/container.h`): individual container lifecycle
19+
- **Ocre Shell**: the command-line interface for Ocre
20+
- **Ocre Runtime**: the runtime engine interface (`ocre/runtime/vtable.h`) and built-in WAMR/WASI-P1 engine
21+
22+
These components and their relationships are described below:
23+
24+
```mermaid
25+
classDiagram
26+
class OcrePlatform {
27+
<<interface>>
28+
+ocre_load_file(path, size) void*
29+
+ocre_unload_file(buffer, size) int
30+
+ocre_lstat(path, buf) int
31+
+user_malloc(size) void*
32+
+user_free(p) void
33+
+user_realloc(p, size) void*
34+
+LOG_ERR(fmt)
35+
+LOG_WRN(fmt)
36+
+LOG_INF(fmt)
37+
+LOG_DBG(fmt)
38+
}
39+
40+
class OcreRuntimeVtable {
41+
<<interface>>
42+
+runtime_name string
43+
+init() int
44+
+deinit() int
45+
+create(id, img_path, workdir, ...) void*
46+
+destroy(ctx) int
47+
+thread_execute(ctx, sem) int
48+
+stop(ctx) int
49+
+kill(ctx) int
50+
+pause(ctx) int
51+
+unpause(ctx) int
52+
}
53+
54+
class WamrWasip1 {
55+
+runtime_name = "wamr/wasip1"
56+
}
57+
58+
class OcreLibrary {
59+
+ocre_initialize(vtable[]) int
60+
+ocre_create_context(workdir) ocre_context*
61+
+ocre_destroy_context(context) int
62+
+ocre_deinitialize() void
63+
}
64+
65+
class OcreContext {
66+
-working_directory string
67+
-containers container_node*
68+
-mutex pthread_mutex_t
69+
+ocre_context_create_container(...) ocre_container*
70+
+ocre_context_get_container_by_id(id) ocre_container*
71+
+ocre_context_remove_container(container) int
72+
+ocre_context_get_containers(out, max) int
73+
+ocre_context_get_container_count() int
74+
+ocre_context_get_working_directory() string
75+
}
76+
77+
class OcreContainer {
78+
-status ocre_container_status_t
79+
-detached bool
80+
-runtime ocre_runtime_vtable*
81+
-thread pthread_t
82+
+ocre_container_start() int
83+
+ocre_container_stop() int
84+
+ocre_container_kill() int
85+
+ocre_container_pause() int
86+
+ocre_container_unpause() int
87+
+ocre_container_wait(status) int
88+
+ocre_container_get_status() ocre_container_status_t
89+
+ocre_container_get_id() string
90+
+ocre_container_get_image() string
91+
+ocre_container_is_detached() bool
92+
}
93+
94+
class OcreContainerArgs {
95+
+argv string[]
96+
+envp string[]
97+
+capabilities string[]
98+
+mounts string[]
99+
}
100+
101+
class OcreShell {
102+
+container create/run/start/kill/wait/ps/rm
103+
+image ls/pull/rm
104+
}
105+
106+
OcreLibrary --> OcrePlatform : uses
107+
OcreLibrary --> OcreRuntimeVtable : registers and manages
108+
OcreLibrary "1" --> "0..*" OcreContext : creates/destroys
109+
OcreContext "1" --> "0..*" OcreContainer : owns
110+
OcreContainer --> OcreRuntimeVtable : runs via vtable
111+
OcreContainer --> OcreContainerArgs : configured by
112+
WamrWasip1 ..|> OcreRuntimeVtable : implements
113+
OcreShell --> OcreLibrary : drives
114+
```
115+
116+
### Ocre Common
117+
118+
The Ocre Common component provides common code reused across Ocre components, including version information (`version.h`) and commit ID (`commit_id.h`).
119+
120+
### Ocre Platform
121+
122+
The Ocre Platform component provides platform-specific implementations for POSIX and Zephyr, exposing a common interface to Ocre. It abstracts platform-specific functionality including binary file loading/mapping, memory allocation, logging, and configuration.
123+
124+
The platform must provide:
125+
126+
- **File I/O**: `ocre_load_file` / `ocre_unload_file` — load a binary image into memory (e.g. via `mmap` on POSIX, or `read` on Zephyr)
127+
- **Memory**: `user_malloc` / `user_free` / `user_realloc` — application-level memory (supports tiered memory on Zephyr via `shared_multi_heap`)
128+
- **Logging**: `LOG_ERR` / `LOG_WRN` / `LOG_INF` / `LOG_DBG` macros (Zephyr-style logging API)
129+
- **Config**: `config.h` defining `CONFIG_OCRE_DEFAULT_WORKING_DIRECTORY` and other Kconfig-style options
130+
- **lstat**: `ocre_lstat` — file metadata query
131+
132+
Check the [Ocre Platform](Platform.md), [Ocre Zephyr Platform](PlatformZephyr.md) and [Ocre POSIX Platform](PlatformPosix.md) documentation for more details.
133+
134+
### Ocre Core
135+
136+
The Ocre Core component is the main Ocre library. The public API is exposed through `<ocre/ocre.h>`, which aggregates:
137+
138+
- `<ocre/library.h>` — library init/deinit and context lifecycle
139+
- `<ocre/context.h>` — container management within a context
140+
- `<ocre/container.h>` — container lifecycle and inspection
141+
142+
#### Library
143+
144+
`ocre_initialize()` registers runtime engines (always includes the built-in WAMR/WASI-P1 engine, plus any user-supplied vtables), initializes them, and prepares global state. It must be called once before any other Ocre API.
145+
146+
`ocre_create_context()` creates a new context bound to a working directory (default: `CONFIG_OCRE_DEFAULT_WORKING_DIRECTORY`). Each working directory may only be used by one context at a time. The library ensures the `images/` and `containers/` subdirectories exist on creation.
147+
148+
`ocre_deinitialize()` destroys all contexts and deinitializes all registered runtimes.
149+
150+
#### Context
151+
152+
An Ocre context (`ocre_context`) manages a collection of containers within a working directory. The working directory has the following structure:
153+
154+
```
155+
<workdir>/
156+
├── images/ # WASM image files available for execution
157+
└── containers/ # Per-container persistent storage (when "filesystem" capability is enabled)
158+
```
159+
160+
Whenever a context is destroyed, all running containers are killed, all containers are waited on, and then all containers are removed. See [State Information](StateInformation.md) for more details.
161+
162+
#### Container
163+
164+
An Ocre container (`ocre_container`) is a lightweight, isolated process running on a runtime engine. Containers are created with a reference to an image file (looked up under `<workdir>/images/`), a runtime name, an optional ID, optional arguments (`ocre_container_args`), and optional I/O file descriptors.
165+
166+
`ocre_container_args` carries:
167+
168+
- `argv` — command-line arguments passed to the container entry point
169+
- `envp` — environment variables (in `VAR=value` form)
170+
- `capabilities` — feature flags (e.g. `"filesystem"`, `"networking"`, `"ocre:api"`)
171+
- `mounts` — virtual mount points in `source:destination` form
172+
173+
An Ocre container can be in one of the following states:
174+
175+
- **Created**: The container has been created but not yet started.
176+
- **Running**: The container is currently running and executing.
177+
- **Paused**: The container has been paused and is not running.
178+
- **Exited**: The container has exited but the exit code has not been collected yet (transient; resolved by `ocre_container_wait()`).
179+
- **Stopped**: The container has been stopped and the exit code has been collected.
180+
- **Error**: The container has encountered an error and is no longer available.
181+
182+
```mermaid
183+
stateDiagram-v2
184+
[*] --> Created : ocre_context_create_container()
185+
Created --> Running : ocre_container_start()
186+
Running --> Paused : ocre_container_pause()
187+
Paused --> Running : ocre_container_unpause()
188+
Running --> Stopped : ocre_container_stop()
189+
Running --> Exited : natural exit
190+
Exited --> Stopped : ocre_container_wait()
191+
Running --> Error : runtime error
192+
Stopped --> Running : ocre_container_start()
193+
Stopped --> [*] : ocre_context_remove_container()
194+
Error --> [*] : ocre_context_remove_container()
195+
```
196+
197+
### Ocre Shell
198+
199+
The Ocre Shell component provides the command-line interface for Ocre. It allows the user to interact with Ocre containers through a simple command-line interface familiar to Docker users.
200+
201+
It is currently supported in Zephyr and is used by the [Supervisor sample](samples/supervisor.md).
202+
203+
Refer to the [Ocre Shell](OcreCli.md) documentation for more details.
204+
205+
### Ocre Runtime
206+
207+
The Ocre Runtime component defines the `ocre_runtime_vtable` interface (`<ocre/runtime/vtable.h>`), which is the plugin contract for custom runtime engines. The vtable includes function pointers for `init`, `deinit`, `create`, `destroy`, `thread_execute`, `stop`, `kill`, `pause`, and `unpause`.
208+
209+
The built-in runtime is **WAMR/WASI-P1** (`wamr/wasip1`), which uses the WebAssembly Micro-Runtime to execute WASM modules compiled against the WASI Preview 1 ABI. Additional runtime engines can be registered at initialization time via `ocre_initialize()`.
210+
211+
Refer to the [Custom Runtime Engine](CustomRuntimeEngine.md) documentation for more details.

0 commit comments

Comments
 (0)