This repository contains the designs, documentations, and source files for the Embedded Virtual Machine (embvm) project's core interfaces, libraries, and subsystems. This project is required to build Embedded VM applications and reusable modules (including drivers, OS interfaces, subsystems, and more).

Note that this project is dual-licensed. The open-source version of this project is released under GPLv3. A commercial license, which provides holders with the ability to create and distribute software without open-source obligations, can be purchased in the Embedded Artistry store. We release additional modules that use the embvm-core project under the MIT license, allowing them to work with both the GPLv3 and commercial licenses, as well as making them free for modification and use outside of the Embedded VM framework.

1. About the Project
2. Project Status
3. Getting Started
   1. Requirements
      1. git-lfs
      2. Meson Build System
   2. Getting the Source
   3. Building
   4. Testing
4. Configuration Options
5. Documentation
6. Need Help?
7. Contributing
8. Authors
9. License
10. Acknowledgments

The Embedded Virtual Machine (Embedded VM or embvm for short) is an embedded software framework that helps developers create portable and reusable embedded software components. The Embedded VM core project provides the core abstractions, boot-related code, utilities, and supporting libraries that are used to build Embedded VM applications. These abstractions are used to quickly create and port embedded systems software from one platform to another.

For a comprehensive introduction to the project, please see the Getting Started Guide. You can also find a detailed overview of the project and its design goals in the System Overview.

Back to top

This project is under active development. Reusable programs, platforms, and drivers have been successfully written using the Embedded VM, and they run on ARM Cortex-M4 embedded platforms. Supporting utilities are continually being tested, tuned, and optimized. Interfaces are evolving, and many interfaces still need to be created.

A number of reusable subsystems are planned, but not yet implemented. These include:

• System Power Manager
• Panic/Fault Handling and symbolification support
• Memory testing
• Parametric Logging
• Command line interface
• Run-time Configuration (KV-store)
• Firmware Update
• OTA Update
• Filesystem
• USB Stack
• WiFi Stack
• Bluetooth Stack

Additional chipsets and drivers will be added as required by client platforms or as time allows.

C interface shims will be developed to enable developers to work in C while interacting with the C++ framework core

Planned processor additions include:

• Nordic nRF91
• Nordic nRF53
• Additional STM32 processors
• Maxim DARWIN MCUs

Planned RTOS additions include:

• ThreadX

Application skeletons will be created for:

• Recovery firmware
• Manufacturing firmware
• Multi-stage boot

Additional libraries and utilities will be provided:

• CRC/Checksum
• Fixed-point Integers & Mathematics
• Coroutine support

Back to top

The instructions below will help you download and build the project.

Detailed documentation on the design and use of the Embedded VM can be found in the docs/ folder.

If this is your first encounter with the Embedded VM project, we recommend beginning with our Getting Started Guide. This guide includes links to demo projects that are built using the Embedded VM.

This project uses Embedded Artistry's standard Meson build system, and dependencies are described in detail on our website.

At a minimum you will need:

• git-lfs, which is used to store binary files in this repository
• Meson is the build system
• Some kind of compiler for your target system.
  • This repository has been tested with:
    • gcc-7, gcc-8, gcc-9
    • arm-none-eabi-gcc
    • Apple clang
    • Mainline clang

This project stores some files using git-lfs.

To install git-lfs on Linux:

sudo apt install git-lfs

To install git-lfs on OS X:

brew install git-lfs

Additional installation instructions can be found on the git-lfs website.

The Meson build system depends on python3 and ninja-build.

To install on Linux:

sudo apt-get install python3 python3-pip ninja-build

To install on OSX:

brew install python3 ninja

Meson can be installed through pip3:

pip3 install meson

If you want to install Meson globally on Linux, use:

sudo -H pip3 install meson

Back to top

This project uses git-lfs, so please install it before cloning. If you cloned prior to installing git-lfs, simply run git lfs pull after installation.

This project is hosted on GitHub. You can clone the project directly using this command:

git clone --recursive https://github.com/embvm/embvm-core

If you don't clone recursively, be sure to run the following command in the repository or your build will fail:

