External Resources Loader

Principle

A resource is, for a MicroEJ Application, the contents of a file. This file is known by its path (its relative path from the MicroEJ Application classpath) and its name. The file may be stored in RAM, flash, or external flash; and it is the responsibility of the MicroEJ Core Engine and/or the BSP to retrieve and load it.

MicroEJ Platform makes the distinction between two kinds of resources:

  • Internal resource: The resource is taken into consideration during the MicroEJ Application build. The SOAR step loads the resource and copies it into the same C library as the MicroEJ Application. Like the MicroEJ Application, the resource is linked into the CPU address space range (internal device memories, external parallel memories, etc.).

    The available list of internal resources to embed must be specified in the MicroEJ Application launcher (MicroEJ launch). Under the “Resources” tab, select all internal resources to embed in the final binary file.

  • External resource: The resource is not taken into consideration by MicroEJ. It is the responsibility of the BSP project to manage this kind of resource. The resource is often programmed outside the CPU address space range (storage media like SD card, serial NOR flash, EEPROM, etc.).

    The BSP must implement some specific Low Level API (LLAPI) C functions: LLEXT_RES_impl.h. These functions allow the MicroEJ Application to load some external resources.

Functional Description

The External Resources Loader is an optional module. When not installed, only internal resources are available for the MicroEJ Application. When the External Resources Loader is installed, the MicroEJ Core Engine tries first to retrieve the expected resource from its available list of internal resources, before asking the BSP to load it (using LLEXT_RES_impl.h functions).

Implementations

External Resources Loader module provides some Low Level API (LLEXT_RES) to let the BSP manage the external resources.

Open a Resource

The LLAPI to implement in the BSP are listed in the header file LLEXT_RES_impl.h. First, the framework tries to open an external resource using the open function. This function receives the resources path as a parameter. This path is the absolute path of the resource from the MicroEJ Application classpath (the MicroEJ Application source base directory). For example, when the resource is located here: com.mycompany.myapplication.resource.MyResource.txt , the given path is: com/mycompany/myapplication/resource/MyResource.txt.

Resource Identifier

This open function has to return a unique ID (positive value) for the external resource, or returns an error code (negative value). This ID will be used by the framework to manipulate the resource (read, seek, close, etc.).

Several resources can be opened at the same time. The BSP does not have to return the same identifier for two resources living at the same time. However, it can return this ID for a new resource as soon as the old resource is closed.

Resource Offset

The BSP must hold an offset for each opened resource. This offset must be updated after each call to read and seek.

Resource Inside the CPU Address Space Range

An external resource can be programmed inside the CPU address space range. This memory (or a part of memory) is not managed by the SOAR and so the resources inside are considered as external.

Most of time the content of an external resource must be copied in a memory inside the CPU address space range in order to be accessible by the MicroEJ algorithms (draw an image etc.). However, when the resource is already inside the CPU address space range, this copy is useless. The function LLEXT_RES_getBaseAddress must return a valid CPU memory address in order to avoid this copy. The MicroEJ algorithms are able to target the external resource bytes without using the other LLEXT_RES APIs such as read, mark etc.

External Resources Folder

The External Resource Loader module provides an option (MicroEJ launcher option) to specify a folder for the external resources. This folder has two roles:

  • It is the output folder used by some extra generators during the MicroEJ Application build. All output files generated by these tools will be copied into this folder. This makes it easier to retrieve the exhaustive list of resources to program on the board.
  • This folder is taken into consideration by the Simulator in order to simulate the availability of these resources. When the resources are located in another computer folder, the Simulator is not able to load them.

If not specified, this folder is created (if it does not already exist) in the MicroEJ project specified in the MicroEJ launcher. Its name is externalResources.

Dependencies

Installation

The External Resources Loader is an additional module. In the platform configuration file, check External Resources Loader to install this module.

Use

The External Resources Loader is automatically used when the MicroEJ Application tries to open an external resource.