Documentation part 1

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.

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.

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)

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).