git submodule update --init --recursive

Back to top

If Make is installed, the project can be built by issuing the following command:

make

This will build all targets for your current architecture.

You can clean builds using:

make clean

You can eliminate the generated buildresults folder using:

make distclean

You can also use meson directly for compiling.

Create a build output folder:

meson buildresults

And build all targets by running

ninja -C buildresults

Cross-compilation is handled using meson cross files. Example files are included in the meson/cross folder. You can write your own cross files for your specific processor by defining the toolchain, compilation flags, and linker flags. These settings will be used to compile the project.

Cross-compilation must be configured using the meson command when creating the build output folder. For files stored within meson/cross, we provide a Makefile CROSS to simplify the process. This variable will automatically supply the proper Meson argument, meson/cross/ prefix, and .txt filename extension.

You can use a single file, or you can layer multiple files by separating the names with a colon.

make CROSS=arm:cortex-m4_hardfloat

You can also do this manually with the Meson interface. Note, however, that you will need to include a special --cross-file=meson/cross/embvm.txt cross file to ensure that the required Embedded VM settings are applied.

meson buildresults --cross-file meson/cross/arm.txt --cross-file meson/cross/cortex-m4_hardfloat.txt --cross-file=meson/cross/embvm.txt

Following that, you can run make (at the project root) or ninja -C buildresults to build the project.

Note: Tests will not be cross-compiled. They will only be built for the native platform.

Full instructions for working with the build system, including topics like using alternate toolchains and running supporting tooling, are documented in Embedded Artistry's Standardized Meson Build System on our website.

Back to top

The tests for this library are written with Catch2, which is included as a subproject and does not need to be installed on your system. You can run the tests by issuing the following command:

make test

By default, test results are generated for use by the CI server and are formatted in JUnit XML. The test results XML files can be found in buildresults/test/. You can manually run the test programs if needed.

For more information on testing, see Unit Testing with Catch2.

Back to top

Build configuration is covered in depth in the Configuration and Tuning guide.

Back to top

We provide a large amount of documentation for the Embedded VM project.

• The Glossary contains definitions for concepts used in the documentation and code
• The Software Inventory contains a list of all open source projects included in this framework, with version numbers and licensing information
• The Architecture and Design Documentation can be used to understand the current Embedded VM design, as well as the rationale behind many of the decisions made in this project.
• Our Developer Documentation folder provides guidelines and standards for developers who are building the Embedded VM or related components.
• The Project History folder contains a lot of major events that have occurred throughout this project.

Full documentation can be built locally by running the following command:

make docs

Documentation can be found in buildresults/docs, and the root page is index.html.

Back to top

If you need further assistance or have any questions, please file a GitHub issue or send us an email using the Embedded Artistry Contact Form.

You can also reach out on Twitter: mbeddedartistry.

If you are interested in contributing to this project, please read our contributing guidelines.

• Phillip Johnston

Copyright © 2020 Embedded Artistry LLC

Note that this project is dual-licensed. The open-source version of this project is released under GPLv3. A commercial license, which provides holders with the ability to create and distribute software without open-source obligations, can be purchased in the Embedded Artistry store.

We release additional modules that use the embvm-core project under the MIT license, allowing them to work with both the GPLv3 and commercial licenses, as well as making them free for modification and use outside of the Embedded VM framework. Note, however, that using these modules as-is will result in the embvm-core project being used in your application, requiring you to abide by GPLv3 or commercial licensing terms.

See the LICENSE.md file for further licensing details.

I would like to thank the following individuals for their direct contributions to this project:

• Rozi Harris, who has tirelessly listened to ideas, reviewed the framework architecture, and edited documentation

I would like to thank the following individuals for their inspiration on this project:

• Ruth Malan, who inspired the architecture documentation and process
• James Grenning, who taught me the value of Test-Driven Development (TDD)
• Jerry Fitzpatrick, who inspired many of the guidelines and practices that were used to build this framework

I would like to thank the following individuals for the open source libraries that have been incorporated into this framework:

• John Wellbelove for the Embedded Template Library
• Jonathan Müller for type_safe and debug_assert

Back to top