Skip to content

Commit 6e738bd

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

1 file changed

Lines changed: 216 additions & 0 deletions

File tree

‎docs/Design.md‎

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

0 commit comments

Comments
 (0)