From 1f2b0e6dab4eeb31baf8984e35a5d10638028662 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 13:03:24 +0100 Subject: [PATCH 01/12] docs: add Get Started guides We add the Devcontainer and Getting Started guides for Zephyr and Linux. Signed-off-by: Marco Casaroli --- docs/Devcontainers.md | 72 +++++++++++++++++++++++++ docs/GetStartedLinux.md | 88 ++++++++++++++++++++++++++++++ docs/GetStartedZephyr.md | 113 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 273 insertions(+) create mode 100644 docs/Devcontainers.md create mode 100644 docs/GetStartedLinux.md create mode 100644 docs/GetStartedZephyr.md diff --git a/docs/Devcontainers.md b/docs/Devcontainers.md new file mode 100644 index 0000000..33e9df7 --- /dev/null +++ b/docs/Devcontainers.md @@ -0,0 +1,72 @@ +# Devcontainers + +Devcontainers are tools that allows you to create and manage isolated development environments in containers. It provides a consistent and reproducible development environment across different machines and operating systems. + +It is the fastest and easiest way to develop Ocre in Linux, macOS, and Windows. As it already comes preinstalled with all the necessary tools for building Ocre and the samples, including wasi-sdk. + +More information can be found at [the official Devcontainers documentation](https://containers.dev/). + +## Usage + +It is recommended to use VS Code devcontainers extension, however if your IDE does not support devcontainers, you can use the [devcontainer-cli](https://github.com/devcontainers/cli) tool. + +### VS Code + +Install the devcontainer extension for VS Code. Open the root of this repository. + +Select "Reopen in Container" in the pop-up notification or select "Reopen in container" in the command pallete. + +The select `linux` or `zephyr` from the command palette. The container will be built and started. + +More information can be found at [VS code extension](https://code.visualstudio.com/docs/devcontainers/containers). + +### devcontainer-cli + +If your IDE does not support devcontainers, you can use the devcontainer-cli tool. + +Install the devcontainer-cli: + +```sh +npm install -g @devcontainers/cli +``` + +Open a terminal in the root of this repository. + +Build the devcontainer. This needs to be done only once. + +In the next steps, you can replace `.devcontainer/linux/devcontainer.json` with `.devcontainer/zephyr/devcontainer.json` if you want to use the Zephyr devcontainer. + +```sh +devcontainer build --workspace-folder . --config .devcontainer/linux/devcontainer.json +``` + +Start the devcontainer. This can be done whenever the container needs to be started. + +```sh +devcontainer up --workspace-folder . --config .devcontainer/linux/devcontainer.json +``` + +Execute a shell inside the devcontainer. + +```sh +devcontainer exec --workspace-folder . --config .devcontainer/linux/devcontainer.json bash -i +``` + +For Linux, you get a shell like: + +``` +ubuntu@a5011ec9afd5:/workspaces/ocre$ +``` + +For Zephyr, you get a shell like: + +``` +(zephyr-venv) ubuntu@a5011ec9afd5:/workspaces/ocre$ +``` + +Note the Python venv is already activated. + +To continue development, follow the instructions for Ocre build and development: + +- [Get started with Linux](GetStartedLinux.md) +- [Get started with Zephyr](GetStartedZephyr.md) diff --git a/docs/GetStartedLinux.md b/docs/GetStartedLinux.md new file mode 100644 index 0000000..f9c6f47 --- /dev/null +++ b/docs/GetStartedLinux.md @@ -0,0 +1,88 @@ +# Get Started with Linux + +The samples we currently provide for Linux are the following. Check their specific instruction for +detailed explanation for each sample: + +- [`src/samples/mini/linux`](samples/mini.md) +- [`src/samples/demo/linux`](samples/demo.md) + +We also provide tests. Please refer to their specific instructions for detailed explanation: + +- [`tests/system`: System tests](tests/SystemTests.md) +- [`tests/leaks`: Memory leak checks](tests/LeakChecks.md) + +We can also generate source code coverage reports and render the documentation: + +- [`tests/coverage`: Source code coverage reports](tests/CoverageReports.md) +- [`docs`: Render documentation](RenderDocs.md) + +## Set up instructions + +### Devcontainer + +The devcontainer can be build and started in VS Code (using the devcontainer extension) or using the devcontainer-cli and requires a working docker environment. Please refer to the [devcontainer section](Devcontainers.md) for information on how to set up the devcontainer. + +### Native host development setup + +If you prefer to use native builds, you need: + +- Linux distribution: Ubuntu 24.04 is recommended. +- Git 2.43 or higher +- CMake 3.20.0 or higher +- A C99 compatible compiler (GCC or Clang recommended) + +To run the leak checks, `clang-18` is required. To build the Doxygen documentation, `doxygen`, and for the +automatic formatting, `clang-format` is required. + +Install everything in Ubuntu 24.04 with: + +```sh +sudo apt install git cmake build-essential clang-18 doxygen clang-format +``` + +## General instructions + +The build system is based on cmake. There are several "entry points" to the build system: + +- `/`: Main Ocre Library and samples +- `/tests/system/posix`: POSIX System Tests +- `/tests/leaks`: Memory Leak Checks +- `/tests/coverage`: Source code coverage generation +- `/docs`: Documentation + +The building of Ocre with the main entry point `/` is described below. The building of the other entry points is described on each of their documentation pages, linked above. + +## Main Ocre Library and samples + +This will build the main ocre library and the mini and demo samples in release mode. + +Go to the root of this repository and do: + +```sh +mkdir build +cd build +cmake .. +make +``` + +If you need to build the library in debug mode, pass the argument `-DCMAKE_BUILD_TYPE=Debug` to +`cmake ..` command above. + +To run the `mini` sample, from the `build` directory, execute: + +```sh +./src/samples/mini/posix/ocre_mini +``` + +For more information about the `mini` sample, refer to the [mini sample documentation](samples/mini.md). + +To run the `demo` sample, from the `build` directory, execute: + +```sh +./src/samples/demo/posix/ocre_demo +``` + +The working directory should be the `build` directory. `ocre_demo` requires the state information files in +`./var/lib/ocre`. + +For more information about the `demo` sample, refer to the [demo sample documentation](samples/demo.md). diff --git a/docs/GetStartedZephyr.md b/docs/GetStartedZephyr.md new file mode 100644 index 0000000..6c7b1e0 --- /dev/null +++ b/docs/GetStartedZephyr.md @@ -0,0 +1,113 @@ +# Get Started with Zephyr + +The samples we currently provide for Zephyr are the following. Check their specific instruction for +detailed explanation for each sample: + +- [`src/samples/mini/zephyr`](samples/mini.md) +- [`src/samples/demo/zephyr`](samples/demo.md) +- [`src/samples/supervisor/zephyr`](samples/supervisor.md) + +Refer to the [Zephyr build system](BuildSystemZephyr.md) documentation for more information. + +## Set up instructions + +### Devcontainer + +The devcontainer can be build and started in VS Code (using the devcontainer extension) or using the devcontainer-cli and requires a working docker environment. Please refer to the [devcontainer section](Devcontainers.md) for information on how to set up the devcontainer. + +### Native host development setup + +The Zephyr build can be done in two ways. We provide a west project with the minimal amount of Zephyr modules, +targeting our standard boards; and a more traditional Zephyr-centric development, where the whole Zephyr modules and toolchains are installed. These options are described below. + +#### Ocre West project + +Use this if you are developing for Ocre and do not care too much about Zephyr development or adding new boards. +The Ocre West project is minimalistic and focuses on a few boards, and includes only the necessary Zephyr +modules. If you are looking for developing Zephyr or other custom applications, modules, or boards, you should +set up a standard Zephyr West project, described below. + +Zephyr and its modules will be checked alongside ocre-runtime repository. In the devcontainer, this is +`/workspace/zephyr`, `/workspace/modules` and so on. In the host, we recommend ocre-runtime to be checked-out in a subdirectory of a workspace, for example: + +```sh +mkdir ~/zephyrproject +cd ~/zephyrproject +git clone --recurse-submodules https://github.com/project-ocre/ocre-runtime.git +``` + +If you open the repository in devcontainer, you have already cloned the repository and can continue with the instructions. + +If you need, make sure you have all the submodules checked out: + +```sh +git submodule update --init --recursive +``` + +Initialize Zephyr build using Ocre West Project Manifest. From the ocre repository root: + +```sh +west init -l . +west update +``` + +Proceed to the general instructions for Zephyr development below. + +#### Ocre Zephyr module + +Use this if you need to add new boards, or need to extensively change the Zephyr build configuration. +This is the standard recommended point of integration with Zephyr. All the modules and boards support +will be checked out. + +The base instructions are based on [Getting Started Guide](https://docs.zephyrproject.org/latest/getting_started/index.html). + +```sh +mkdir ~/zephyrproject +cd ~/zephyrproject +west init +west update +``` + +Proceed to the general instructions for Zephyr development below. + +## General instructions + +Build a sample: + +```sh +west build -p always -b native_sim/native/64 src/samples/supervisor/zephyr +``` + +Make sure you are in a directory inside the Zephyr workspace and the path to the Ocre sample is correct. +This will create a `build` directory in the current directory. It is possible to use multiple different build +directories for each sample, just by switching to a different directory. + +You can replace `native_sim/native/64` with any other supported board. +Please refer to the board specific instructions for more details: + +- `native_sim` +- `pico_plus2/rp2350b/m33` +- `b_u585i_iot02a` + +You can replace `src/samples/supervisor` with any other supported sample. +Please refer to the sample specific instructions for more details: + +- `src/samples/mini/zephyr` +- `src/samples/demo/zephyr` +- `src/samples/supervisor/zephyr` + +For the `native_sim` targets, run the sample as: + +```sh +west build -t run +``` + +For a physical target, you need to flash the image to the board: + +```sh +west flash +``` + +If you flashed the board, monitor the serial port and check the output. Please refer to the zephyr documentation for more details: + +- [Zephyr Documentation](https://docs.zephyrproject.org/latest/index.html) From 33508da5f053dfb0af9d1b2b489b9451988f4e08 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 13:04:03 +0100 Subject: [PATCH 02/12] docs: add documentation about tests We add the documentation about system tests, memory leak checks and source code test coverage reporting. Signed-off-by: Marco Casaroli --- docs/tests/CoverageReports.md | 32 ++++++++++++++++++ docs/tests/LeakChecks.md | 35 +++++++++++++++++++ docs/tests/SystemTests.md | 64 +++++++++++++++++++++++++++++++++++ 3 files changed, 131 insertions(+) create mode 100644 docs/tests/CoverageReports.md create mode 100644 docs/tests/LeakChecks.md create mode 100644 docs/tests/SystemTests.md diff --git a/docs/tests/CoverageReports.md b/docs/tests/CoverageReports.md new file mode 100644 index 0000000..b1670c3 --- /dev/null +++ b/docs/tests/CoverageReports.md @@ -0,0 +1,32 @@ +# Source code test coverage reports + +The source code coverage report generation coverage mapping features provided in clang +to build an instrumented version of Ocre and execute the [System Tests](SystemTests.md). + +Currently, these are only available for the POSIX platform. + +Because Ocre will need to be built with a different set of compile options, the entry point is separate: + +## Build and run + +Create a build directory in the root of the repository (or anywhere else) and navigate to it: + +```sh +mkdir tests/coverage/build +cd tests/coverage/build +``` + +Configure the cmake project. Note that `..` points to `tests/coverage` in the Ocre source tree: + +```sh +cmake .. +make +``` + +To build, run the tests and generate the report: + +```sh +make +``` + +If the command was successful, the coverage report is inside `report` in the `build` directory. diff --git a/docs/tests/LeakChecks.md b/docs/tests/LeakChecks.md new file mode 100644 index 0000000..e6d00ce --- /dev/null +++ b/docs/tests/LeakChecks.md @@ -0,0 +1,35 @@ +# Memory leak checks + +The memory leak checks will leverage the address sanitizer features provided in clang +to build an instrumented version of Ocre and execute the following binaries: + +- [mini sample](../samples/mini.md) +- [demo sample](../samples/demo.md) +- [System Tests](SystemTests.md) + +Currently, these are only available for the POSIX platform. + +Because Ocre will need to be built with a different set of compile options, the entry point is separate: + +## Build and run + +Create a build directory in the root of the repository (or anywhere else) and navigate to it: + +```sh +mkdir tests/leaks/build +cd tests/leaks/build +``` + +Configure the cmake project. Note that `..` points to `tests/leaks` in the Ocre source tree: + +```sh +cmake .. +``` + +To build and run all the tests and samples, execute: + +```sh +make +``` + +Any memory leaks detected by clang address sanitizer will be printed and the command will fail. diff --git a/docs/tests/SystemTests.md b/docs/tests/SystemTests.md new file mode 100644 index 0000000..3c70b17 --- /dev/null +++ b/docs/tests/SystemTests.md @@ -0,0 +1,64 @@ +# System tests + +System Tests are tests designed to test the entire system as a black box, +including all components and dependencies. +We usually build it in release mode, so we test exactly what we are delivering. + +Currently, these are only available for the POSIX platform. + +However, these are also sometimes reused for memory [leak checks](LeakChecks.md) and [source code coverage generation](CoverageReports.md). +In these cases, Ocre needs to be built with instrumentation so it is not testing the release build. +For more information on those, refer to their specific documentation. + +These tests are configured in the CI workflows as a quality gate. All PRs must pass all of them. + +## Build and run + +Create a build directory and navigate to it: + +```sh +mkdir tests/system/posix/build +cd tests/system/posix/build +``` + +Configure and build the cmake project. Note that `..` points to `tests/system/posix`: + +```sh +cmake .. +make +``` + +To run all the tests, execute: + +```sh +make run-systests +``` + +The last lines of the output will be something like: + +``` +-------------------------- +OVERALL UNITY TEST SUMMARY +-------------------------- +51 TOTAL TESTS 0 TOTAL FAILURES 0 IGNORED +``` + +You can also run the individual test executable binaries `test_*` in the build directory. + +Note that the tests must be run from the build directory, because they look for images in the current working directory + `./ocre/src/ocre/var/lib/ocre/images/`. + +## Details + +The individual test binaries: + +- `test_lib` +- `test_ocre` +- `test_context` +- `test_container` + +Follow a similar pattern. `test_lib` is testing the general library initialization functions. +`test_ocre` initializes the Ocre library, and tests the functionality of management of contexts. +`test_context` instantiates a context and tests its functionality, creating and managing the lifetime of the containers. +`test_container` tests the specific functionality of a specific container. + +Please, refer to their source code for more details. From 8e0e9fe2cbd24582399d0a6b82bfdaee64156b78 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 14:09:52 +0100 Subject: [PATCH 03/12] docs(samples/mini): add initial Signed-off-by: Marco Casaroli --- docs/samples/mini.md | 72 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/samples/mini.md diff --git a/docs/samples/mini.md b/docs/samples/mini.md new file mode 100644 index 0000000..47f90f6 --- /dev/null +++ b/docs/samples/mini.md @@ -0,0 +1,72 @@ +# mini sample + +This sample will create `hello-world.wasm` from the state information directory (`/lfs/ocre/images/hellow-world.wasm` if it does not exist. Then it will execute this container, which prints a nice ASCII art. + +It does not require the preloading of any other containers in the state information +directory because the hello-world.wasm container is hardcoded. + +It is possible to customize what container is hardcoded and created. Check the [Zephyr build system](../BuildSystemZephyr.md) document for more information. + +## Building and running + +Instructions for building on the different platforms are provided below: + +### Linux + +Make sure you are using the [Devcontainer](../Devcontainers.md) or have the necessary +tools for Linux described in the [Get Started with Linux](../GetStartedLinux.md) guide. + +In Linux, the mini sample is part of the main library build. + +From the root of the repository, or from anywhere else, reate build directory: + +```sh +mkdir build +cd build +``` + +Configure the Ocre Library build: + +```sh +cmake .. +``` + +Make sure `..` points to the root of the ocre-runtime source tree. + +Build ocre and the samples: + +```sh +make +``` + +Run the mini sample: + +```sh +./src/samples/mini/posix/ocre_mini +``` + +Note that this command should be run from the build directory +(i.e. the directory that contains `./src/ocre/var/lib/`). + +### Zephyr + +Make sure you are using the [Devcontainer](../Devcontainers.md) or have the necessary +tools for Linux described in the [Get Started with Zephyr](../GetStartedZephyr.md) guide. + +You should have done at least the `west init` and `west update` commands to proceed. + +Build the firmware image with: + +```sh +west build -p always -b b_u585i_iot02a src/samples/mini/zephyr/ +``` + +You can also replace `b_u585i_iot02a` with another board. + +#### Flashing + +```sh +west flash +``` + +If you monitor the UART or console from your Zephyr board, you should get the execution output. From ecea1e826991e48ba69b316f5aa821908afe76e3 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 14:09:59 +0100 Subject: [PATCH 04/12] docs(samples/demo): add initial Signed-off-by: Marco Casaroli --- docs/samples/demo.md | 112 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/samples/demo.md diff --git a/docs/samples/demo.md b/docs/samples/demo.md new file mode 100644 index 0000000..4622684 --- /dev/null +++ b/docs/samples/demo.md @@ -0,0 +1,112 @@ +# demo sample + +The demo sample will run a few scenarios in a sequential demonstration. + +Currently it will run the following scenarios in order: + +1. `hello-world.wasm` + - Prints a nice ASCII art + +2. `blinky.wasm` runs for 2 seconds + - Prints some logs to stdout + +3. `subscriber.wasm` and `publisher.wasm` run alongside for 4 seconds + - Exchange messages between the containers + +It requires the [state information](../StateInformation.md) directory +to load the images from. + +## Building and running + +Instructions for building on the different platforms are provided below: + +### Linux + +Make sure you are using the [Devcontainer](../Devcontainers.md) or have the necessary +tools for Linux described in the [Get Started with Linux](../GetStartedLinux.md) guide. + +In Linux, the demo sample is part of the main library build. + +From the root of the repository, or from anywhere else, reate build directory: + +```sh +mkdir build +cd build +``` + +Configure the Ocre Library build: + +```sh +cmake .. +``` + +Make sure `..` points to the root of the ocre-runtime source tree. + +Build ocre and the samples: + +```sh +make +``` + +Run the demo sample: + +```sh +./src/samples/demo/posix/ocre_demo +``` + +Note that this command should be run from the build directory +(i.e. the directory that contains files in the relative path `./src/ocre/var/lib/ocre/images/`). + +### Zephyr + +Make sure you are using the [Devcontainer](../Devcontainers.md) or have the necessary +tools for Linux described in the [Get Started with Zephyr](../GetStartedZephyr.md) guide. + +You should have done at least the `west init` and `west update` commands to proceed. + +Build the firmware image with: + +```sh +west build -p always -b b_u585i_iot02a src/samples/demo/zephyr/ +``` + +You can also replace `b_u585i_iot02a` with another board. + +#### Flashing + +This sample will load the container images from the state information directory, +which in Zephyr is `/lfs/ocre` by default. This directory should have a `images` +subdirectory preloaded with the required images. + +If we just use `west flash` here, it will flash the main app partition, but if the +images are not in the filesystem, the demo will fail. + +As part of the build artifacts, on supported platforms, is `merged.hex` which is +a hex file providing the application and the storage_partition with the state information data with the required preloaded images for the demo. + +To flash this hex, use a command like: + +```sh +west flash --hex-file build/zephyr/merged.hex +``` + +Note that the `--hex-file` option might be different depending on your runner, +and the `merged.hex` file might not have been built for your board because of +missing configuration. +Check the [Zephyr build system](../BuildSystemZephyr.md) document for more information. + +Depending on the size, it might take a long time to flash it. +For this reason we recommend doing this the first time, so it will preload the images, +and for subsequent development and flashing of Ocre, we can then just do: + +```sh +west flash +``` + +which should not erase the storage partition. + +If you monitor the UART or console from your Zephyr board, you should get the execution output. + +If it is not possible to flash the storage_partition with west, as a workaround, +it is possible to use the [Supervisor] with `ocre pull` to populate the images +directory, and then flash just this demo with the command above. From cdde6b3c81b8d4dde0914f6d2b6fad785d511d72 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 14:34:46 +0100 Subject: [PATCH 05/12] docs(samples/supervisor): add initial Signed-off-by: Marco Casaroli --- docs/samples/supervisor.md | 142 +++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/samples/supervisor.md diff --git a/docs/samples/supervisor.md b/docs/samples/supervisor.md new file mode 100644 index 0000000..44228d3 --- /dev/null +++ b/docs/samples/supervisor.md @@ -0,0 +1,142 @@ +# Supervisor + +The Supervisor will run "ocre daemon" in background, being controlled by the ocre-cli command line (shell) tool. It by default will preload the following images, +but will not start them. Instead it will provide a command line controller for managing these. Check the [Ocre CLI](../OcreCli.md) documentation for details. + +It also preloads the following images: + +- `blinky.wasm` +- `filesystem-full.wasm` +- `filesystem.wasm` +- `hello-world.wasm` +- `publisher.wasm` +- `subscriber.wasm` +- `webserver-complex.wasm` +- `webserver.wasm` + +Currently it only supports Zephyr. + +## Building and running on Zephyr + +### Building + +Make sure you are using the [Devcontainer](../Devcontainers.md) or have the necessary +tools for Linux described in the [Get Started with Zephyr](../GetStartedZephyr.md) guide. + +You should have done at least the `west init` and `west update` commands to proceed. + +Build the firmware image with: + +```sh +west build -p always -b b_u585i_iot02a src/samples/supervisor/zephyr/ +``` + +You can also replace `b_u585i_iot02a` with another board. + +### Flashing + +This sample will load the container images from the state information directory, +which in Zephyr is `/lfs/ocre` by default. This directory could have a `images` +subdirectory preloaded with images. Additional images can be pulled with `ocre pull` command. + +If we just use `west flash` here, it will flash the main app partition, but if the +images are not in the filesystem, there will be no preloaded images. + +As part of the build artifacts, on supported platforms, is `merged.hex` which is +a hex file providing the application and the storage_partition with the state information data with the preloaded images for the sample. + +To flash this hex, use a command like: + +```sh +west flash --hex-file build/zephyr/merged.hex +``` + +Note that the `--hex-file` option might be different depending on your runner, +and the `merged.hex` file might not have been built for your board because of +missing configuration. +Check the [Zephyr build system](../BuildSystemZephyr.md) document for more information. + +Depending on the size, it might take a long time to flash it. +For this reason we recommend doing this the first time, so it will preload the images, +and for subsequent development and flashing of Ocre, we can then just do: + +```sh +west flash +``` + +which should not erase the storage partition. + +If you monitor the UART or console from your Zephyr board, you should get the execution output. + +If it is not possible to flash the storage_partition with west, as a workaround, +it is possible to use the [Supervisor] with `ocre pull` to populate the images +directory, and then flash just this demo with the command above. + +## Customizing the preloaded images + +TODO + +## Using ocre-cli (shell) + +Quick usage of ocre client is described below. Detailed usage information can be found on the [Ocre CLI](../OcreCli.md) documentation. + +Get help: + +``` +ocre +``` + +List local images: + +``` +ocre image ls +``` + +It should display the local images: + +``` +SHA-256 SIZE NAME +d9d2984172d74b157cbcd27ff53ce5b5e07c1b8f9aa06facd16a59f66ddd0afb 22772 blinky.wasm +fdeffaf2240bd6b3541fccbb5974c72f03cbf4bdd0970ea7e0a5647f08b7b50a 58601 filesystem-full.wasm +a8042be335fd733ecf4c48b76e6c00a43b274ad9b0d9a6d3c662c5f0c36d4a40 41545 filesystem.wasm +4a42158ff5b0a4d0a65d9cf8a3d2bb411d846434a236ca84b483e05b2f1dff99 5026 hello-world.wasm +c7b29c38bd91f67e69771fbe83db4ae84d515a6038a77ee6823ae377c55eac3c 23111 publisher.wasm +5f94ea4678c4c1ab42a3302e190ffe61c58b8db4fcf4919e1c5a576a1b8dcd3b 22944 subscriber.wasm +496ab513d6b1b586f846834fd8d17e0360c053bc614f2c2418ef84a87fbcd384 98082 webserver-complex.wasm +0a8cd55cb93c995d71500381c11bab1f2536c66282b8cab324b42c35817fba57 81647 webserver.wasm +``` + +If there are no images, before you proceed, you can use `ocre pull` to populate the images. +Check the Ocre SDK and [Ocre CLI](../OcreCli.md) documentation for details. + +Start a container with the the `hello-world.wasm` image: + +``` +ocre run hello-world.wasm +``` + +Start a background container named `my_blinky` with the `blinky.wasm` image: + +``` +ocre run -n my_blinky -d -k ocre:api blinky.wasm +``` + +Show container statuses: + +``` +ocre ps +``` + +Kill the `my_blinky` container: + +``` +ocre kill my_blinky +``` + +Remove the `my_blinky` container: + +``` +ocre rm my_blinky +``` + +Please, refer to [Ocre CLI](../OcreCli.md) documentation and help messages for details From 63ee29c93ddd2504ec3bd6da94d1628571840de6 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 19:15:02 +0100 Subject: [PATCH 06/12] docs(demo): add info about customization Signed-off-by: Marco Casaroli --- docs/samples/demo.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/samples/demo.md b/docs/samples/demo.md index 4622684..d3c0269 100644 --- a/docs/samples/demo.md +++ b/docs/samples/demo.md @@ -110,3 +110,25 @@ If you monitor the UART or console from your Zephyr board, you should get the ex If it is not possible to flash the storage_partition with west, as a workaround, it is possible to use the [Supervisor] with `ocre pull` to populate the images directory, and then flash just this demo with the command above. + +## Customization + +It is possible to customize the preloaded container in the demo sample [state information](../StateInformation.md) directory through the following variables. + +- `OCRE_PRELOADED_IMAGES`: List of absolute paths images to be added to the state information directory. +- `OCRE_SDK_PRELOADED_IMAGES`: List of ocre-sdk submodule target images to be added to the state information directory. + +Note that for `OCRE_PRELOADED_IMAGES` the path to the container files must be absolute. And `OCRE_SDK_PRELOADED_IMAGES` list targets for the ocre-sdk build that should be added to the state information directory. Both variables can be included. For example, in Linux, we could have done: + +```sh +cmake .. "-DOCRE_SDK_PRELOADED_IMAGES=webserver.wasm;filesystem.wasm" "-DOCRE_PRELOADED_IMAGES=/absolute/path/to/image1.wasm;/absolute/path/to/image2.wasm" +``` + +Note the `"` are required because we have `;` in the lists. + +And these containers will be added to the state information directory. + +Also, please note that this will not automatically include the execution of these images in the demo, +so you will probably want to modify the demo application to run the images you have passed. + +For more information about build customization, please refer to the [Linux Build System](../BuildSystemLinux.md) or [Zephyr Build System](../BuildSystemZephyr.md) documentation. From cebfc91f0c8cfcd73ab903ec61f309cd7323c4a2 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 19:15:09 +0100 Subject: [PATCH 07/12] docs(mini): add info about customization Signed-off-by: Marco Casaroli --- docs/samples/mini.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/samples/mini.md b/docs/samples/mini.md index 47f90f6..9ca5d76 100644 --- a/docs/samples/mini.md +++ b/docs/samples/mini.md @@ -70,3 +70,28 @@ west flash ``` If you monitor the UART or console from your Zephyr board, you should get the execution output. + +## Customization + +It is possible to customize the container executed by mini sample through the `OCRE_INPUT_FILE_NAME` variable. + +For Zephyr: + +```sh +west build -b src/samples/mini/zephyr -- -DOCRE_INPUT_FILE_NAME=/absolute/path/to/my_container.wasm +``` + +For Linux: + +```sh +cmake .. -DOCRE_INPUT_FILE_NAME=/absolute/path/to/my_container.wasm +``` + +Note that the path to the container file must be absolute. + +And this container will be executed by the sample application. + +Also, please note that if the container required additional runtime engine capabilities, they should be added +to the source code of this sample. + +For more information about build customization, please refer to the [Linux Build System](../BuildSystemLinux.md) or [Zephyr Build System](../BuildSystemZephyr.md) documentation. From 0e6d72115dee18dae45fffdc80a27e0f41758806 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 19:15:16 +0100 Subject: [PATCH 08/12] docs(supervisor): add info about customization Signed-off-by: Marco Casaroli --- docs/samples/supervisor.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/samples/supervisor.md b/docs/samples/supervisor.md index 44228d3..1895a0d 100644 --- a/docs/samples/supervisor.md +++ b/docs/samples/supervisor.md @@ -72,10 +72,6 @@ If it is not possible to flash the storage_partition with west, as a workaround, it is possible to use the [Supervisor] with `ocre pull` to populate the images directory, and then flash just this demo with the command above. -## Customizing the preloaded images - -TODO - ## Using ocre-cli (shell) Quick usage of ocre client is described below. Detailed usage information can be found on the [Ocre CLI](../OcreCli.md) documentation. @@ -140,3 +136,22 @@ ocre rm my_blinky ``` Please, refer to [Ocre CLI](../OcreCli.md) documentation and help messages for details + +## Customization + +It is possible to customize the preloaded container in the demo sample [state information](../StateInformation.md) directory through the following variables. + +- `OCRE_PRELOADED_IMAGES`: List of absolute paths images to be added to the state information directory. +- `OCRE_SDK_PRELOADED_IMAGES`: List of ocre-sdk submodule target images to be added to the state information directory. + +Note that for `OCRE_PRELOADED_IMAGES` the path to the container files must be absolute. And `OCRE_SDK_PRELOADED_IMAGES` list targets for the ocre-sdk build that should be added to the state information directory. Both variables can be included. For example, in Linux, we could have done: + +```sh +west build -p always -b b_u585i_iot02a src/samples/supervisor/zephyr/ -- "-DOCRE_SDK_PRELOADED_IMAGES=webserver.wasm;filesystem.wasm" "-DOCRE_PRELOADED_IMAGES=/absolute/path/to/image1.wasm;/absolute/path/to/image2.wasm" +``` + +Note the `--` is required for west to pass these arguments to CMake and the `"` are required because we have `;` in the lists. + +And these containers will be added to the state information directory. + +For more information about build customization, please refer to the [Linux Build System](../BuildSystemLinux.md) or [Zephyr Build System](../BuildSystemZephyr.md) documentation. From ee361e443886e99fe46aabe394bcbf27ce703f53 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 19:15:41 +0100 Subject: [PATCH 09/12] docs(build): Zephyr build system Signed-off-by: Marco Casaroli --- docs/BuildSystemZephyr.md | 126 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/BuildSystemZephyr.md diff --git a/docs/BuildSystemZephyr.md b/docs/BuildSystemZephyr.md new file mode 100644 index 0000000..fb85892 --- /dev/null +++ b/docs/BuildSystemZephyr.md @@ -0,0 +1,126 @@ +# Ocre Build System for Zephyr + +Ocre build system is tightly integrated with Zephyr's build system, allowing developers to leverage the power of Zephyr's build system while also providing a more streamlined and user-friendly experience for developing Ocre itself. + +Since Zephyr does not support multiple applications, we need to build each sample separately. For this reason, we recommend the usage of multiple `build` directories with west. + +For more information about west and Zephyr, please refer to the [Zephyr documentation](https://docs.zephyrproject.org/latest/guides/west/index.html). + +## Build integration + +We provide several points of integration with Zephyr: + +- Ocre West Project +- Ocre Zephyr Module +- Ocre Sample Applications + - mini + - demo + - supervisor + +The general usage of these points of integration are described below. + +### Ocre West Project + +The Ocre West Project is a lightweight way of getting started with Ocre development. +It should just check out the very few modules and tools necessary for Ocre development on a supported board. + +It is defined by the `west.yml` file in the root directory of the project. + +There are two main possibilities to use it. If the Ocre runtime source code is already checked out, you can use the following command to initialize the project (run from the root of the source tree): + +```sh +west init -l . +``` + +Here, `-l .` tells west to initialize the project using the manifest (`west.yml` in the current directory). + +This will create a `.west` directory in `..` (i.e. side by side with the ocre-runtime directory). And when `west update` is run, Zephyr and its modules will also be checked out in `..`. + +This is the recommended way to work with the [Devcontainers](./Devcontainers.md). + +If the Ocre runtime source code is not checked out, you use a remote path to check out the Ocre West Project: + +```sh +west init https://github.com/project-ocre/ocre-runtime.git +``` + +This will create a `.west` directory in the current directory, and when `west update` is run, Ocre, Zephyr and its modules will be checked out in the current directory. + +With this project initialized, the following command is to actually check out all the code: + +```sh +west update +``` + +And then you can proceed to building one of the sample applications below. + +### Ocre Zephyr Module + +Ocre is provided as a Zephyr module. This makes it easy to integrate with existing Zephyr projects. + +The modules is defined by the `zephyr` directory in the root of the project. This adds some configuration variables +and kconfig options to Zephyr. Ocre is also built as a library, as it does not implement the function `main()`. +The user is free to implement it on their own projects. + +The module is usually included in a Zephyr project through the use of `ZEPHYR_EXTRA_MODULES` CMake variable of the `EXTRA_ZEPHYR_MODULES` environment variable. + +The samples described below already do this, so no extra configuration is required. + +### Ocre Sample Applications + +The provided sample applications use the Ocre Zephyr Module and can be used for demonstration +or a starting point for your own projects. + +These applications already include the Zephyr module on their `CMakeLists.txt` file, by setting the variable `ZEPHYR_EXTRA_MODULES`. + +### Configuration + +This sections describes the build-time configuration required for Ocre to work. + +#### Version + +There are several components of the Ocre version that gets compiled in the project. + +The file `src/ocre/version.h` includes the Ocre Library version string. +While the file `commit_id.h` includes the commit ID of the Ocre Library. +If this file is not present in the source tree, the file is generated during the build process and is stored in the build directory. +If the file does not exist, and the source tree is not a valid git repository, the build will fail. + +Note that these are unrelated to the Zephyr version and the Zephyr application version mechanism (i.e. throught he use of the VERSION file in the Zephyr application directory). + +#### Kconfig + +There are several Kconfig options that can be used to configure Ocre. +They are described in the `zephyr/Kconfig` file in this repository. + +The easiest way to configure them is to first build one of the Ocre sample applications, and then do: + +```sh +west built -t menuconfig +``` + +Then navigate to Zephyr -> Modules -> Ocre and look for their help pages. + +The Kconfig system is also used to extract the variables `CONFIG_OCRE_STORAGE_PARTITION_ADDR`, `CONFIG_OCRE_STORAGE_PARTITION_SIZE` and `CONFIG_OCRE_STORAGE_PARTITION_BLOCK_SIZE`. These parameters are used to generate the littlefs storage partition `merged.hex` file described below. + +#### build-time variables + +Some relevant build-time variables are described below: + +- `OCRE_INPUT_FILE_NAME`: Absolute path to the container file to be executed by the mini sample application. +- `OCRE_PRELOADED_IMAGES`: List of absolute paths images to be added to the state information directory. +- `OCRE_SDK_PRELOADED_IMAGES`: List of ocre-sdk submodule target images to be added to the state information directory. + +#### Storage partition + +In Zephyr, the [state information](StateInformation.md) is usually stored in a separate littlefs flash partition, +defined in the device tree. We use the widely used `storage_partition` device-tree labelled partition mounted at +`/lfs`. This is usually done with a `fstab.overlay` file (already included in our demos for the supported boards). + +Ocre will use a directory `ocre` inside this filesystem. For more information, see [StateInformation.md](StateInformation.md). + +The `fstab.overlay` file is included by appending to the list `EXTRA_DTC_OVERLAY_FILE` in the samples `CMakeLists.txt` files. + +#### merged.hex + +On platforms that support, if the storage partition related variables are set (potentially to their auto-detected values) in Kconfig, and when the flash programmer runner supports it, it is possible to flash the generated `merged.hex` file which includes the Zephyr application and the storage partition. From b395fb9bbf52e683e04d3aba7406caff6285a8f4 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 19:16:16 +0100 Subject: [PATCH 10/12] docs(ocre): state information Signed-off-by: Marco Casaroli --- docs/StateInformation.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/StateInformation.md diff --git a/docs/StateInformation.md b/docs/StateInformation.md new file mode 100644 index 0000000..8a0734b --- /dev/null +++ b/docs/StateInformation.md @@ -0,0 +1,33 @@ +# State information directory + +## Location + +The state information directory holds non-volatile data used by an Ocre context. + +It can be customized by passing a different workspace directory to the `ocre_create_context` function is called. + +When this function is called with `NULL` workspace, or when Ocre is installed as a system service in Linux or in zephyr, by default, it is defined as: + +- Zephyr: `/lfs/ocre` +- Linux: `/var/lib/ocre` + +## Structure + +The structure of this directory is described below. Currently it holds two directories: + +`images` +`containers` + +### `images` + +This directory holds the images available for local execution. + +In the [Supervisor sample](samples/supervisor.md), this is managed by [Ocre CLI](OcreCli.md). The user can add or remove files in this directory but they must be careful to avoid race conditions. + +### `containers` + +Holds one subdirectory named after the container id, for each of the created containers with the `filesystem` runtime engine capability. In this case, the container subdirectory here will be mounted as the root filesystem inside the container. + +This is used to provide a non-volatile storage to the container. It gets removed when the container is removed (but not on container restart). + +This directory is managed by Ocre and the user is not expected to manually edit or modify files there, especially when the container is running. From 83c0802755f70018f10a68966d31e8a32f556337 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 13 Jan 2026 20:32:15 +0100 Subject: [PATCH 11/12] docs(linux): build system Signed-off-by: Marco Casaroli --- docs/BuildSystemLinux.md | 42 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/BuildSystemLinux.md diff --git a/docs/BuildSystemLinux.md b/docs/BuildSystemLinux.md new file mode 100644 index 0000000..814273a --- /dev/null +++ b/docs/BuildSystemLinux.md @@ -0,0 +1,42 @@ +# Ocre Build System for Linux + +Ocre build system is based on CMake. This provides an easy way of embedding Ocre in diffrerent Linux applications, +as well as easy integration with other projects and generation of target executables. + +Since Linux does support multiple applications, we need a single entry point for building the Ocre library and all the sample applications. + +However, for [memory leak checks](tests/LeakChecks.md) and [source code test coverage report generation](tests/CoverageReports.md), it is necessary to build Ocre with a different set of build time options. While for [system tests](tests/SystemTests.md), we need to include Unity. Please check their documentation for more information. + +This file described the generic configuration that is used by Ocre Library or the builds described above. + +### Configuration + +This sections describes the build-time configuration honored by samples and tests in Linux. + +#### Version + +There are several components of the Ocre version that gets compiled in the project. + +The file `src/ocre/version.h` includes the Ocre Library version string. +While the file `commit_id.h` includes the commit ID of the Ocre Library. +If this file is not present in the source tree, the file is generated during the build process and is stored in the build directory. +If the file does not exist, and the source tree is not a valid git repository, the build will fail. + +#### Ocre build Configuration + +The default Ocre build configuration is in the file `src/platform/posix/include/ocre/platform/config.h`. +These options should not be changed by the user and the defaults should be used. + +#### build-time variables + +Some relevant build-time variables are described below: + +- `OCRE_INPUT_FILE_NAME`: Absolute path to the container file to be executed by the mini sample application. +- `OCRE_PRELOADED_IMAGES`: List of absolute paths images to be added to the state information directory. +- `OCRE_SDK_PRELOADED_IMAGES`: List of ocre-sdk submodule target images to be added to the state information directory. + +#### State information directory + +In Linux, the [state information](StateInformation.md) is usually stored by default in `/var/run/ocre` if Ocre is installed as a system service. For tests, these are usually stored relative to the build directory. + +Whenever an Ocre context is created, the workspace directory will be created and used as the state information directory. From 09a87eb1c98419ee1ace03295de7a805f26e2880 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Mon, 19 Jan 2026 12:31:54 +0100 Subject: [PATCH 12/12] docs(ocre-cli): initial Signed-off-by: Marco Casaroli --- docs/OcreCli.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 docs/OcreCli.md diff --git a/docs/OcreCli.md b/docs/OcreCli.md new file mode 100644 index 0000000..01bee9c --- /dev/null +++ b/docs/OcreCli.md @@ -0,0 +1,199 @@ +# Ocre CLI + +The ocre command line interface (CLI) is a powerful tool for interacting with the Ocre runtime. It provides a simple and intuitive way to manage and execute images within the Ocre environment. + +It is designed to be familiar with docker command line, however there are some different options and behavior. And all the underlying mechanisms are simpler and different. + +Currently, it is only supported in Zephyr, and is used by the [supervisor](samples/supervisor.md) sample. + +Below is a description of the available commands and options. + +## General Commands + +### `help` + +Display help message and usage information. + +Usage: `ocre help` + +### `version` + +Display version information including build details. + +Usage: `ocre version` + +Displays: + +- Ocre version +- Commit ID +- Build information +- Build date + +### Global Options + +Usage: `ocre [GLOBAL OPTIONS] COMMAND [COMMAND ARGS...]` + +The current global options are defined: + +``` + -v Verbose mode +``` + +## Container Management + +### `container create` + +Creates a container in the Ocre context. + +Usage: `ocre container create [options] IMAGE [ARG...]` + +Options: + +``` + -d Creates a detached container + -n CONTAINER_ID Specifies a container ID + -r RUNTIME Specifies the runtime to use + -v VOLUME:MOUNTPOINT Adds a volume to be mounted into the container + -v /ABSPATH:MOUNTPOINT Adds a directory to be mounted into the container + -k CAPABILITY Adds a capability to the container + -e VAR=VALUE Sets an environment variable in the container +``` + +Options '-v', '-e', and '-k' can be supplied multiple times. + +Note: Mount destinations must be absolute paths and cannot be '/'. Source paths must also be absolute. + +### `container run` + +Creates and starts a container in the Ocre context. + +Usage: `ocre container run [options] IMAGE [ARG...]` + +Options: + +``` + -d Creates a detached container + -n CONTAINER_ID Specifies a container ID + -r RUNTIME Specifies the runtime to use + -v VOLUME:MOUNTPOINT Adds a volume to be mounted into the container + -v /ABSPATH:MOUNTPOINT Adds a directory to be mounted into the container + -k CAPABILITY Adds a capability to the container + -e VAR=VALUE Sets an environment variable in the container +``` + +Options '-v', '-e', and '-k' can be supplied multiple times. + +### `container start` + +Starts a container in the Ocre context. + +Usage: `ocre container start CONTAINER` + +The container must be in CREATED or STOPPED status to be started. + +### `container kill` + +Kills a container in the Ocre context. + +Usage: `ocre container kill CONTAINER` + +The container must be in RUNNING status to be killed. + +### `container wait` + +Waits for a container to exit. + +Usage: `ocre container wait CONTAINER` + +Returns the exit code of the container once it has finished executing. + +### `container ps` + +Lists containers in the Ocre context. + +Usage: `ocre container ps [CONTAINER]` + +When called without arguments, lists all containers. When called with a container ID, shows information for that specific container. + +### `container rm` + +Removes a non-running, non-paused container from the Ocre context. + +Usage: `ocre container rm CONTAINER` + +The container must be in STOPPED, CREATED, or ERROR status to be removed. + +## Image Management + +### `image ls` + +Lists images in local storage. + +Usage: `ocre image ls [IMAGE]` + +When called without arguments, lists all images. When called with an image ID, shows information for that specific image. + +### `image pull` + +Downloads an image from a remote repository to the local storage. + +Usage: `ocre image pull URL [NAME]` + +Downloads an image from the specified URL. If no name is provided, the image name is extracted from the URL path. The command will fail if an image with the same name already exists locally. + +Currently, only http and https URLs are supported. If NAME is not provided, it will be extracted from the URL path if possible. + +### `image rm` + +Removes an image from local storage. + +Usage: `ocre image rm IMAGE` + +Warning: This command does not check if the image is currently in use by containers. + +## Shortcuts + +The following shortcut commands are available for convenience: + +### Container Shortcuts + +- `ps` → `container ps` - List containers +- `create` → `container create` - Create a container +- `run` → `container run` - Create and start a container +- `start` → `container start` - Start a container +- `kill` → `container kill` - Kill a container +- `rm` → `container rm` - Remove a container + +### Image Shortcuts + +- `images` → `image ls` - List images +- `pull` → `image pull` - Pull an image + +## ID Validation + +Both container and image IDs must follow specific naming conventions: + +- Valid characters are lowercase alphanumeric [a-z0-9] plus underscore (\_), hyphen (-), and dot (.) +- Cannot start with a dot (.) + +## Examples + +```sh +# Pull an image +ocre pull http://example.com/myimage.tar myimage + +# List images +ocre images + +# Create and run a container +ocre run -d -n mycontainer -e ENV_VAR=value myimage /bin/sh + +# List containers +ocre ps + +# Wait for container to finish +ocre wait mycontainer + +# Remove container +ocre rm mycontainer +```