External Resources Loader
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.
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
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
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,
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.
The BSP must hold an offset for each opened resource. This offset must
be updated after each call to
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
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
APIs such as
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
LLEXT_RES_impl.himplementation (see LLEXT_RES: External Resources Loader).
The External Resources Loader is an additional module. In the platform configuration file, check External Resources Loader to install this module.
The External Resources Loader is automatically used when the MicroEJ Application tries to open an external resource.