Kernel Linking

This chapter describes how a Kernel Application is linked.

Basically, a Kernel Application is linked as a Standalone Application. The main difference is that a Kernel Application defines Kernel APIs, and requires to embed additional information that will be used later to build a Sandboxed Application against this Kernel (by linking with the Kernel APIs). Such additional information is called the Kernel Metadata.

Link Flow

The following figure shows the general process of linking a Firmware, applied to a Kernel Application.

Kernel Link Flow

The Platform must be configured with Multi-Sandbox capability.

By default, the Kernel Metadata is included in the .debug.soar section which also serves for debug purpose (Stack Trace Reader, Heap Dumper). Particularly, it contains resolved absolute addresses of Kernel APIs.

Kernel Metadata Generation

To build a Sandboxed Application on Device, the Kernel Metadata must be exported after the Firmware link from the .debug.soar section of the executable. This step is not necessary to build a Sandboxed Application Off Board.

The Kernel Metadata can be exported from an existing Firmware executable file by using the Kernel Metadata Generator tool. It produces a .kdat file that will be used to link the Sandboxed Applications on device.

Kernel Metadata Generator

The .kdat file is optimized for size. When linking a Sandboxed Application .fso file, only the required metadata will be loaded in Java heap. It will be loaded from a standard InputStream, so that it can be stored to a non byte-addressable memory.

Note

The Kernel Metadata .kdat file can also be integrated in a Firmware executable file using post-link tools such as binutils objcopy, provided a dedicated section has been reserved by the third-party linker.

Firmware Linker

Firmware Linker is a tool that links a Feature within a Multi-Sandboxed Firmware.

It takes as input the Firmware executable (.out file) and the Feature binary code (.fo file) into which to be linked. It outputs a new executable application file, including the Installed Feature. This tool can be used to append multiple Features, by using as input file of each link pass the output file of the previous pass. Features linked this way are then called Installed Features.

The Kernel should have been linked for dimensioning the maximum size (code, data) for such Installed Features. See Installed Features options.

The Firmware Linker tool is automatically called when declaring System Applications to a Multi-Sandbox module description. It is also available as a MicroEJ Tool named Firmware Linker.

Firmware Linker using MicroEJ Launch

Warning

Features linked using the Firmware Linker tool cannot be dynamically uninstalled using Kernel.uninstall(Feature) method.

Feature Portability Control

A Kernel can install .fo files that have been built on other Kernels, provided this Kernel complies with other Kernels according to a set of rules declared hereafter. This is called Feature Portability Control, as the verification is performed during the new Kernel build, with no impact on the Feature dynamic installation.

Principle

During a Kernel build, SOAR can verify this Kernel preserves the portability of any .fo files built on a previous Kernel using the Kernel metadata file. If the portability is preserved, the UID of the previous Kernel is embedded in the new Kernel, allowing .fo files built on the previous Kernel to be installed as well. Otherwise, SOAR fails with an error indicating the broken rule(s).

Feature Portability Control Principle

Enable

Note

This is a new functionality that requires a custom Architecture configuration. Please contact our support team for more details.

Add the following Application Options to your Kernel project:

• com.microej.soar.kernel.featureportabilitycontrol.enabled: true to enable Feature Portability Control. Any other value disables Feature Portability Control (the following option is ignored).
• com.microej.soar.kernel.featureportabilitycontrol.metadata.path: OS path-separated list of Kernel Metadata files (*.kdat files).

Portability Rules

A Kernel Application can install a .fo file that has been built against another Kernel Application if the Kernel Application code has not changed or if the modifications respect the portability rules. Here is the list of the modifications that can be done while preserving the portability:

• Modify method code, except if Method Devirtualization or Method Inlining has changed.
• Add a new type (including declared as Kernel API),
• Add a new static method (including declared as Kernel API),
• Add a new instance method in a type not declared as Kernel API,
• Add a new instance method with private visibility in a type declared as Kernel API,
• Add a new static field (including declared as Kernel API),
• Add a new instance field in a type not declared as Kernel API,
• Rename an instance field with private visibility in a type declared as Kernel API,
• Modify a Java type, method, or static field not declared as Kernel API (code, signature, hierarchy)
• Remove a Java type, method, or static field not declared as Kernel API

Both Kernel Applications must be built from Platforms based on the same Architecture version.

Any other modifications will break the Feature portability. For example, the following modifications will not preserve the portability:

• Remove a Java type, method or static field declared as Kernel API,
• Add or remove an instance method in a type declared as Kernel API, even if the method is not declared as Kernel API,
• Add or remove an instance field in a type declared as Kernel API,
• Modify method or field signature declared as Kernel API (name, declaring type, static vs instance member, …),
• Modify hierarchy of a type declared as Kernel API.