Attention

EWAOL development has moved to the SOAFEE Special Interest Group and is now hosted at https://gitlab.com/soafee/ewaol/meta-ewaol, and the official documentation at: https://meta-ewaol.docs.soafee.io/.
For more details on SOAFEE, please see https://soafee.io/.
Note the following documentation is only applicable to the EWAOL’s repo hosted here: https://gitlab.arm.com/ewaol/meta-ewaol.

Introduction

The Edge Workload Abstraction and Orchestration Layer (EWAOL) project provides users with a standards-based framework using containers for the deployment and orchestration of applications on edge platforms. EWAOL is provided as the meta-ewaol repository, which includes metadata for building the EWAOL software stack as a custom Linux distribution via the Yocto Project.

The EWAOL distribution is an extension of the Project Cassini distribution as provided by the upstream meta-cassini Yocto layer repository, with associated documentation at: https://cassini.docs.arm.com/en/v0.9.0/introduction.html.

The EWAOL software stack is divided into the following software layers:

  • Application workloads:

    User-defined container applications that are deployed and executed on the EWAOL software stack. Note that the EWAOL project provides the system infrastructure for user workloads, and not the application workloads themselves. Instead, they should be deployed by end-users according to their individual use-cases.

  • Linux-based filesystem:

    This is the main component provided by the EWAOL project. The EWAOL filesystem contains tools and services that provide EWAOL core functionalities and facilitate deployment and orchestration of user application workloads. These tools and services include the Docker container engine, the K3s container orchestration framework, and Xen virtualization management software, together with their run-time dependencies. These are provided by and adapted from the meta-virtualization Yocto layer, although the integration of the Docker container engine and the K3s container orchestration framework is inherited as part of the Cassini distribution. In addition, EWAOL provides supporting packages such as those which enable run-time validation tests or software development capabilities on the target platform.

  • System software:

    System software specific to the target platform, composed of firmware, bootloader and the operating system, as well as the Xen type-1 hypervisor when building an EWAOL distribution with hardware virtualization support. This system software is integrated from the meta-arm, meta-arm-bsp, and meta-virtualization Yocto layers.

EWAOL is the reference implementation for SOAFEE (Scalable Open Architecture For Embedded Edge), the Arm lead industry initiative for extending cloud-native software development to automotive, with a special focus on real-time and functional safety. For more details, please see https://soafee.io.

More specifically, the meta-ewaol repository contains Yocto layers, configuration files, documentation and tools to support building EWAOL distribution images and validating core functionalities. The project currently supports two hardware target platforms:

Note

Users of this software stack must consider safety and security implications according to their own usage goals.

High-Level Overview

The following diagram illustrates the EWAOL software stack. EWAOL provides two different system architectures to support application workload deployment and orchestration, as described in EWAOL System Architectures later in this introduction.


_images/high_level_overview.png

Use-Cases Overview

EWAOL aims to facilitate the following core use-cases on the supported target platforms:

  • Deployment of application workloads via Docker and K3s.

  • Orchestration of resource-managed and isolated application workloads via Docker, K3s, and the Xen type-1 hypervisor providing hardware virtualization.

Instructions for achieving these use-cases are given in the Reproduce section of the User Guide, subject to relevant assumed technical knowledge as listed later in this introduction at Documentation Assumptions.

EWAOL System Architectures

There are two primary system architectures currently provided by EWAOL, differing according to the intended use-case, as follows:

Baremetal Architecture

For this architecture, the EWAOL software stack executes directly on the target hardware. This architecture supports the deployment and orchestration of application workloads running on a target platform without hardware virtualization.

Virtualization Architecture

For this architecture, the EWAOL software stack also includes the Xen type-1 hypervisor to support hardware virtualization in the form of isolated, resource-managed Virtual Machines (VMs). An EWAOL virtualization distribution image will include a Control VM (Dom0) and a single bundled Guest VM (DomU), by default. This architecture enables the deployment and orchestration of application workloads on a set of distinct VMs running on a single target platform.

EWAOL defines two customizable image build targets per target architecture: a standard EWAOL distribution image to support deployment and orchestration of an existing application workload, and an EWAOL distribution image which includes a Software Development Kit (SDK) that supports on-target development and analyses of application workloads and system services.

Features Overview

EWAOL includes the following major features:

  • Support for two architectural use-cases (Baremetal, and Virtualization).

  • Hardware virtualization support with the Xen type-1 hypervisor.

  • On-target development support with optionally included Software Development Kit.

  • Validation support with optionally included run-time integration tests, and build-time kernel configuration checks.

  • Tools provided for quality assurance and build support.

