Embedded Virtual Machine - Blinky Demo Application

This repository contains the definition for a blinky program that uses the Embedded VM infrastructure.

Table of Contents

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. Further Reading
9. Authors
10. License

About the Project

The blinky project defines a basic application that blinks an LED. We demonstrate how an application can run on any platform which satisfies its requirements by providing examples that run on:

• An nRF52840 Development Kit
• An nRF52 USB Dongle
• A simulator platform running on your personal computer and using an Aardvark I2C/SPI adapter.

To demonstrate the separateness of the application and platform layers, this project only contains application source code. The platforms that it runs on are made available through an external dependency: embvm/embvm-demo-platforms.

Back to top

Project Status

This project has reached v1.0.

Additional support is planned for demonstrating threading vs non-threading support in the while(1) loop.

Back to top

Getting Started

If you are unfamiliar with the Embedded VM project, please see the embvm-core repository for more information and a Getting Started guide.

Requirements

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

git-lfs

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.

Meson Build System

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

Getting the Source

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

Building

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 build/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 build/cross, we provide a Makefile CROSS to simplify the process. This variable will automatically supply the proper Meson argument, build/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=build/cross/embvm.txt cross file to ensure that the required Embedded VM settings are applied.

meson buildresults --cross-file build/cross/arm.txt --cross-file build/cross/cortex-m4_hardfloat.txt --cross-file=build/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

Configuration Options

Build configuration is covered in depth in the Configuration and Tuning guide in the embvm-core project.

Back to top

Documentation

The bulk of the Embedded VM documentation is contained in the embvm-core repository. This repository only contains documentation relevant to this specific module.

Building the Documentation

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

Need help?

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.

Contributing

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

Authors

• Phillip Johnston

License

Copyright © 2020 Embedded Artistry LLC

This project is released under GPLv3 according to the requirements of the embvm-core project. See the LICENSE.md file for further licensing details.

Back to top