Kernel Creation

This chapter requires a minimum understanding of MicroEJ Module Manager and Module Natures.

Create a new Project

First create a new Kernel Application.

A new project is generated into the workspace:

../_images/firmware-multiapp-skeleton-project.png

Configure a VEE Port

Before building the Kernel, you need to build a VEE Port with Multi-Sandbox capability. To enable the Multi-Sandbox capability in your VEE Port configuration, follow the instructions from the Multi-Sandbox section.

Once the VEE Port is built, configure the target VEE Port in your Kernel project. See Platform Selection.

Build the Executable and Virtual Device

In the Package Explorer, right-click on the project and select Build Module. The build of the Executable and Virtual Device may take several minutes. Once the build has succeeded, the folder myfirmware > target~ > artifacts contains the firmware output artifacts (see Input and Output Artifacts) :

  • mymodule.out: The Executable to be programmed on device.
  • mymodule.kpk: The Kernel package to be imported in a MicroEJ Forge instance.
  • mymodule.vde: The Virtual Device to be imported in the SDK.
  • mymodule-workingEnv.zip: This file contains all files produced by the build phase (intermediate, debug and report files).
../_images/firmware-multiapp-skeleton-artifacts.png

Expose APIs

A Kernel must define the set of classes, methods and static fields all applications are allowed to use.

Note

According to the Kernel and Features specification, no API is open by default to Sandboxed Applications.

This can be done either by declaring Kernel APIs or by definining a Runtime Environment.

The main difference is from the Application development point of view. In the first case, the Application project still declares standard module dependencies. This is the good starting point for quickly building a Kernel with Applications based on the MicroEJ modules as-is. In the second case, the Application project declares the runtime environment dependency. This is the preferred way in case you intend to build and maintain a dedicated Applications ecosystem.

A Kernel API or a Runtime Environment module is added as a dependency with the configuration kernelapi->default.

<dependency org="com.microej.kernelapi" name="edc" rev="1.0.6" conf="kernelapi->default"/>

Implement a Security Policy

The Kernel can restrict sensitive or possibly unsafe operations performed by Sandboxed Applications, thus defining a security policy. Implementing a security policy is achieved by enabling support for Security Management system-wide and by registering to the Kernel a custom SecurityManager that will handle the Permission checks.

Note

An API controlled by the Security Manager must be guarded by a Permission check. The usual API documentation convention is to declare to throw a SecurityException with details about the requested Permission.

Enable the Security Management

For the sake of ROM footprint optimization, calls to Permission checks are disabled by default. In order to activate this feature the Option(checkbox): Enable SecurityManager checks option must be set.

Implement your Security Policy

This can be achieved by subclassing the base SecurityManager class, overriding its SecurityManager.checkPermission(Permission) method, and registering an instance of this class to the Kernel by a call to System.setSecurityManager(SecurityManager).

// create a new Security Manager
SecurityManager sm = new SecurityManager() {
   @Override
   public void checkPermission(java.security.Permission perm) {
      // here implement your Kernel Security Policy
   };
};
// register the Security Manager
System.setSecurityManager(sm);

Then you have to implement your own Security Policy.

Implementation of a Security Policy is demonstrated in the Kernel-GREEN project. This Kernel implements a logging-only Security Policy using the utility class FeaturePermissionCheckDelegate that helps in implementing Permission checks in a Multi-Sandbox environment.

Add Pre-installed Applications

Your device may come with pre-installed applications, also known as applications that are already available when the Kernel starts. These applications are installed during the manufacturing process, such as in ROM alongside the Kernel executable.

To mimic this behavior on a Virtual Device, add a new dependency with the configuration systemapp-vd->application.

<dependency org="com.mycompany" name="myapp" rev="0.1.0" conf="systemapp-vd->application"/>

Build the Executable in the Workspace

It is possible to build the Executable using a MicroEJ Launch rather than the regular module build. This speeds-up the build time thanks to MicroEJ Module Manager workspace resolution and Eclipse incremental compilation.

  • Import the Kernel project and all Sandboxed Application projects in the same workspace,
  • Prepare a MicroEJ Application launch for the Kernel as a regular Standalone Application,
  • Prepare a MicroEJ Application launch for each Sandboxed Application using Build Dynamic Feature settings.

The following figure shows the overall build flow:

Kernel Build Flow using MicroEJ Launches

Kernel Build Flow using MicroEJ Launches

Kernel Application Configuration

Module Configuration

The build-firmware-multiapp build type defines additional configurations, used to specify the different kind of firmware inputs (see Input and Output Artifacts) as dependencies.

The following table lists the different configuration mapping usage where a dependency line is declared:

<dependency org="..." name="..." rev="..." conf="[Configuration Mapping]"/>
Configurations Mapping for build-firmware-multiapp Build Type
Configuration Mapping Dependency Kind Usage
vdruntime->default Add-On Library (JAR) Embedded in the Virtual Device only, not in the Executable
default->default; vdruntime->default Add-On Library (JAR) Embedded in both the Executable and the Virtual Device
platform->default VEE Port VEE Port dependency used to build the Executable and the Virtual Device. There are other ways to select the VEE Port (see Platform Selection)
kernelapi->default Runtime Environment (JAR) See Runtime Environment
systemapp-vd->application Application (WPK) Included to the Virtual Device as pre-installed Application.

Example of minimal firmware dependencies.

The following example defines a Kernel that exposes all APIs of EDC library.

<dependencies>
    <dependency org="ej.api" name="edc" rev="1.2.0" conf="provided" />
    <!-- Runtime API (set of Kernel API files) -->
    <dependency org="com.microej.kernelapi" name="edc" rev="1.0.0" conf="kernelapi->default"/>
</dependencies>

Build Options

The Kernel Application module nature section describes all the options available for building a Kernel module.

Build only a Virtual Device with a pre-existing Kernel

Copy/Paste the .kpk file into the folder dropins