By extending the following distributions, EWAOL also inherits and adapts additional features:

  • Poky distribution (poky.conf) from the meta-poky Yocto layer

  • Systemd used as the init system.

  • RPM used as the package management system.

  • Cassini distribution (cassini.conf) from the meta-cassini-distro Yocto layer

  • Container engine and runtime with Docker and runc-opencontainers.

  • Container workload orchestration with the K3s Kubernetes distribution.

Documentation Overview

The documentation is structured as follows:

  • User Guide

    Provides guidance for configuring, building, and deploying EWAOL distributions on supported target platforms, running and validating supported EWAOL functionalities, and building the distribution for a custom or unsupported target platform. Also includes migration guidance for how to enable these activities on a later EWAOL release, when upgrading from an older release.

  • Developer Manual

    Provides more advanced developer-focused details of the EWAOL distribution, its implementation, and dependencies.

  • Codeline Management

    Describes the branch and release process of EWAOL, and how this process aligns with that of the Yocto Project.

  • Contributing

    Describes guidance for contributing to the EWAOL project, and describes the tooling provided to support it.

  • License

    Defines the license under which EWAOL is provided.

  • Changelog & Release Notes

    Documents new features, bug fixes, limitations, and any other changes provided under each EWAOL release.

Documentation Assumptions

This documentation assumes a base level of knowledge related to two different aspects of achieving the target use-cases via EWAOL:

  • Application workload containerization, deployment, and orchestration

    This documentation does not provide detailed guidance on developing application workloads, deploying them, or managing their execution via Docker or the K3s orchestration framework, and instead focuses on EWAOL-specific instructions to support these activities on an EWAOL distribution image.

    For information on how to use these technologies which are provided with the EWAOL distribution, see the Docker documentation and the K3s documentation.

  • Xen Type-1 Hypervisor

    EWAOL supports deployment and orchestration of application workloads running on isolated and resource-managed VMs enabled by the Xen type-1 hypervisor. However, this documentation does not provide detailed guidance for booting Xen hardware virtualized systems or managing VMs on an EWAOL distribution image, and provides only basic instructions for logging into a VM as part of the example instruction sequences within the User Guide.

    For detailed guidance on booting Xen hardware virtualized systems as well as managing and connecting to Xen VMs using Xen-specific tools and services, see the public Xen documentation.

  • The Yocto Project

    This documentation contains instructions for achieving EWAOL’s use-cases using a set of included configuration files that provide standard build features and settings. However, EWAOL forms a distribution layer for integration with the Yocto project and is thus highly configurable and extensible. This documentation supports those activities by detailing the available options for EWAOL-specific customizations and extensions, but assumes knowledge of the Yocto project necessary to prepare an appropriate build environment with these options configured.

    Readers are referred to the Yocto Project Documentation for information on setting up and running non-standard EWAOL distribution builds.

Repository Structure

The meta-ewaol repository (https://gitlab.arm.com/ewaol/meta-ewaol) is structured as follows:

  • meta-ewaol:

    • meta-ewaol-distro

      Yocto distribution layer providing top-level and general policies for the EWAOL distribution images.

    • meta-ewaol-tests

      Yocto software layer with recipes that include run-time tests to validate EWAOL functionalities.

    • meta-ewaol-bsp

      Yocto BSP layer with target platform specific extensions for particular EWAOL distribution images.

    • meta-ewaol-config

      Directory which contains configuration files for running tools on EWAOL, such as files to support use of the kas build tool, or EWAOL-specific configuration for running automated quality-assurance checks.

    • documentation

      Directory which contains the documentation sources, defined in ReStructuredText (.rst) format for rendering via sphinx. See the Documentation Build Validation page for guidance on building the documentation.

    • tools

      Directory that contains supporting tools for the EWAOL project, from tools to support Bitbake image builds or documentation builds (provided within tools/build) to tools for quality assurance (provided within tools/qa-checks).

The Yocto layers which are provided by meta-ewaol are detailed with their layer dependencies in Yocto Layers.

Repository License

The repository’s standard license is the MIT license (more details in License), under which most of the repository’s content is provided. Exceptions to this standard license relate to files that represent modifications to externally licensed works (for example, patch files). These files may therefore be included in the repository under alternative licenses in order to be compliant with the licensing requirements of the associated external works.

Contributions to the project should follow the same licensing arrangement.

Contributions and Issue Reporting

Guidance for contributing to the EWAOL project can be found at Contributing.

To report issues with the repository such as potential bugs, security concerns, or feature requests, please submit an Issue via GitLab Issues, following the project’s template.

Feedback and support

To request support please contact Arm at support@arm.com. Arm licensees may also contact Arm via their partner managers.

Maintainer(s)