External Resources Loader¶
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).
See Application Resources for more information on how to declare external resources depending on its kind (raw resources, images, fonts, NLS).
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¶
LLEXT_RES_impl.h
implementation (see LLEXT_RES: External Resources Loader).
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.