Low Level API

This chapter describes succinctly the available Low Level API, module by module. The exhaustive documentation of each LLAPI function is available in the LLAPI header files themselves. The required header files to implement are automatically copied in the folder include of the VEE Port at build time.

Low Level API Pattern

Principle

Each time the user has to supply the C code that links a VEE Port component to the target hardware, a Low Level API is defined. There is a standard pattern for the definition and implementation of these APIs. Each interface has a name and is specified by two header files:

• [INTERFACE_NAME].h specifies the functions that make up the public API of the implementation. In some cases the user code will never act as a client of the API, and so will never use this file.

• [INTERFACE_NAME]_impl.h specifies the functions that must be coded by the user in the implementation.

The user creates implementations of the interfaces, each captured in a separate C source file. In the simplest form of this pattern, only one implementation is permitted, as shown in the illustration below.

Low Level API Pattern (single implementation)

The following figure shows a concrete example of an LLAPI. The C world (the board support package) has to implement a send function and must notify the library using a receive function.

Low Level API Example

Multiple Implementations and Instances

When a Low Level API allows multiple implementations, each implementation must have a unique name. At run-time there may be one or more instances of each implementation, and each instance is represented by a data structure that holds information about the instance. The address of this structure is the handle to the instance, and that address is passed as the first parameter of every call to the implementation.

The illustration below shows this form of the pattern, but with only a single instance of a single implementation.

Low Level API Pattern (multiple implementations/instances)

The #define statement in MYIMPL.c specifies the name given to this implementation.

LLMJVM: Core Engine

The following API corresponds to architecture version 8.6.0.

LLMJVM_impl.h

Set of functions that the BSP must implement to launch and schedule the Core Engine

Defines

LLMJVM_OK (0)

Returned value when function call has succeeded.

LLMJVM_INTERRUPTED (1)

Returned value when current task has been interrupted during function call.

LLMJVM_ERROR (-1)

Returned value when function call has failed.

Functions

int32_t LLMJVM_IMPL_initialize(void)

This function is called once during Core Engine creation (i.e., when the SNI_createVM() function is called). It may be used to initialize specific data.

Returns:

LLMJVM_OK on success, LLMJVM_ERROR on error.

int32_t LLMJVM_IMPL_vmTaskStarted(void)

This function is called once during the Core Engine startup by the Core Engine task (i.e., when the SNI_startVM() function is called). It can be useful if the Core Engine support needs to know the Core Engine task.

Returns:

LLMJVM_OK on success, LLMJVM_ERROR on error.

int32_t LLMJVM_IMPL_scheduleRequest(int64_t absoluteTime)

Schedule an alarm (or timer) that will be triggered at the given absolute (system) time. If an alarm is already scheduled for an earlier time this function must do nothing, otherwise it must configure the alarm. If the given absolute time has already been reached, this function must call LLMJVM_schedule. Previously scheduled alarm must be canceled, only one alarm is scheduled at the same time. The scheduled alarm must call the function LLMJVM_schedule when it is triggered. The specified time is in milliseconds.

Returns:

LLMJVM_OK on success, LLMJVM_ERROR on error.

int32_t LLMJVM_IMPL_idleVM(void)

Causes the Core Engine RTOS task to sleep until it is woken up by the LLMJVM_wakeupVM function. This function is called by the Core Engine task.

Returns:

LLMJVM_OK if wakeup occurred, LLMJVM_INTERRUPTED if the Core Engine task has been interrupted, or LLMJVM_ERROR on error.

int32_t LLMJVM_IMPL_wakeupVM(void)

Wake up the Core Engine RTOS task. If the Core Engine task is not sleeping, the wakeup stays pending and the Core Engine will not sleep on the next LLMJVM_idleVM call unless there is a call to LLMJVM_ackWakeup between this call and the next LLMJVM_idleVM call. This function must be called only by the Core Engine code. If a task wants to wake up the Core Engine, it must use the LLMJVM_schedule function (which may in turn call this function).

Returns:

LLMJVM_OK on success, LLMJVM_ERROR on error.

int32_t LLMJVM_IMPL_ackWakeup(void)

Clears any outstanding LLMJVM_wakeupVM request. After calling this function, a call to LLMJVM_idleVM will result in a wait even if LLMJVM_wakeupVM has been called previously (provided no other LLMJVM_wakeupVM call has occurred since the call to this function. This function must cancel the alarm previously scheduled with LLMJVM_scheduleRequest. This function is called by the Core Engine task.

Returns:

LLMJVM_OK on success, LLMJVM_ERROR on error.

int32_t LLMJVM_IMPL_getCurrentTaskID(void)

Returns the ID of the current OS task.

This function may be called within the Core Engine task or another OS task.

int32_t LLMJVM_IMPL_shutdown(void)

This function is called during Core Engine end (i.e., at the end of the SNI_startVM() function). It may be used to freed specific data.

Returns:

LLMJVM_OK on success, LLMJVM_ERROR on error.

void LLMJVM_IMPL_setApplicationTime(int64_t t)

Sets the application time. The application time is the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. This time does not change the monotonic time.

Parameters:

• t – the application time to set in milliseconds.

int64_t LLMJVM_IMPL_getCurrentTime(uint8_t monotonic)

Gets the monotonic or the application time in milliseconds.

The monotonic time always moves forward and is not impacted by application time modifications (NTP or Daylight Savings Time updates). It can be implemented by returning the running time since the start of the device. This time is the value returned by the Java method Util.platformTimeMillis().

The application time is the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. This time is the value returned by the Java methods System.currentTimeMillis() and Util.currentTimeMillis().

Parameters:

• monotonic – if 1, get the monotonic time, otherwise get the application time.

int64_t LLMJVM_IMPL_getTimeNanos(void)

Gets the current timestamp in nanoseconds. Only elapsed time between two calls is meaningful.

Returns:

the current timestamp in nanoseconds

int32_t LLMJVM_schedule(void)

Notify the Core Engine that it must wake up or schedule a new thread.

Returns:

LLMJVM_OK on success, LLMJVM_ERROR on error.

LLMJVM.h

Set of functions provided by Core Engine that can be called by the BSP

Defines

LLMJVM_E_OK (0)

GreenThread Core Engine API. Exit code returned when the application ends normally (i.e., all the non-daemon threads are terminated or System.exit(exitCode) has been called)

LLMJVM_E_SOAR_FILE_INCOMPATIBLE (-1)

Exit code returned when the SOAR used for the application is not compatible with the Core Engine.

LLMJVM_E_BAD_LINK (-2)

Exit code returned when the link specific configuration breaks Core Engine requirements.

LLMJVM_E_EVAL_LIMIT (-3)

Exit code returned when the application ends because of the evaluation version limitations.

LLMJVM_E_MAIN_THREAD_ALLOC (-5)

Exit code returned when the Main thread can not be launched (for instance if thread stack can not be allocated).

LLMJVM_E_TOO_MANY_THREADS (-12)

Exit code returned when the specified maximum number of threads exceeds Core Engine limits.

LLMJVM_E_INV_HEAP_SIZE (-13)

Exit code returned when the Java heap size is too small or too large.

LLMJVM_E_INV_JAVA_STACK_MEM (-14)

Exit code returned when the Java stacks memory is invalid. Check the stacks memory alignment or size.

LLMJVM_E_CANNOT_RESTART (-16)

Exit code returned when the Core Engine cannot be restarted.

LLMJVM_E_INV_STATE (-17)

Exit code returned when the Core Engine is not in a valid state.

LLMJVM_E_INV_HEAP_MEMORY (-18)

Exit code returned when the memory used for the Java heap or the immortal heap does not work properly. This may be caused by an invalid external RAM configuration.

LLMJVM_E_INV_STATIC_MEMORY (-19)

Exit code returned when the memory used for the Java static fields does not work properly. This may be caused by an invalid external RAM configuration.

LLMJVM_E_INV_KF_RULES_CONFIGURATION (-20)

Exit code returned when KF rules configuration section is not correct. Check linker script files.

LLMJVM_E_INV_TOO_MANY_MONITORS_PER_THREAD (-21)

Exit code returned when the maximum number of monitors per threads exceeds Core Engine limits.

LLMJVM_E_INV_FPU_CONVENTION_CALL (-22)

Exit code returned when FPU convention call requirements are not satisfied.

LLMJVM_E_INITIALIZE_ERROR (-23)

Exit code returned when LLMJVM_IMPL_initialize() function defined in the abstraction layer returns an error.

LLMJVM_E_VM_TASK_STARTED_ERROR (-24)

Exit code returned when LLMJVM_IMPL_vmTaskStarted() function defined in the abstraction layer returns an error.

LLMJVM_E_SHUTDOWN_ERROR (-25)

Exit code returned when LLMJVM_IMPL_shutdown() function defined in the abstraction layer returns an error.

LLMJVM_E_INV_GC_MARK_STACK_SIZE (-26)

Exit code returned when the GC mark stack size is too small.

LLMJVM_E_INV_LINK (-27)

Exit code returned when the application object file has not been correctly linked by the third-party linker.

LLMJVM_E_INV_MANAGED_HEAP_CONFIG (-28)

Exit code returned when LLMJVM_CONF_impl_get_managed_heap_memory function returns an error when trying to configure a managed heap.

LLMJVM_E_INV_IMMORTALS_HEAP_CONFIG (-29)

Exit code returned when LLMJVM_CONF_impl_get_immortals_heap_memory function returns an error when trying to configure immortals heap.

LLMJVM_E_ERROR (-1)

Error code returned when an error occurred.

LLMJVM_E_ILLEGAL_ARGUMENT (-2)

Error code returned when an illegal argument has been given.

LLMJVM_E_INTERRUPTED (1)

Error code returned by LLMJVM_suspendCurrentJavaThread when suspend is not done.

Functions

void LLMJVM_initialize(void)

Initializes the Core Engine. This function MUST be called once before a call to LLMJVM_start.

int32_t LLMJVM_start(int32_t argc, void *argv)

Starts the Core Engine and call the main method of the Java application with the given String arguments. This function returns when the Java application ends.

The Java application ends when there is no more Java thread to run or when the Java method System.exit(int) is called.

Parameters:

• argc – java main argument count.

• argv – java main argument vector. An array of String (char**).

Returns:

LLMJVM_E_OK when the Core Engine ends normally or a negative value when an error occurred during startup.

int32_t LLMJVM_getExitCode(void)

Call this method after Core Engine execution to get the Java application exit code.

Returns:

the value given to the System.exit(exitCode) or 0 if the Java application ends without calling System.exit(exitCode).

void LLMJVM_dump(void)

Prints the state of the Core Engine to the standard output stream. For each Java thread, the Java stack trace, the name, the state and the priority are printed.

This function must only be called from the Core Engine thread context and only from a native function or callback. Calling this function from another context may lead to undefined behavior and should be done only for debug purpose.

int32_t LLMJVM_checkIntegrity(void)

Checks internal structure integrity of Core Engine and returns its checksum.

If an integrity error is detected, the

void LLMJVM_on_CheckIntegrity_error(uint32_t errorCode, void* errorAddress) hook is called and this method returns 0

.

If no integrity error is detected, a non-zero checksum is returned.

This function must only be called from the Core Engine thread context and only from a native function or callback. Calling this function multiple times in a native function must always produce the same checksum. If the returned checksums are different, a corruption must have occurred.

Please note that returning a non-zero checksum does not mean the Core Engine data has not been corrupted, as it is not possible for the Core Engine to detect the complete memory integrity.

The internal structures of the Core Engine that can be altered legitimately by a native function do not impact the checksum calculation. The following internal structures may be modified without affecting the checksum:

• basetype fields in Java objects or content of Java arrays of base type,

• internal structures modified by a LLMJVM function call (e.g., set a pending Java exception, suspend or resume the Java thread, register a resource, …).

This function affects performance and should only be used for debug purpose

A typical use of this API is to verify that a native implementation does not corrupt the internal structures:

Returns:

a 32 bits integrity checksum if the integrity check has run without errors, or 0 if an error has been detected.

uint8_t LLMJVM_isImmortalArray(void *sniJavaArray)

Checks if the given Java array is immortal or not.

An immortal Java array can be used safely from another native task, an interrupt handler or a DMA.

A non-immortal Java array can be used only during the execution of an SNI native or an SNI callback. A reference to a non-immortal Java array must not be kept in C between to SNI native executions.

Parameters:

• sniJavaArray – is a Java array retrieved from an SNI native arguments. This pointer reference the first element of an array and not the header of the object.

Returns:

1 if the given Java array is immortal or null, otherwise returns 0.

int32_t LLMJVM_throwNativeException(int32_t errorCode, void *message, uint8_t ioException)

If ioException

is false:

Throws a new

ej.sni.NativeException after the end of the current native method or SNI callback. NativeException class is a subclass of java.lang.RuntimeException. NativeException instances are unchecked exceptions, they do not need to be declared in the native method throws clause.

If ioException

is true:

Throws a new

ej.sni.NativeIOException after the end of the current native method or SNI callback. NativeIOException class is a subclass of java.io.IOException. NativeIOException instances are checked exceptions, they need to be declared in the native method throws clause (e.g., throws IOException). If the native method declaration is not compatible with NativeIOException (i.e., the throws clause does not specify NativeIOException or one of its superclasses) then a code>NativeException is thrown instead.

If an SNI callback must be executed after the end of the current native method then it will be executed first and then the exception will be thrown.

Calling this function while an exception is already pending will replace the previous exception.

Parameters:

• errorCode – is a value that can be retrieved in Java using the Native(IO)Exception.getErrorCode() method.

• message – is a null-terminated string that will be used to generate the message returned by Native(IO)Exception.getMessage(). It may be null.

• ioException – if true throws a NativeIOException, if false throws a NativeException.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ERROR if the function is called outside of the VM Task.

uint8_t LLMJVM_isExceptionPending(void)

Returns 1 if an exception is pending in the current Java thread (i.e., a successful call to LLMJVM_throwNativeException or throwNativeIOException(int, Ram) has been made prior to this call), returns 0 otherwise.

int32_t LLMJVM_clearPendingException(void)

Clears any pending exception for the current Java thread.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ERROR if the function is called outside of the VM Task.

int32_t LLMJVM_registerResource(void *resource, void *close, void *getDescription)

This function must be called when a native resource (file, socket, …) has been created to register it in the Core Engine.

The Core Engine keeps track of the native resources to prevent any memory leak when the Core Engine or an application is stopped.

In a Multi-Sandbox environment with KF profile enabled, the given close function is called when the application that has created the resource is stopped. If the resource has been created by the Kernel or if KF profile is disabled, the close function is called when the Core Engine stops.

To unregister the given native resource, call LLMJVM_unregisterResource.

A native resource is uniquely identified by the pair resource, close. Several native resources with the same resource value can be registered as long as close is different.

If a native resource is registered several times with the same resource and close values, this method returns LLMJVM_E_ILLEGAL_ARGUMENT (unless it has been unregistered before a second registration).

This function can be called once per native call. Calling this function several time within the same native will return LLMJVM_E_ERROR.

If an error occurs while registering the resource, then the close function is called and an exception is thrown when returning in Java.

Parameters:

• resource – the created native resource to register.

• close – the function called if the Core Engine wants to automatically close the resource.

• getDescription – the function called if the Core Engine wants to retrieve a description of the native resource. This pointer function may be null.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ILLEGAL_ARGUMENT if close is null or if the given native resource has already been registered. Returns LLMJVM_E_ERROR if the function is not called within the Core Engine task or if this function has been called several time in the same native.

int32_t LLMJVM_unregisterResource(void *resource, void *close)

This function must be called when a native resource previously registered with LLMJVM_registerResource has been reclaimed. It will unregister the given native resource so the Core Engine won’t call later the close function.

This method does not call the close function. It is up to the caller to call the appropriate function to close the resource.

The close parameter is used to uniquely identify the registered resource. If the given native resource is not found, this method returns LLMJVM_E_ILLEGAL_ARGUMENT.

Parameters:

• resource – a resource previously registered with LLMJVM_registerResource.

• close – the close argument given to LLMJVM_registerResource when the native resource has been registered.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ILLEGAL_ARGUMENT if the given native resource is not registered. Returns LLMJVM_E_ERROR if the function is not called within the Core Engine task.

int32_t LLMJVM_registerScopedResource(void *resource, void *close, void *getDescription)

Registers a scoped native resource.

These native resources are similar to standard native resources but they consume less memory, they are faster and they are closed automatically when the native returns back to Java. This function should be used when a resource is allocated in a native and released in a callback of the same native. This will prevent memory leaks that can occur when a thread is suspended using SNI_suspendCurrentJavaThreadWithCallback() and the Core Engine or the current application is stopped.

In a Multi-Sandbox environment with KF profile enabled, the given close function is called when the application that has created the scoped native resource is stopped. If the scoped native resource has been created by the Kernel or if KF profile is disabled, the close function is called when the Core Engine stops.

To unregister the given scoped native resource, call LLMJVM_unregisterScopedResource.

If several scoped native resources are registered within the same native context (or subsequent callback), then this function returns LLMJVM_E_ERROR (unless the previously registered scoped native resource has been unregistered).

Parameters:

• resource – the created scoped native resource to register.

• close – the function called if the Core Engine wants to automatically close the resource.

• getDescription – the function called if the Core Engine wants to retrieve a description of the scoped native resource. This pointer function may be null.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ILLEGAL_ARGUMENT if close is null. Returns LLMJVM_E_ERROR if the function is not called within the Core Engine task or if this function has been called several time in the same native context.

int32_t LLMJVM_unregisterScopedResource(void)

Unregisters the scoped native resource previously registered with LLMJVM_registerScopedResource.

After a call to this function, a new scoped native resource can be registered.

Usually this function does not need to be called because the registered scoped native resource is automatically closed and unregistered when the native returns back to Java.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ERROR if the function is not called within the Core Engine task or if no scoped native resource has been previously registered.

int32_t LLMJVM_getScopedResource(void *resourcePtr, void *closePtr, void *getDescriptionPtr)

Gets the information of the scoped native resource previously registered with LLMJVM_registerScopedResource.

Parameters:

• resourcePtr – output parameter. This function will store in this pointer the resource value previously given to LLMJVM_registerScopedResource. May be null.

• closePtr – output parameter. This function will store in this pointer the close value previously given to LLMJVM_registerScopedResource. May be null.

• getDescriptionPtr – output parameter. This function will store in this pointer the getDescription value previously given to LLMJVM_registerScopedResource. May be null.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ERROR if the function is not called within the Core Engine task or if no scoped native resource has been previously registered.

int32_t LLMJVM_getJavaResource(void *path, int32_t pathLength, void *resource)

Gets the Java resource data identified by the given path.

Parameters:

• path – string that contains the path. It must start with ‘/’.

• pathLength – length of the path string.

• resource – structure where the information of the resource are stored.

Returns:

LLMJVM_E_OK on success. Returns LLMJVM_E_ERROR if the resource is not found. Returns LLMJVM_E_ILLEGAL_ARGUMENT if pathLength is lower than 1 or resource is null.

int32_t LLMJVM_getCurrentJavaThreadID(void)

Returns the ID of the current Java thread. This function should be called within the Core Engine task. Returns LLMJVM_E_ERROR if this function is not called within the Core Engine task.

int32_t LLMJVM_suspendCurrentJavaThread(int64_t timeout, void *callback, void *callbackSuspendArg, uint8_t interruptible)

Causes the current Java thread to pause its Java execution after the end of the current native method. This function is not blocking. The current Java thread will resume its execution after the reception of an external event or after timeout milliseconds.

If a resume has been done on this thread before calling this function, the thread is not paused.

The result of calling this method several times during the same native execution is unpredictable.

If a callback is specified, then this callback is called before resuming the Java execution.

Parameters:

• timeout – duration in milliseconds of the pause. If timeout is zero, then time is not taken into consideration and the thread simply waits until resumed.

• callback – method to call when the timeout is reached or the sendExternalEvent(VMEngine) method is called on the current Java thread. May be null.

• callbackSuspendArg – argument that can be retrieved in the callback using LLMJVM_getCallbackArgs. May be null.

• interruptible – if true the suspend can be interrupted with a call to Thread.interrupt(), otherwise the suspend cannot be interrupted.

Returns:

LLMJVM_E_ERROR if the method has been called outside of the VM Task. Returns LLMJVM_E_OK if the pause is effective (i.e., the thread will suspend its execution at the end of the current native). Returns LLMJVM_E_INTERRUPTED if interruptible is true and an interrupt is pending (see Thread.interrupt()).

int32_t LLMJVM_javaThreadYield(void *callback, void *callbackArg)

Causes the current Java thread to call Thread.yield() after the end of the current native method and then to call the given callback when it will be scheduled again.

The result of calling this method several times during the same native execution is unpredictable.

Parameters:

• callback – method to call when the thread will be scheduled. May be null.

• callbackArg – argument that can be retrieved from the callback using LLMJVM_getCallbackArgs. May be null.

Returns:

LLMJVM_E_ERROR if the method has been called outside of the VM Task. Returns LLMJVM_E_OK on success.

int32_t LLMJVM_getCallbackArgs(void *suspendArgPtr, void *resumeArgPtr)

This method can be called from inside a SNI callback to retrieve arguments given to the callback with LLMJVM_javaThreadYield, LLMJVM_suspendCurrentJavaThread or LLMJVM_resumeJavaThread.

Parameters:

• suspendArgPtr – Out parameter. Pointer to the argument (void**) that will be filled-in by this method with the callbackSuspendArg value given to LLMJVM_suspendCurrentJavaThread or callbackArg value given to LLMJVM_javaThreadYield. May be null.

• resumeArgPtr – Out parameter. Pointer to the argument (void**) that will be filled-in by this method with the callbackResumeArg value given to LLMJVM_resumeJavaThread. May be null.

Returns:

LLMJVM_E_ERROR if the method has been called outside of the VM Task, otherwise returns LLMJVM_E_OK.

int32_t LLMJVM_resumeJavaThread(int32_t javaThreadID, void *callbackResumeArg)

Resume the given Java thread if it is suspended. If the Java thread is not paused, this resume stays pending. Next call of SNI_suspendCurrentJavaThread() will return immediately.

Parameters:

• javaThreadID – is the ID of the Java thread to resume.

• callbackResumeArg – argument that can be retrieved from the callback using LLMJVM_getCallbackArgs. May be null.

Returns:

LLMJVM_E_ERROR if the given Java thread ID is invalid, otherwise returns LLMJVM_E_OK.

uint8_t LLMJVM_isResumePending(int32_t javaThreadID)

Tests whether the given Java thread has been resumed while it was not suspended.

The pending resume flag is set when calling LLMJVM_resumeJavaThread. It is cleared when calling LLMJVM_suspendCurrentJavaThread, or when the Java thread actually resumes its execution. The pending resume flag is not modified by a timeout that occurs during a pause.

The pending resume flag of the given Java thread is unaffected by this method.

If the given Java thread ID is invalid, this method does nothing and returns false.

Parameters:

• javaThreadID – ID of the Java thread to test. The Java thread ID can be retrieved using LLMJVM_getCurrentJavaThreadID function.

Returns:

1 if the pending resume flag of the given Java thread is set, 0 otherwise.

uint8_t LLMJVM_clearCurrentJavaThreadPendingResumeFlag(void)

Clears the pending resume flag of the current Java thread (see LLMJVM_isResumePending).

If this method is not called within the Core Engine task, it does nothing and returns false.

Returns:

1 if the pending resume flag of the current Java thread was set before clearing it, 0 otherwise.

LLBSP_impl.h

Set of extra functions that the BSP must implement.

Functions

void LLBSP_IMPL_putchar(int32_t c)

Writes the character c, cast to an unsigned char, to stdout stream.

This function is used by the default implementation of the Java System.out.

LLMJVM_CONF_impl.h

Set of functions that can be implemented to configure the Core Engine at startup.

Functions

int LLMJVM_CONF_impl_get_managed_heap_memory(void **out_ptr, size_t *out_total_size, size_t *out_initial_size)

Optional user-implemented callback to provide a memory region for the Managed Heap.

The Core Engine calls this function to obtain:

• a pointer to a memory block that will be used as the Managed Heap,

• its total size in bytes,

• its initial usable size in bytes (the size the Core Engine will start using, and may extend up to the total size as needed).

The memory returned should preferably be aligned to 4 bytes, but if it is not, the framework will handle alignment itself by adjusting the start address and may reduce the usable size accordingly.

The initial size and the total size must be set to the same value, unless you want to activate Automatic Heap Usage Monitoring. To enable Automatic Heap Usage Monitoring, set the initial size to a value strictly less than the total size: the framework will then start by using the initial size, and may extend its usage up to the total size as needed.

This function is called once during Core Engine creation (i.e., when the SNI_createVM() function is called).

This function is optional. The Core Engine provides a default weak implementation, which returns the address, the total size, and the initial size as defined by the application, typically using the .bss.microej.heap linker section and associated symbols. Users can override this function to provide a custom Managed Heap configuration.

Parameters:

• out_ptr – Pointer to a void* variable to receive the address of the memory block to be used as the Managed Heap.

• out_total_size – Pointer to a size_t variable to receive the total size of the memory block in bytes referenced by out_ptr.

• out_initial_size – Pointer to a size_t variable that receives the initial usable size in bytes of the memory block. By default (when Automatic Heap Usage Monitoring is not desired), this value must be equal to the total size. To enable Automatic Heap Usage Monitoring, set this value lower than the total size.

Returns:

0 on success, -1 on error.

int LLMJVM_CONF_impl_get_immortals_heap_memory(void **out_ptr, size_t *out_size)

Optional user-implemented callback to provide a memory region for the Immortals Heap.

The Core Engine calls this function to obtain:

• a pointer to a memory block that will be used as the Immortals Heap,

• its size in bytes.

The memory returned should preferably be aligned to 4 bytes, but if it is not, the framework will handle alignment itself by adjusting the start address and may reduce the usable size accordingly.

This function is called once during Core Engine creation (i.e., when the SNI_createVM() function is called).

This function is optional. The Core Engine provides a default weak implementation, which returns the address and the size as defined by the application, typically using the .bss.microej.immortals linker section and associated symbols. Users can override this function to provide a custom Immortals Heap configuration.

Parameters:

• out_ptr – Pointer to a void* variable to receive the address of the memory block to be used as the Immortals Heap.

• out_size – Pointer to a size_t variable to receive the size of the memory block in bytes.

Returns:

0 on success, -1 on error.

LLKERNEL: Multi-Sandbox

The following API corresponds to architecture version 8.6.0.

LLKERNEL_impl.h

Set of functions that the BSP must implement to manage memory allocation of dynamically installed Applications.

Defines

LLKERNEL_OK (0)

Returned value when function call has succeeded.

LLKERNEL_ERROR (-1)

Returned value when function call has failed.

LLKERNEL_RAM_AREA_ALIGNMENT (8)

The RAM area alignment constraint.

LLKERNEL_ROM_AREA_ALIGNMENT (16)

The ROM area alignment constraint.

LLKERNEL_FEATURE_INIT_ERROR_CORRUPTED_CONTENT (1)

Error code thrown by LLKERNEL_onFeatureInitializationError function when the Installed Feature content is corrupted. The checksum computed during the installation does not match the actual computed checksum.

LLKERNEL_FEATURE_INIT_ERROR_INCOMPATIBLE_KERNEL_WRONG_UID (2)

Error code thrown by LLKERNEL_onFeatureInitializationError function when the Installed Feature has not been built for this Kernel UID or a compatible Kernel UID.

LLKERNEL_FEATURE_INIT_ERROR_TOO_MANY_INSTALLED (3)

Error code thrown by LLKERNEL_onFeatureInitializationError function when there is no internal free slot to connect the Installed Feature.

LLKERNEL_FEATURE_INIT_ERROR_ALREADY_INSTALLED (4)

Error code thrown by LLKERNEL_onFeatureInitializationError function when the Installed Feature matches an already Installed Feature.

LLKERNEL_FEATURE_INIT_ERROR_INCOMPATIBLE_KERNEL_WRONG_ADDRESSES (5)

Error code thrown by LLKERNEL_onFeatureInitializationError function when the Installed Feature has been linked on a Kernel Address Table with different content.

LLKERNEL_FEATURE_INIT_ERROR_ROM_OVERLAP (6)

Error code thrown by LLKERNEL_onFeatureInitializationError function when the Installed Feature ROM area overlaps the ROM area of an already Installed Feature.

LLKERNEL_FEATURE_INIT_ERROR_RAM_OVERLAP (7)

Error code thrown by LLKERNEL_onFeatureInitializationError function when the Installed Feature RAM area overlaps the RAM area of an already Installed Feature.

LLKERNEL_FEATURE_INIT_ERROR_RAM_ADDRESS_CHANGED (8)

Error code thrown by LLKERNEL_onFeatureInitializationError function when the RAM address returned by LLKERNEL_getFeatureAddressRAM is not equals to the RAM address returned when the Feature has been linked on this Kernel.

LLKERNEL_FEATURE_INIT_ERROR_NULL_HANDLE (9)

Error code thrown by LLKERNEL_onFeatureInitializationError function when a previous call to LLKERNEL_getFeatureHandle returned 0.

Functions

int32_t LLKERNEL_IMPL_allocateFeature(int32_t size_ROM, int32_t size_RAM)

Allocates a new Feature and reserves its ROM and RAM areas. If the Feature cannot be allocated, it must return 0.

Warning: ROM and RAM areas reservation must take care of address alignment constraints required by LLKERNEL_getFeatureAddressROM and LLKERNEL_getFeatureAddressRAM.

Parameters:

• size_ROM – the size in bytes to allocate in ROM

• size_RAM – the size in bytes to allocate in RAM

Returns:

a handle that uniquely identifies the allocated Feature, or 0 if the Feature could not be allocated.

void LLKERNEL_IMPL_freeFeature(int32_t handle)

Releases a Feature previously allocated using LLKERNEL_allocateFeature and frees its ROM and RAM areas.

Parameters:

• handle – the Feature handle

int32_t LLKERNEL_IMPL_getAllocatedFeaturesCount(void)

Retrieves the count of currently installed Features in memory.

A Feature is considered installed in memory if it has been successfully allocated using the LLKERNEL_allocateFeature method and has not been freed with the LLKERNEL_freeFeature method. This count may include Features that were installed in a previous execution of this Kernel.

Upon calling this method, the Core Engine will retrieve Feature handles by invoking LLKERNEL_getFeatureHandle for each index within the range [0..-1)].

See also

LLKERNEL_getFeatureHandle

Returns:

the current count of Features installed in memory, 0 if there are none.

int32_t LLKERNEL_IMPL_getFeatureHandle(int32_t index)

Retrieves the handle of a Feature that has been installed in memory.

This method is invoked by the Core Engine immediately following a call to LLKERNEL_getAllocatedFeaturesCount for each index within the range [0..-1].

See also

LLKERNEL_getAllocatedFeaturesCount

Parameters:

• index – an index within the range [0..-1].

Returns:

a unique handle that identifies the Feature at the specified index, or 0 if no valid handle is found.

void *LLKERNEL_IMPL_getFeatureAddressRAM(int32_t handle)

Gets the address of the allocated RAM area for the given Feature. The returned address must be LLKERNEL_RAM_AREA_ALIGNMENT bytes aligned.

Parameters:

• handle – the Feature handle

Returns:

the start address in bytes of the allocated RAM area, or NULL if the Feature handle is not valid.

void *LLKERNEL_IMPL_getFeatureAddressROM(int32_t handle)

Gets the address of the allocated ROM area for the given Feature. The returned address must be LLKERNEL_ROM_AREA_ALIGNMENT bytes aligned.

Parameters:

• handle – the Feature handle

Returns:

the start address in bytes of the allocated ROM area, or NULL if the Feature handle is not valid.

int32_t LLKERNEL_IMPL_copyToROM(void *dest_address_ROM, void *src_address, int32_t size)

Copies a sequence of bytes to ROM area. This function does not require that all bytes are really copied to the destination before it returns.

Parameters:

• dest_address_ROM – the start address in ROM (destination)

• src_address – the start address of bytes to copy (source)

• size – the number of bytes to copy

Returns:

LLKERNEL_OK on success, LLKERNEL_ERROR on error.

int32_t LLKERNEL_IMPL_flushCopyToROM(void)

This function is called once all calls to LLKERNEL_copyToROM are done for the currently allocated Feature. This function must block until all bytes are really copied to ROM area.

Returns:

LLKERNEL_OK on success, LLKERNEL_ERROR on error.

int32_t LLKERNEL_IMPL_onFeatureInitializationError(int32_t handle, int32_t error_code)

This function is called during Kernel boot when the initialization of an allocated Feature failed.

Parameters:

• handle – a Feature handle returned by LLKERNEL_getFeatureHandle

• error_code – the error code indicating the initialization error cause (see FEATURE_INIT_ERROR_* constants)

Returns:

LLKERNEL_OK to skip the initialization of this Feature and continue with the next allocated Feature, or LLKERNEL_ERROR if the Kernel must abruptly stop.

LLKERNEL.h

Set of functions provided by the Core Engine that can be called by the BSP.

Functions

int32_t LLKERNEL_quantaConsumed(int32_t quanta)

Notifies the scheduler that the current thread has consumed the given quanta.

The scheduler will increment the execution counter for the context of the current thread’s owner. This function allows explicitly specifying a quanta that reflects the computational complexity of a native function execution.

Parameters:

• quanta – the quanta consumed

Returns:

LLKERNEL_ERROR if this function is not called within the Core Engine task or if quanta is negative. Otherwise returns E_OK.

LLSP: Shielded Plug

Header Files

The implementation of the Shielded Plug assumes some support from the underlying RTOS. It is mainly related to provide some synchronization when reading / writing into Shielded Plug blocks.

• LLSP_IMPL_syncWriteBlockEnter and LLSP_IMPL_syncWriteBlockExit are used as a semaphore by RTOS tasks. When a task wants to write to a block, it “locks” this block until it has finished to write in it.

• LLSP_IMPL_syncReadBlockEnter and LLSP_IMPL_syncReadBlockExit are used as a semaphore by RTOS tasks. When a task wants to read a block, it “locks” this block until it is ready to release it.

The [SP] specification provides a mechanism to force a task to wait until new data has been provided to a block. The implementation relies on functions LLSP_IMPL_wait and LLSP_IMPL_wakeup to block the current task and to reschedule it.

LLEXT_RES: External Resources Loader

Principle

This LLAPI allows to use the External Resource Loader. When installed, the External Resource Loader is notified when the Core Engine is not able to find a resource (an image, a file etc.) in the resources area linked with the Core Engine.

When a resource is not available, the Core Engine invokes the External Resource Loader in order to load an unknown resource. The External Resource Loader uses the LLAPI EXT_RES to let the BSP loads or not the expected resource. The implementation has to be able to load several files in parallel.

Header Files

One header file is provided:

• LLEXT_RES_impl.h

  Defines the set of functions that the BSP must implement to load some external resources.

LLSERIAL: Serial Communications

Header Files

One C header file is provided:

• LLSERIAL_CONNECTION_impl.h

  Defines the set of functions that the BSP driver must implement to provide serial port communication. See Serial for implementation details.

Functions

void LLSERIAL_CONNECTION_IMPL_init(void)

Initializes the native stack.

int32_t LLSERIAL_CONNECTION_IMPL_open(uint8_t *portName)

Opens a connection to serial port with given name.

Note to the implementor of this function:

This function MUST register the returned connection ID as an SNI resource using SNI_registerResource(). The calling Java method registers the connection ID for garbage collection alongside its owner Java object, and registering it as an SNI resource is a prerequisite for this.

Note

The connection ID returned by this function must be configured using configure() before use. Most functions in this header require a configured connection.

Parameters:

• portName – the serial port name.

Throws NativeIOException:

(error code LLSERIAL_IOEXCEPTION_GENERIC) if an I/O error occurs.

Returns:

the connection ID, a SNI registered handle to operate on this connection.

void LLSERIAL_CONNECTION_IMPL_configure(int32_t connectionId, int32_t baudrate, int32_t databits, int32_t parity, int32_t stopbits)

Configures the connection.

See also

#open(uint8_t*) Connection ID

Parameters:

• connectionId – the connection ID.

• baudrate – the baud rate (e.g. 9600, 115200)

• databits – the number of data bits (see Data Bits Configuration)

• parity – the parity mode (see Parity Configuration)

• stopbits – the number of stop bits (see Stop Bits Configuration)

Throws NativeIOException:

(error code LLSERIAL_IOEXCEPTION_GENERIC) if an I/O error occurs while applying the configuration, or (error code LLSERIAL_IOEXCEPTION_UNSUPPORTED_CONFIG) if the requested configuration is not supported by the hardware.

int32_t LLSERIAL_CONNECTION_IMPL_read(int32_t connectionId, uint8_t *b, int32_t off, int32_t len)

Reads from the connection.

This method is blocking.

See also

#open(uint8_t*) Connection ID

See also

#available(int) Non-blocking read

Parameters:

• connectionId – the connection ID.

• b – the buffer into which the data is read.

• off – the start offset in array at which the data is written.

• len – the maximum number of bytes to read, must be > 0.

Throws NativeIOException:

(error code LLSERIAL_IOEXCEPTION_GENERIC) if an I/O error occurs.

Throws NativeException:

if the connectionId hasn’t been configured

Returns:

the total number of bytes read into the buffer, > 0.

int32_t LLSERIAL_CONNECTION_IMPL_available(int32_t connectionId)

Gets the number of available bytes that can be read without blocking.

See also

#open(uint8_t*) Connection ID

Parameters:

• connectionId – the connection ID.

Throws NativeIOException:

(error code LLSERIAL_IOEXCEPTION_GENERIC) if an I/O error occurs.

Throws NativeException:

if the connectionId hasn’t been configured

Returns:

the number of available bytes that can be read without blocking.

void LLSERIAL_CONNECTION_IMPL_write(int32_t connectionId, uint8_t *b, int32_t off, int32_t len)

Writes to the connection.

This method is blocking.

See also

#open(uint8_t*) Connection ID

Parameters:

• connectionId – the connection ID.

• b – the data.

• off – the start offset in the data.

• len – the number of bytes to write.

Throws NativeIOException:

(error code LLSERIAL_IOEXCEPTION_GENERIC) if an I/O error occurs.

Throws NativeException:

if the connectionId hasn’t been configured

void LLSERIAL_CONNECTION_IMPL_flush(int32_t connectionId)

Flushes the data buffered in write(int, byte[], int, int).

See also

#open(uint8_t*) Connection ID

Parameters:

• connectionId – the connection ID.

Throws NativeIOException:

(error code LLSERIAL_IOEXCEPTION_GENERIC) if an I/O error occurs.

Throws NativeException:

if the connectionId hasn’t been configured

void LLSERIAL_CONNECTION_IMPL_close(int32_t connectionId)

Closes the connection.

See also

#open(uint8_t*) Connection ID @implNote Implementations can assume flush(int) has been called before this.

Note to the implementor of this function:

The provided connectionId MUST be unregistered from managed SNI resources, using SNI_unregisterResource()

Parameters:

• connectionId – the connection ID.

Throws NativeIOException:

(error code LLSERIAL_IOEXCEPTION_GENERIC) if an I/O error occurs.

int64_t LLSERIAL_CONNECTION_IMPL_getCloseFunction(int32_t connectionId)

Returns a pointer to a native function, with signature void(<em>close)(void), responsible for freeing allocated/reserved/opened native resources.

Parameters:

• connectionId – the connection ID whose close function is requested

Returns:

a native function pointer

LLUI_INPUT: Input

LLUI_INPUT API is composed of the following files:

• the file LLUI_INPUT_impl.h that defines the functions to be implemented

• the file LLUI_INPUT.h that provides the functions for sending events

Implementation

LLUI_INPUT_IMPL_initialize is the first function called by the input engine, and it may be used to initialize the underlying devices and bind them to event generator IDs.

LLUI_INPUT_IMPL_enterCriticalSection and LLUI_INPUT_IMPL_exitCriticalSection need to provide the Input Engine with a critical section mechanism for synchronizing devices when sending events to the internal event queue. The mechanism used to implement the synchronization will depend on the VEE Port configuration (with or without RTOS), and whether or not events are sent from an interrupt context.

LLUI_INPUT_IMPL_getInitialStateValue allows the input stack to get the current state for devices connected to the MicroUI States event generator, such as switch selector, coding wheels, etc.

Sending Events

The LLUI_INPUT API provides two generic functions for a C driver to send data to its associated event generator:

• LLUI_INPUT_sendEvent: Sends a 32-bit event to a specific event generator, specified by its ID. If the input buffer is full, the event is not added, and the function returns LLUI_INPUT_NOK; otherwise it returns LLUI_INPUT_OK.

• LLUI_INPUT_sendEvents: Sends a frame constituted by several 32-bit events to a specific event generator, specified by its ID. If the input buffer cannot receive the whole data, the frame is not added, and the function returns LLUI_INPUT_NOK; otherwise it returns LLUI_INPUT_OK.

Events will be dispatched to the associated event generator that will be responsible for decoding them (see Generic Event Generators).

The UI extension provides an implementation for each of MicroUI’s built-in event generators. Each one has dedicated functions that allows a driver to send them structured data without needing to understand the underlying protocol to encode/decode the data. The following table shows the functions provided to send structured events to the predefined event generators:

LLUI_INPUT API for predefined event generators

Function name	Default event generator kind [1]	Comments
LLUI_INPUT_sendCommandEvent	Command	Constants are provided that define all standard MicroUI commands [MUI].
LLUI_INPUT_sendButtonPressedEvent LLUI_INPUT_sendButtonReleasedEvent LLUI_INPUT_sendButtonRepeatedEvent LLUI_INPUT_sendButtonLongEvent	Buttons	In the case of chronological sequences (for example, a RELEASE that may occur only after a PRESSED), it is the responsibility of the driver to ensure the integrity of such sequences.
LLUI_INPUT_sendPointerPressedEvent LLUI_INPUT_sendPointerReleasedEvent LLUI_INPUT_sendPointerMovedEvent	Pointer	In the case of chronological sequences (for example, a RELEASE that may occur only after a PRESSED), it is the responsibility of the driver to ensure the integrity of such sequences. Depending on whether a button of the pointer is pressed while moving, a DRAG and/or a MOVE MicroUI event is generated.
LLUI_INPUT_sendStateEvent	States	The initial value of each state machine (of a States) is retrieved by a call to LLUI_INPUT_IMPL_getInitialStateValue that must be implemented by the device. Alternatively, the initial value can be specified in the XML static configuration.
LLUI_INPUT_sendTouchPressedEvent LLUI_INPUT_sendTouchReleasedEvent LLUI_INPUT_sendTouchMovedEvent	Pointer	In the case of chronological sequences (for example, a RELEASE that may only occur after a PRESSED), it is the responsibility of the driver to ensure the integrity of such sequences. These APIs will generate a DRAG MicroUI event instead of a MOVE while they represent a touch pad over a display.

[1]

The implementation class is a subclass of the MicroUI class of the column.

Event Buffer

Functions LLUI_INPUT_IMPL_log_xxx allow logging the use of event buffer. Implementation of these LLAPIs is already available on the Central Repository (LLUI_INPUT_LOG_impl.c). This implementation is using an array to add some metadata to each event. This metadata is used when the BSP is calling LLUI_INPUT_dump(). When no implementation is included in the BSP, the call to LLUI_INPUT_dump() has no effect (no available logger).

Header Files

The version macros of LLUI_INPUT_impl.h are described with the display header files.

Functions

void LLUI_INPUT_IMPL_initialize(void)

Called by the input engine at startup to initialize all input devices.

jint LLUI_INPUT_IMPL_getInitialStateValue(jint stateMachinesID, jint stateID)

Called by the input engine at startup to get the initial state of the given state machine. Only called if a states event generator is defined in the static microui initializer xml file.

A states is a group of state machines. At any time state machine keeps a state. Each state machine has a 0-based ID: first state machine the ID 0, next state machine the ID 1 etc.

Parameters:

• stateMachinesID – [in] the state machines group ID.

• stateID – [in] the state machine ID in the state machines group.

Returns:

the initial state machine state.

void LLUI_INPUT_IMPL_enterCriticalSection(void)

Called by the input engine before entering in a critical section.

During the critical section no event must be added to the input queue. Therefore, the LLUI_INPUT_sendXXXEvent functions must not be called. There are several ways to implement the enterCriticalSection method:

• When all events are added to the input engine by OS task(s), the method must ensure that the current task is not pre-empted by another task during the critical section (use a binary semaphore)

• When some or all events are added to the input engine by interrupt routine(s), the method has to disable all interrupts that could generate inputs, and, if an interrupt is not currently being processed, ensure that the current task is not pre-empted by another task during the critical section.

Note that this function will never be called twice without an interleaving call to LLUI_INPUT_IMPL_leaveCriticalSection. Therefore the implementation does not need to support nested critical sections.

void LLUI_INPUT_IMPL_leaveCriticalSection(void)

Called by the input engine when exiting from a critical section.

See also

LLUI_INPUT_IMPL_enterCriticalSection.

void LLUI_INPUT_IMPL_log_queue_init(uint32_t length)

Initializes the MicroUI FIFO elements dumper.

MicroUI FIFO contains some events and some optional events’ data. MicroUI FIFO is not able to interpret these events and data. The logger must save event (or data)’s metadata to be able to interpret the event when dumping the FIFO.

The default logger uses LLTRACE_IMPL_record_event_xxx logger.

See also

LLUI_INPUT_dump().

Parameters:

• length – [in] the MicroUI FIFO (queue) size.

void LLUI_INPUT_IMPL_log_queue_full(uint32_t data)

Called by the input engine when an event (or its data) cannot be added to the MicroUI FIFO because the queue is full.

The default logger uses LLTRACE_IMPL_record_event_xxx logger.

Parameters:

• data – [in] the event or data that cannot be added to the queue.

void LLUI_INPUT_IMPL_log_queue_add(uint32_t data, uint32_t index, uint32_t remaining_elements, uint32_t queue_length)

Called by the input engine when an event (or its data) is added to the MicroUI FIFO.

The default logger uses LLTRACE_IMPL_record_event_xxx logger.

Parameters:

• data – [in] the event or data added to the queue.

• index – [in] the event or data’s index in queue.

• remaining_elements – [in] available number of remaining data to add in the queue to store the full event.

• queue_length – [in] available number of events and data not executed by MicroUI pump.

void LLUI_INPUT_IMPL_log_queue_replace(uint32_t old, uint32_t data, uint32_t index, uint32_t queue_length)

Called by the input engine when an event (or its data) replaces an older event (or data) in the MicroUI FIFO.

The default logger uses LLTRACE_IMPL_record_event_xxx logger.

Parameters:

• old – [in] the replaced event or data.

• data – [in] the new event or data.

• index – [in] the event or data’s index in queue.

• queue_length – [in] available number of events and data not executed by MicroUI pump.

void LLUI_INPUT_IMPL_log_queue_read(uint32_t data, uint32_t index)

Called by the input engine when an event (or its data) is read by the MicroUI pump.

The default logger uses LLTRACE_IMPL_record_event_xxx logger.

Parameters:

• data – [in] the event or data read by pump.

• index – [in] the event or data’s index in queue.

void LLUI_INPUT_IMPL_log_dump(bool log_type, uint32_t log, uint32_t index)

Dumps a MicroUI FIFO element (event or data) or the dump status.

The default logger does nothing and by consequence a call to LLUI_INPUT_dump() has no effect.

The dump status are:

• 0: start the dump: all next logs are the events or events’ data already consumed (“past” events) and first log is the latest event or data stored in the queue.

• 1: next logs are the events or data not consumed yet (“future” events).

• 2: the dump will log the Java objects associated with the events that are not consumed yet (“future” events); this feature is only available with the MicroEJ Architecture 7.16 and higher.

• 3: end of dump.

See also

LLUI_INPUT_dump().

Parameters:

• log_type – [in] true when the data is an event or a data, false when the data is a dump status.

• log – [in] the 32-bit event or data, or the dump status.

• index – [in] the event or data’s index in queue (ignored when the data is a dump status).

Defines

LLUI_INPUT_COMMAND_ESC (0)

The “escape” command constant. The value 0x0000 is assigned to COMMAND_ESC.

LLUI_INPUT_COMMAND_BACK (1)

The “back” command constant. The value 0x0001 is assigned to COMMAND_BACK.

LLUI_INPUT_COMMAND_UP (2)

The “up” command constant. The value 0x0002 is assigned to COMMAND_UP.

LLUI_INPUT_COMMAND_DOWN (3)

The “down” command constant. The value 0x0003 is assigned to COMMAND_DOWN.

LLUI_INPUT_COMMAND_LEFT (4)

The “left” command constant. The value 0x0004 is assigned to COMMAND_LEFT.

LLUI_INPUT_COMMAND_RIGHT (5)

The “right” command constant. The value 0x0005 is assigned to COMMAND_RIGHT.

LLUI_INPUT_COMMAND_SELECT (6)

The “select” command constant. The value 0x0006 is assigned to COMMAND_SELECT.

LLUI_INPUT_COMMAND_CANCEL (7)

The “cancel” command constant. The value 0x0007 is assigned to COMMAND_CANCEL.

LLUI_INPUT_COMMAND_HELP (8)

The “help” command constant. The value 0x0008 is assigned to COMMAND_HELP.

LLUI_INPUT_COMMAND_MENU (9)

The “menu” command constant. The value 0x0009 is assigned to COMMAND_MENU.

LLUI_INPUT_COMMAND_EXIT (10)

The “exit” command constant. The value 0x000A is assigned to COMMAND_EXIT.

LLUI_INPUT_COMMAND_START (11)

The “start” command constant. The value 0x000B is assigned to COMMAND_START.

LLUI_INPUT_COMMAND_STOP (12)

The “stop” command constant. The value 0x000C is assigned to COMMAND_STOP.

LLUI_INPUT_COMMAND_PAUSE (13)

The “pause” command constant. The value 0x000D is assigned to COMMAND_PAUSE.

LLUI_INPUT_COMMAND_RESUME (14)

The “resume” command constant. The value 0x000E is assigned to COMMAND_RESUME.

LLUI_INPUT_COMMAND_COPY (15)

The “copy” command constant. The value 0x000F is assigned to COMMAND_COPY.

LLUI_INPUT_COMMAND_CUT (16)

The “cut” command constant. The value 0x0010 is assigned to COMMAND_CUT.

LLUI_INPUT_COMMAND_PASTE (17)

The “paste” command constant. The value 0x0011 is assigned to COMMAND_PASTE.

LLUI_INPUT_COMMAND_CLOCKWISE (18)

The “clockwise” command constant. The value 0x0012 is assigned to COMMAND_CLOCKWISE.

LLUI_INPUT_COMMAND_ANTICLOCKWISE (19)

The “anti-clockwise” command constant. The value 0x0013 is assigned to COMMAND_ANTICLOCKWISE.

LLUI_INPUT_COMMAND_PREVIOUS (20)

The “previous” command constant. The value 0x0014 is assigned to COMMAND_PREVIOUS.

LLUI_INPUT_COMMAND_NEXT (21)

The “next” command constant. The value 0x0015 is assigned to COMMAND_NEXT.

LLUI_INPUT_COMMAND_DISPLAY (22)

The “display” command constant. The value 0x0016 is assigned to COMMAND_DISPLAY.

Enums

enum LLUI_INPUT_Status

LLUI_INPUT error and status codes.

These values are used by several LLUI_INPUT.h and LLUI_INPUT_IMPL.h functions. See each function comment to know which are the available codes.

Values:

enumerator LLUI_INPUT_OK = 0

Value when everything has been correctly executed.

enumerator LLUI_INPUT_NOK = -1

Value when an error has occurred or when a function is not able to implement the expected behavior.

enum LLUI_INPUT_Pointer

LLUI_INPUT pointer type of coordinates.

These values are used to specify the type of pointer coordinates.

Values:

enumerator LLUI_INPUT_ABSOLUTE = 0

Specifies the pointer coordinates are absolute.

enumerator LLUI_INPUT_RELATIVE = -1

Specifies the pointer coordinates are relative to the previous pointer position.

Functions

LLUI_INPUT_Status LLUI_INPUT_sendEvent(jint eventGeneratorID, jint event)

Add an event to the generic event generator.

The effect of this method is undefined when the given event generator (specified by eventGeneratorID) is not a MicroUI EventGenerator event generator. The event will not be added if the internal events buffer is full.

Parameters:

• eventGeneratorID – [in] the MicroUI EventGenerator event generator ID.

• event – [in] the 32-bit event.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendEvents(jint eventGeneratorID, jint *eventsArray, jint length)

Add several events to the generic event generator.

The effect of this method is undefined when the given event generator (specified by eventGeneratorID) is not a MicroUI EventGenerator event generator. The events will not be added if the internal events buffer is or becomes full. If the return value is not 1, no events have been added.

Parameters:

• eventGeneratorID – [in] the MicroUI EventGenerator event generator ID.

• eventsArray – [in] the address of the 32-bit events array.

• length – [in] the number of events (maximum 256 events).

Returns:

LLUI_INPUT_OK if all events have been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendCommandEvent(jint commandsEventGeneratorID, jint command)

Add a command event to the event generator.

The effect of this method is undefined when the given event generator (specified by commandsEventGeneratorID) is not a MicroUI Command event generator (tag <command> in microui xml file). The event will not be added if the internal events buffer is full.

Parameters:

• commandsEventGeneratorID – [in] the MicroUI Command event generator ID.

• command – [in] the command to send, between 0 and 255.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendButtonPressedEvent(jint buttonsEventGeneratorID, jint buttonId)

Add a PRESSED event to the event generator.

The effect of this method is undefined when the given event generator (specified by buttonsEventGeneratorID) is not a MicroUI Buttons event generator (tag <buttons> in microui xml file). The event will not be added if the internal events buffer is full. In this case the caller should not send next RELEASED event (and potential REPEATED event(s)) to prevent unexpected behavior.

Parameters:

• buttonsEventGeneratorID – [in] the MicroUI Buttons event generator ID.

• buttonId – [in] the button ID, between 0 and 255.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendButtonReleasedEvent(jint buttonsEventGeneratorID, jint buttonId)

Add a RELEASED event to the event generator.

The effect of this method is undefined when the given event generator (specified by buttonsEventGeneratorID) is not a MicroUI Buttons event generator (tag <buttons> in microui xml file). The event will not be added if the internal events buffer is full. In this case the caller should not send next PRESSED event to prevent unexpected behavior.

Parameters:

• buttonsEventGeneratorID – [in] the MicroUI Buttons event generator ID.

• buttonId – [in] the button ID, between 0 and 255.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendButtonRepeatedEvent(jint buttonsEventGeneratorID, jint buttonId)

Add a REPEATED event to the event generator.

The effect of this method is undefined when the given event generator (specified by buttonsEventGeneratorID) is not a MicroUI Buttons event generator (tag <buttons> in microui xml file). The event will not be added if the internal events buffer is full.

Parameters:

• buttonsEventGeneratorID – [in] the MicroUI Buttons event generator ID.

• buttonId – [in] the button ID, between 0 and 255.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendButtonLongEvent(jint buttonsEventGeneratorID, jint buttonId)

Add a LONG event to the event generator.

The effect of this method is undefined when the given event generator (specified by buttonsEventGeneratorID) is not a MicroUI Buttons event generator (tag <buttons> in microui xml file). The event will not be added if the internal events buffer is full.

Parameters:

• buttonsEventGeneratorID – [in] the MicroUI Buttons event generator ID.

• buttonId – [in] the button ID, between 0 and 255.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendPointerPressedEvent(jint pointerEventGeneratorID, jint buttonID, jint x, jint y, LLUI_INPUT_Pointer type)

Add a PRESSED event to the event generator.

The effect of this method is undefined when the given event generator (specified by pointerEventGeneratorID) is not a MicroUI Pointer event generator (tag <pointer> in microui xml file). The event will not be added if the internal events buffer is full. In this case the caller should not send next RELEASED event (and potential MOVE event(s)) to prevent unexpected behavior.

Parameters:

• pointerEventGeneratorID – [in] the MicroUI Pointer event generator ID.

• buttonID – [in] the button ID, between 0 and 255.

• x – [in] the pointer X coordinate.

• y – [in] the pointer Y coordinate.

• type – [in] LLUI_INPUT_ABSOLUTE when (x,y) coordinates are absolute,LLUI_INPUT_RELATIVE when there are relative to the previous pointer position.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendPointerReleasedEvent(jint pointerEventGeneratorID, jint buttonID)

Add a RELEASED event to the event generator.

The effect of this method is undefined when the given event generator (specified by pointerEventGeneratorID) is not a MicroUI Pointer event generator (tag <pointer> in microui xml file). The event will not be added if the internal events buffer is full. In this case the caller should not send next PRESSED event to prevent unexpected behavior.

Parameters:

• pointerEventGeneratorID – [in] the MicroUI Pointer event generator ID.

• buttonID – [in] the button ID, between 0 and 255.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendPointerMovedEvent(jint pointerEventGeneratorID, jint x, jint y, LLUI_INPUT_Pointer type)

Add a MOVE event to the event generator.

The effect of this method is undefined when the given event generator (specified by pointerEventGeneratorID) is not a MicroUI Pointer event generator (tag <pointer> in microui xml file). The event will not be added if the internal events buffer is full.

Parameters:

• pointerEventGeneratorID – [in] the MicroUI Pointer event generator ID.

• x – [in] the pointer X coordinate.

• y – [in] the pointer Y coordinate.

• type – [in] LLUI_INPUT_ABSOLUTE when (x,y) coordinates are absolute,LLUI_INPUT_RELATIVE when there are relative to the previous pointer position.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendTouchPressedEvent(jint touchEventGeneratorID, jint x, jint y)

Add a PRESSED event to the event generator.

The effect of this method is undefined when the given event generator (specified by touchEventGeneratorID) is not a MicroUI Pointer event generator (tag <touch> in microui xml file). The event will not be added if the internal events buffer is full. In this case the caller should not send next RELEASED event (and potential MOVE event(s)) to prevent unexpected behavior.

Parameters:

• touchEventGeneratorID – [in] the MicroUI Pointer event generator ID.

• x – [in] the pointer X coordinate.

• y – [in] the pointer Y coordinate.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendTouchReleasedEvent(jint touchEventGeneratorID)

Add a RELEASED event to the event generator.

The effect of this method is undefined when the given event generator (specified by touchEventGeneratorID) is not a MicroUI Pointer event generator (tag <touch> in microui xml file). The event will not be added if the internal events buffer is full. In this case the caller should not send next PRESSED event to prevent unexpected behavior.

Parameters:

• touchEventGeneratorID – [in] the MicroUI Pointer event generator ID.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendTouchMovedEvent(jint touchEventGeneratorID, jint x, jint y)

Add a MOVE event to the event generator.

The effect of this method is undefined when the given event generator (specified by touchEventGeneratorID) is not a MicroUI Pointer event generator (tag <touch> in microui xml file). The event will not be added if the internal events buffer is full.

Parameters:

• touchEventGeneratorID – [in] the MicroUI Pointer event generator ID.

• x – [in] the pointer X coordinate.

• y – [in] the pointer Y coordinate.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

LLUI_INPUT_Status LLUI_INPUT_sendStateEvent(jint statesEventGeneratorID, jint stateID, jint stateValue)

Add a STATE event to the event generator.

The effect of this method is undefined when the given event generator (specified by statesEventGeneratorID) is not a MicroUI States event generator (tag <states> in microui xml file). The event will not be added if the internal events buffer is full.

Parameters:

• statesEventGeneratorID – [in] the MicroUI States event generator ID.

• stateID – [in] the state machine identifier, between 0 and 255.

• stateValue – [in] the new state if the state machine, between 0 and 255.

Returns:

LLUI_INPUT_OK if the event has been added, LLUI_INPUT_NOK otherwise.

jint LLUI_INPUT_getMaxEventsBufferUsage(void)

Returns the maximum usage of the native events buffer. This can be useful for tuning the size of the buffer.

Returns:

the maximum usage of the native events buffer.

void LLUI_INPUT_dump(void)

Dumps the MicroUI FIFO.

MicroUI FIFO contains some events and some optional events’ data. MicroUI FIFO is not able to interpret these events and data. The interpretation is delegated to LLUI_INPUT_IMPL_log_dump(). The default logger does nothing and by consequence a call to LLUI_INPUT_dump() has no effect.

Events (and data) are dumped from older to newer. They are dumped in two categories: the events (and data) that are already executed (past) and the events (and data) that are not executed yet (future).

This function must only be called from the MicroJvm virtual machine thread context and only from a native function or callback. Calling this function from another context may lead to undefined behavior and should be done only for debug purpose.

LLUI_DISPLAY: Display

Initialization

Each Graphics Engine gets initialized by calling the function LLUI_DISPLAY_IMPL_initialize: It asks its display driver to initialize itself. The implementation function has to fill the given structure LLUI_DISPLAY_SInitData. This structure allows to retrieve the size of the virtual and physical screen, the back buffer address (where MicroUI is drawing). The implementation has to give two binary semaphores.

Image Heap

The display driver must reserve a runtime memory buffer for creating dynamic images when using MicroUI ResourceImage and BufferedImage classes methods. The display driver may choose to reserve an empty buffer. Thus, calling MicroUI methods will result in a MicroUIException exception.

The section name is .bss.microui.display.imagesHeap.

Functions LLUI_DISPLAY_IMPL_imageHeapXXX allow to control the image buffers allocation in the image heap. Implementation of these LLAPIs is already available on the Central Repository (LLUI_DISPLAY_HEAP_impl.c). This implementation is using a best fit allocator. It can be updated to log the allocations, the remaining space, etc. When no implementation is included in the BSP, the default Graphics Engine’s allocator (a best fit allocator) is used.

External Font Heap

The display driver must reserve a runtime memory buffer for loading external fonts (fonts located outside CPU addresses ranges). The display driver may choose to reserve an empty buffer. Thus, calling MicroUI Font methods will result in empty drawings of some characters.

The section name is .bss.microui.display.externalFontsHeap.

Flush and Synchronization

The back buffer (graphics buffer) address defined in the Initialization function is the address for the very first drawing. The content of this buffer is flushed to the external display memory by the function LLUI_DISPLAY_flush. The parameters define one or several rectangular regions of the content that have changed during the last drawing action and that must be flushed to the front buffer (dirty area). This function should be atomic: the implementation has to start another task or a hardware device (often a DMA) to perform the flush.

As soon as the Application performs a new drawing, the Graphics Engine locks the thread. It will automatically be unlocked when the BSP calls LLUI_DISPLAY_setBackBuffer at the end of the flush.

Display Characteristics

Function LLUI_DISPLAY_IMPL_isColor directly implements the method from the MicroUI Display class of the same name. The default implementation always returns true when the number of bits per pixel is higher than 4.

Function LLUI_DISPLAY_IMPL_getNumberOfColors directly implements the method from the MicroUI Display class of the same name. The default implementation returns a value according to the number of bits by pixel, without taking into consideration the alpha bit(s).

Function LLUI_DISPLAY_IMPL_isDoubleBuffered directly implements the method from the MicroUI Display class of the same name. The default implementation returns true. When LLAPI implementation targets a display in direct mode, this function must be implemented and return false.

Contrast

LLUI_DISPLAY_IMPL_setContrast and LLUI_DISPLAY_IMPL_getContrast are called to set/get the current display contrast intensity. The default implementations don’t manage the contrast.

BackLight

LLUI_DISPLAY_IMPL_hasBacklight indicates whether the display has backlight capabilities.

LLUI_DISPLAY_IMPL_setBacklight and LLUI_DISPLAY_IMPL_getBacklight are called to set/get the current display backlight intensity.

Color Conversions

The following functions are only useful (and called) when the display is not a standard display, see Pixel Structure.

LLUI_DISPLAY_IMPL_convertARGBColorToDisplayColor is called to convert a 32-bit ARGB MicroUI color in 0xAARRGGBB format into the “driver” display color.

LLUI_DISPLAY_IMPL_convertDisplayColorToARGBColor is called to convert a display color to a 32-bit ARGB MicroUI color.

CLUT

The function LLUI_DISPLAY_IMPL_prepareBlendingOfIndexedColors is called when drawing an image with indexed color. See CLUT to have more information about indexed images.

Image Decoders

The API LLUI_DISPLAY_IMPL_decodeImage allows to add some additional image decoders.

Header Files

The UI Pack replaces the tokens @LLUI_MAJOR_VERSION@, @LLUI_MINOR_VERSION@ and @LLUI_PATCH_VERSION@ with its own version. LLUI_INPUT_impl.h and LLUI_LED_impl.h define the same version macros. The VEE Port build replaces the tokens @LLUI_DISPLAY_FORMAT@ and @LLUI_DISPLAY_BPP@ with the display pixel format and its number of bits per pixel (see Display: Checking the Pixel Format).

Defines

LLUI_MAJOR_VERSION @LLUI_MAJOR_VERSION@

Low-Level API UI major version.

LLUI_MINOR_VERSION @LLUI_MINOR_VERSION@

Low-Level API UI minor version.

LLUI_PATCH_VERSION @LLUI_PATCH_VERSION@

Low-Level API UI patch version.

LLUI_DISPLAY_FORMAT @LLUI_DISPLAY_FORMAT@

Display pixel format the graphics engine was built for.

Resolved from display.properties by the display fragment PCA at VEE Port build.

LLUI_DISPLAY_BPP @LLUI_DISPLAY_BPP@

Display bits-per-pixel.

Resolved from display.properties by the display fragment PCA at VEE Port build.

LLUI_DISPLAY_IMPL_image_heap_initialize LLUI_DISPLAY_IMPL_imageHeapInitialize

Old naming convention, kept for backward compatibility.

Deprecated:

LLUI_DISPLAY_IMPL_image_heap_allocate LLUI_DISPLAY_IMPL_imageHeapAllocate

Old name of LLUI_DISPLAY_IMPL_imageHeapAllocate().

Deprecated:

Use LLUI_DISPLAY_IMPL_imageHeapAllocate() instead.

LLUI_DISPLAY_IMPL_image_heap_free LLUI_DISPLAY_IMPL_imageHeapFree

Old name of LLUI_DISPLAY_IMPL_imageHeapFree().

Deprecated:

Use LLUI_DISPLAY_IMPL_imageHeapFree() instead.

struct LLUI_DISPLAY_SInitData

#include <LLUI_DISPLAY_impl.h>

Public Members

LLUI_DISPLAY_binary_semaphore *binary_semaphore_0

Binary semaphore used by the Graphics Engine.

This semaphore must be configured in a state such that the semaphore must first be ‘given’ before it can be ‘taken’.

This semaphore is reserved for the Graphics Engine. The LLUI_DISPLAY_IMPL.h implementation is not allowed to use this semaphore to synchronize the function LLUI_DISPLAY_IMPL_flush() with the display driver (or for any other synchronization actions). The implementation must create its own semaphores in addition with this dedicated Graphics Engine’s semaphore.

LLUI_DISPLAY_binary_semaphore *binary_semaphore_1

Binary semaphore used by the Graphics Engine.

This semaphore must be configured in a state such that the semaphore must first be ‘given’ before it can be ‘taken’.

For more information on this semaphore, refer to the binary_semaphore_0’s documentation.

uint8_t *back_buffer_address

Back buffer address on startup.

This buffer will be used by the Graphics Engine to draw application drawings. In SINGLE and DIRECT modes, this buffer address is used during all application runtime. In SWAP mode, this buffer address will be internally updated by the Graphics Engine (see LLUI_DISPLAY_setBackBuffer()).

uint32_t lcd_width

LCD width in pixels.

This size must not be higher than 65535.

uint32_t lcd_height

LCD height in pixels.

This size must not be higher than 65535.

uint32_t memory_width

Display front buffer width in pixels.

The display graphics buffer (front buffer) may require more memory than theoretical memory. Theoretical memory size is: lcd_width * lcd_height * bpp / 8.

On some devices the memory width (in pixels) is higher than virtual width. In this way, the graphics buffer memory size is: memory_width * memory_height * bpp / 8.

Keep this value to 0 when memory_width is equals to lcd_width. An error is thrown by the Graphics Engine when memory_width is smaller than lcd_width.

This size must not be higher than 65535.

uint32_t memory_height

Display front buffer height in pixels.

The display graphics buffer (front buffer) may require more memory than theoretical memory. Theoretical memory size is: lcd_width * lcd_height * bpp / 8.

On some devices the memory height (in pixels) is higher than virtual height. In this way, the graphics buffer memory size is: memory_width * memory_height * bpp / 8.

Keep this value to 0 when memory_height is equals to lcd_height. An error is thrown by the Graphics Engine when memory_height is smaller than lcd_height.

This size must not be higher than 65535.

Functions

void LLUI_DISPLAY_IMPL_initialize(LLUI_DISPLAY_SInitData *init_data)

Initializes the display driver. Called by the Graphics Engine when MicroEJ application is calling MicroUI.start().

Given structure must be initialized with expected data. See LLUI_DISPLAY_SInitData comments.

The graphics engine blocks (infinite loop) if:

• the structure is not correctly filled,

• the semaphores are not configured as expected.

Parameters:

• init_data – [out] the data to initialize.

void LLUI_DISPLAY_IMPL_binarySemaphoreTake(void *binary_semaphore)

Takes the binary semaphore.

Parameters:

• binary_semaphore – [in] the binary semaphore to take.

void LLUI_DISPLAY_IMPL_binarySemaphoreGive(void *binary_semaphore, bool from_isr)

Gives the binary semaphore.

Parameters:

• binary_semaphore – [in] the binary semaphore to give.

• from_isr – [in] true when giving the semaphore from an interrupt.

void LLUI_DISPLAY_IMPL_flush(MICROUI_GraphicsContext *gc, uint8_t flush_identifier, const ui_rect_t regions[], size_t length)

Performs a flush: the content of the back buffer (address returned by LLUI_DISPLAY_getBufferAddress(gc->image)) has to be flushed to the front buffer (display’s buffer).

The content of given rectangles in the graphics buffer (back buffer) must be displayed into the LCD buffer (front buffer). The rectangles specified are the regions which have changed during last draw and only these regions should be updated (drawing regions). The number of rectangles depends on the display buffer refresh strategy (BRS).

There are several ways to update the display, depending on the display flushing mode (see UI documentation).

Parameters:

• gc – [in] the graphics context that targets the back buffer to flush.

• flush_identifier – [in] a value that identifies the flush; the next call(s) to LLUI_DISPLAY_setBackBuffer() (that notify the end of flush) must use this identifier.

• regions – [in] an array of modified rectangular regions in the back buffer since last flush

• length – [in] the available number of regions

DRAWING_Status LLUI_DISPLAY_IMPL_refresh(MICROUI_GraphicsContext *gc, uint8_t flush_identifier)

This function allows to plug a display buffer refresh strategy (BRS) (see the MicroUI Abstraction Layer). By default, no strategy is used and the Graphics Engine only calls LLUI_DISPLAY_IMPL_flush() with a single rectangle that fits the full display area.

Parameters:

• gc – [in] the graphics context that targets the back buffer to flush.

• flush_identifier – [in] a value that identifies the flush; the next call(s) to LLUI_DISPLAY_setBackBuffer() (that notify the end of flush) must use this identifier.

Returns:

DRAWING_DONE once LLUI_DISPLAY_IMPL_flush() has been called; DRAWING_RUNNING when an asynchronous restore step has been started instead: its end must be notified by LLUI_DISPLAY_notifyAsynchronousDrawingEnd(), after which the Graphics Engine calls this function again.

DRAWING_Status LLUI_DISPLAY_IMPL_newDrawingRegion(MICROUI_GraphicsContext *gc, ui_rect_t *region, bool drawing_now)

Notifies that a region will be modified by the application in the display back buffer.

This function is called by the Graphics Engine:

• For each call to LLUI_DISPLAY_requestDrawing() (in the display back buffer) if the drawing region set by the application is different than the previous drawing region. In this case, the drawing_now parameter is set to true.

• For each call to GraphicsContext.notifyDirtyRegion(). In this case, the drawing_now parameter is set to false.

The implementation (the BRS) can perform some drawings. If these drawings are asynchronous (often executed by a GPU), this function must return DRAWING_RUNNING. The execution will be suspended until the next call to LLUI_DISPLAY_notifyAsynchronousDrawingEnd(). The same function will be called again just after.

If the drawings are synchronous, this function has to return DRAWING_DONE.

As soon as all drawings (asynchronous or synchronous) are made, the Graphics Engine gives the hand to the caller to LLUI_DISPLAY_requestDrawing().

Parameters:

• gc – [in] the graphics context of the back buffer

• region – [in] the drawing region

• drawing_now – [in] true if the region will be altered just after this call

Returns:

DRAWING_RUNNING if a drawing has been started or DRAWING_DONE when the caller of LLUI_DISPLAY_requestDrawing() can draw in the display back buffer.

void LLUI_DISPLAY_IMPL_imageHeapInitialize(uint8_t *heap_start, uint8_t *heap_limit)

Initializes the MicroUI images heap. This heap is used to decode at runtime PNG images, to store the MicroUI BufferedImage, etc.

The heap size is fixed by the MicroEJ application launcher. It is allocated in the section .bss.microui.display.imagesHeap.

This function is not called by the Graphics Engine if the size is too small. By consequence, all allocations will return an out of memory error.

The default implementation is using a best fit allocator: BESTFIT_ALLOCATOR_new(&image_heap); BESTFIT_ALLOCATOR_initialize(&image_heap, (int32_t)heap_start, (int32_t)heap_limit);

Parameters:

• heap_start – [in] bss section start address.

• heap_limit – [in] bss section end address + 1.

uint8_t *LLUI_DISPLAY_IMPL_imageHeapAllocate(uint32_t size)

Allocates a block in the images heap.

The default implementation is using a best fit allocator: return (uint8_t*)BESTFIT_ALLOCATOR_allocate(&image_heap, (int32_t)size);

Parameters:

• size – [in] the block size.

Returns:

the block address or NULL in case of out of memory.

void LLUI_DISPLAY_IMPL_imageHeapFree(uint8_t *block)

Frees a block in images heap.

The default implementation is using a best fit allocator: BESTFIT_ALLOCATOR_free(&image_heap, (void*)block);

Parameters:

• block – [in] the block to free.

void LLUI_DISPLAY_IMPL_setContrast(uint32_t contrast)

Sets the new contrast. By default the weak function does nothing (feature not supported).

Parameters:

• contrast – [in] a value between 0 and 100.

uint32_t LLUI_DISPLAY_IMPL_getContrast(void)

Gets the current contrast. By default the weak function returns 0.

Returns:

a value between 0 and 100.

bool LLUI_DISPLAY_IMPL_hasBacklight(void)

Returns true when the display module can manage the display backlight, false otherwise. By default the weak function returns false (feature not supported).

Returns:

true or false.

void LLUI_DISPLAY_IMPL_setBacklight(uint32_t backlight)

Sets the new backlight value. By default the weak function does nothing (feature not supported).

Parameters:

• backlight – [in] a value between 0 and 100.

uint32_t LLUI_DISPLAY_IMPL_getBacklight(void)

Gets the current backlight value. By default the weak function returns 0.

Returns:

a value between 0 and 100.

bool LLUI_DISPLAY_IMPL_isColor(void)

Asks if the display is a colored display or not.

Returns:

true when the display is not a grayscale display, false otherwise. By default the weak function returns false when the BPP is lower than or equals to 4 BPP and true otherwise.

uint32_t LLUI_DISPLAY_IMPL_getNumberOfColors(void)

Returns the number of colors the display can display.

Usually the number of colors is 1 << BPP (BPP without transparency bits). By default the weak function returns a value which follows this rule.

Returns:

the number of colors the display can display.

bool LLUI_DISPLAY_IMPL_isDoubleBuffered(void)

Asks if the display uses an underlying double buffer (either hardware or software).

This technique is useful to avoid flickering while the user is drawing.

Returns:

true if and only if a double buffer is used for the display false otherwise. By default the weak function returns true.

uint32_t LLUI_DISPLAY_IMPL_convertARGBColorToDisplayColor(uint32_t color)

Converts the 32-bit ARGB color format (A-R-G-B) into the display color format.

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: MICROUI_IMAGE_FORMAT_ARGB8888, MICROUI_IMAGE_FORMAT_RGB888, MICROUI_IMAGE_FORMAT_RGB565, MICROUI_IMAGE_FORMAT_ARGB1555 or MICROUI_IMAGE_FORMAT_ARGB4444. In case of this function is not implemented whereas it is required, the result of pixel drawing is unknown.

Note: the alpha level may be ignored if the display pixel representation does not hold the alpha level information.

The implementation should not directly call this function when performing a drawing. It must call LLUI_DISPLAY_convertARGBColorToDisplayColor() instead in case of this conversion is Graphics Engine built-in (standard display)

Parameters:

• color – [in] the color to convert.

Returns:

the converted color.

uint32_t LLUI_DISPLAY_IMPL_convertDisplayColorToARGBColor(uint32_t color)

Converts the display color format into a 32-bit ARGB color format (A-R-G-B).

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: MICROUI_IMAGE_FORMAT_ARGB8888, MICROUI_IMAGE_FORMAT_RGB888, MICROUI_IMAGE_FORMAT_RGB565, MICROUI_IMAGE_FORMAT_ARGB1555 or MICROUI_IMAGE_FORMAT_ARGB4444. In case of this function is not implemented whereas it is required, the result of pixel drawing is unknown.

Note: the alpha level may be ignored if the display pixel representation does not hold the alpha level information. In this case, the returned alpha level is 0xff (full opaque).

Parameters:

• color – [in] the color to convert.

Returns:

the converted color.

bool LLUI_DISPLAY_IMPL_prepareBlendingOfIndexedColors(uint32_t *foreground, uint32_t *background)

Prepares the blending of two ARGB colors.

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: MICROUI_IMAGE_FORMAT_ARGB8888, MICROUI_IMAGE_FORMAT_RGB888, MICROUI_IMAGE_FORMAT_RGB565, MICROUI_IMAGE_FORMAT_ARGB1555 or MICROUI_IMAGE_FORMAT_ARGB4444.

This is useful only when the LCD is a palletized LCD. This function is called by framework when the MicroEJ application draws something which requires a blending between the current foreground color and a specific background color (draw a string, draw an anti-aliased line etc.).

The implementation has to replace the ARGB colors by the indexes of these colors in the LCD CLUT. The framework will use the intermediate values between these two indexes instead of blending in software the ARGB colors. No post conversion will be performed later.

When the ARGB colors are not available in the CLUT or when the range specified by the two ARGB colors is not expected by the CLUT, the implementation should return false (feature not supported). In this way the blending will be done in software and the result color will be converted later thanks a call to LLUI_DISPLAY_convertARGBColorToDisplayColor().

By default the weak function returns false (feature not supported / useless).

Parameters:

• foreground – [inout] pointer on the foreground ARGB color to convert.

• background – [inout] pointer on the background ARGB color to convert.

Returns:

true when the indexes have been found, false otherwise.

LLUI_DISPLAY_Status LLUI_DISPLAY_IMPL_decodeImage(uint8_t *addr, uint32_t length, jbyte expectedFormat, MICROUI_Image *image, bool *isFullyOpaque)

Use an hardware image decoder to create a RAW image.

The RAW image format is given by expectedFormat parameter. The decoder can choose another RAW image output format when it is not able to apply the expected format.

The implementation has to fill the given MICROUI_Image structure with the image characteristics: its width, height, and the chosen RAW image format. The others fields no need to be filled.

To allocate the RAW image pixels area, the implementation has to call the function LLUI_DISPLAY_allocateImageBuffer(), giving the filled MICROUI_Image as parameter. This function will allocate the required memory area in the images heap.

The implementation returns LLUI_DISPLAY_OK when the RAW image has been created. It has to return LLUI_DISPLAY_NOK when the hardware decoder is not able to decode the given image. If the function LLUI_DISPLAY_allocateImageBuffer() returns false (means “out of memory”), the implementation has to return LLUI_DISPLAY_OUT_OF_MEMORY.

Parameters:

• addr – [in] the source image address.

• length – [in] the source image size in bytes.

• expectedFormat – [in] the RAW image expected format. The format is one value from the MICROUI_ImageFormat enumeration. (MICROUI_IMAGE_FORMAT_CUSTOM means the implementation can choose the better output format).

• image – [out] the reserved MicroUI Image; implementation has to fill it with the image characteristics.

• isFullyOpaque – [out] a boolean to notify to the that the decoded image is fully opaque or not; when fully opaque, the software algorithms which use the image as source image are often faster (even if the image format contains alpha levels).

Returns:

LLUI_DISPLAY_OK when decoding is successful.

int32_t LLUI_DISPLAY_IMPL_getDrawerIdentifier(jbyte image_format)

Gets the drawing engine able to draw in the GraphicsContext whose format is the given format.

When the Graphics Context format is the same as the display buffer (see LLUI_DISPLAY_isDisplayFormat()), the drawing engine (called “drawer”) may be the same as the one used to draw in the display buffer: the software algorithms will be used by default and the VEE Port can override one or several drawing functions to use a GPU.

When this format is not same as the display buffer (see LLUI_DISPLAY_isDisplayFormat()), a dedicated drawer must be used. This engine is identified by an identifier: a value between 0 and 255. This identifier is stored in the structure “MICROUI_GraphicsContext” (see “drawer”). “0” identifies the “display buffer” drawing engine.

This function can return a negative value to indicate that the VEE Port does not support the destination format (no available drawing engine). It will throw an exception in the application.

Parameters:

• image_format – [in] the new RAW image format. The format is one value from the MICROUI_ImageFormat enumeration.

Returns:

a drawing engine identifier, between 0 and 255, all other values indicate “no available drawing engine”.

uint32_t LLUI_DISPLAY_IMPL_getNewImageStrideInBytes(jbyte image_format, uint32_t image_width, uint32_t image_height, uint32_t default_stride)

Returns the new image row stride in bytes.

Some hardware accelerators require a specific row stride when manipulating images. This function allows to fix the new runtime image size. A default stride is given; this stride is calculated according the image format and platform characteristics.

The retained row stride is the higher value between the default row stride and the returned value. This value will be used to allocate the new image pixel buffer.

This value can be retrieved later using the functions LLUI_DISPLAY_getStrideInBytes() and LLUI_DISPLAY_getStrideInPixels().

This function is only called when the number of bits-per-pixel is higher or equals to 8. For lower values, default stride is always used.

By default the weak function returns default row stride.

Parameters:

• image_format – [in] the new RAW image format. The format is one value from the MICROUI_ImageFormat enumeration.

• image_width – [in] the new image width (in pixels).

• image_height – [in] the new image height (in pixels).

• default_stride – [in] the minimal row stride (in bytes)

Returns:

expected row stride (in bytes)

void LLUI_DISPLAY_IMPL_adjustNewImageCharacteristics(jbyte image_format, uint32_t width, uint32_t height, uint32_t *data_size, uint32_t *data_alignment)

Adjusts the new image characteristics: data size and alignment.

The image format can be platform generic or specific.

For the generic RAW formats, the data size is already calculated according the image format (bpp) and the image dimensions. The platform can increase this value to add a custom header before the first pixel data (top-left pixel: 0,0). This header can be used by some GPU to store metadata. If the returned size is smaller than the calculated size, the custom header is considered as useless and ignored.

For the custom image formats, the given data size is 0. The platform has the responsability to give a valid size to allocate the custom header. This header must, at least, keeps a pointer on the custom image data. An error is thrown at runtime if this function does not set a positive value for data_size.

The value returned by LLUI_DISPLAY_getBufferAddress() points on this custom header if exists. Otherwise, it points on first image data (top-left pixel: 0,0).

The data alignment value is used by the allocator to align the image buffer (with or without custom header) address. A default alignment is set and the bigger alignment is kept.

Parameters:

• image_format – [in] the new RAW image format. The format is one value from the MICROUI_ImageFormat enumeration.

• width – [in] the new image width (in pixels).

• height – [in] the new image height (in pixels).

• data_size – [inout] the minimal data size (in bytes).

• data_alignment – [inout] the minimal data alignment to respect (in bytes).

void LLUI_DISPLAY_IMPL_initializeNewImage(MICROUI_Image *image)

Initializes the image’s buffer: the image data when it is a custom image (see LLUI_DISPLAY_IMPL_getDrawerIdentifier()), an optional custom header (see LLUI_DISPLAY_IMPL_adjustNewImageCharacteristics()), etc.

This function can retrieve the image buffer address by calling LLUI_DISPLAY_getBufferAddress(). The image format (generic or custom) and the image dimensions can be also useful to initialize a custom header (see struct MICROUI_Image and LLUI_DISPLAY_IMPL_adjustNewImageCharacteristics()).

Parameters:

• image – [in] the MicroUI Image to initialize.

void LLUI_DISPLAY_IMPL_freeImageResources(MICROUI_Image *image)

Frees the image’s third-party resources. For a given image format, some resources may have been allocated. This call allows to free them before freeing the image buffer itself.

This function can retrieve the image buffer address by calling LLUI_DISPLAY_getBufferAddress().

Parameters:

• image – [in] the MicroUI Image being closed.

void LLUI_DISPLAY_IMPL_lockJob(void)

This function allows the use of reentrant mode (thread-safe) in the Graphics Engine via a task different from that of the MicroJvm virtual machine.

The relevant reentrant functions are:

• LLUI_DISPLAY_allocateImageBuffer()

• LLUI_DISPLAY_freeImageBuffer()

• LLUI_DISPLAY_decodeImage()

  All others functions are already thread-safe or not concerned. If these reentrant functions are not used or are only used within the MicroJvm virtual machine’s task, the lock() and unlock() functions do not need to be implemented (the default implementation does nothing). Otherwise, the LLUI port must implement these functions using, for example, a mutex.

  The mutex must be recursive (decodeImage() calls allocateImage() and freeImage()).

void LLUI_DISPLAY_IMPL_unlockJob(void)

Exits the re-entrant mode.

See also

LLUI_DISPLAY_IMPL_lockJob

void LLUI_DISPLAY_IMPL_notifyDrawingSoft(MICROUI_GraphicsContext *gc)

Called by the Graphics Engine when a drawing is rendered by a software algorithm (CPU drawing).

This function notifies the low-level part that a soft drawing operation has been completed, allowing for any necessary updates or state changes:

- Print a message: `printf("[WARNING] CPU drawing\n");`
- Report a drawing log flag warning (custom or generic), the application has to check the flag:
  LLUI_DISPLAY_reportWarning(gc, DRAWING_LOG_FORBIDDEN);
- Report a drawing log flag error (custom or generic), the flag is checked at flush time if the
  target is the display buffer:
  LLUI_DISPLAY_reportError(gc, DRAWING_LOG_FORBIDDEN);
- Store the soft drawing in an user flag
  LLUI_DISPLAY_testAndSetUserFlag(gc, FLAG_SOFTWARE_DRAWING, true);

For example, this function serves to remember that a soft drawing has occurred before executing a GPU drawing. To achieve this, it should be paired with the LLUI_DISPLAY_testAndSetUserFlag() function, which can save the state of the soft drawing in the GraphicsContext. This ensures that the memory cache can be cleared before initiating the subsequent GPU draw.

Example usage:

#define FLAG_SOFTWARE_DRAWING ((uint8_t)0x1)

void LLUI_DISPLAY_IMPL_notifyDrawingSoft(MICROUI_GraphicsContext *gc) {
    // tags the drawing (don't care about old mask)
    (void)LLUI_DISPLAY_testAndSetUserFlag(gc, FLAG_SOFTWARE_DRAWING, true);
}

void GPU_drawing(MICROUI_GraphicsContext *gc, a, b, c){
    [...]
    if (LLUI_DISPLAY_testAndSetUserFlag(gc, FLAG_SOFTWARE_DRAWING, false)) {
        clear_cache();
    }
    [...]
}

See also

LLUI_DISPLAY_testAndSetUserFlag

Parameters:

• gc – [in] the MicroUI GraphicsContext

Defines

LLUI_DISPLAY_setDrawingBuffer LLUI_DISPLAY_setBackBuffer

Old name of LLUI_DISPLAY_setBackBuffer().

Deprecated:

Use LLUI_DISPLAY_setBackBuffer() instead.

Functions

static inline void LLUI_DISPLAY_reportWarning(MICROUI_GraphicsContext *gc, jint flags)

Function to report a non-critical incident that occurred during a drawing operation.

Sets drawing_log_flags in a MICROUI_GraphicsContext. This will not set the DRAWING_LOG_ERROR flag (unless explicitly specified as a parameter), which will not cause an exception to be thrown when checking the flags in the application. This is meant to report non-critical incidents.

Parameters:

• gc – [in] the MicroUI GraphicsContext of the drawing.

• flags – [in] the drawing log flags to set.

static inline void LLUI_DISPLAY_reportError(MICROUI_GraphicsContext *gc, jint flags)

Function to report an error that occurred during a drawing operation.

Sets drawing_log_flags in a MICROUI_GraphicsContext. This will additionally set the DRAWING_LOG_ERROR flag, causing an exception to be thrown when checking the flags in the application.

Parameters:

• gc – [in] the MicroUI GraphicsContext of the drawing.

• flags – [in] the drawing log flags to set, in addition to DRAWING_LOG_ERROR.

bool LLUI_DISPLAY_isLCD(MICROUI_Image *image)

Returns true when the given MicroUI Image specified targets the LCD, in other words, if the image targets the same buffer than the current LCD back buffer.

Parameters:

• image – [in] the MicroUI Image to check.

Returns:

true when the image targets the LCD.

MICROUI_Image *LLUI_DISPLAY_getSourceImage(MICROUI_Image *image)

Returns an image that targets the front buffer (display buffer) instead of the back buffer.

This behavior only concerns the following use case:

• the image targets the display (not an image),

• the display buffer refresh strategy (BRS) has not restored yet the content of the old back buffer to the current back buffer.

In that case, the read actions (GraphicsContext.readPixel(), Painter.drawDisplayRegion(), etc.) cannot use the back buffer as source buffer. The algorithm has to call LLUI_DISPLAY_getSourceImage() to retrieve a pointer to the front buffer address.

For all other use cases, the returned image is the given parameter.

Parameters:

• image – [in] the MicroUI Image to read.

Returns:

the image to read the pixels from.

bool LLUI_DISPLAY_isImageClosed(MICROUI_Image *image)

Checks if an image has been closed.

Returns true if the given MicroUI Image has been closed by the MicroEJ application.

Parameters:

• image – [in] the image

Returns:

true if the image has been closed

static inline bool LLUI_DISPLAY_isClosed(MICROUI_Image *image)

Alias for LLUI_DISPLAY_isImageClosed.

Deprecated:

Provided for backward compatibility.

Parameters:

• image – [in] the image

Returns:

true if the image has been closed

void LLUI_DISPLAY_configureClip(MICROUI_GraphicsContext *gc, bool enable)

Enables or disables the graphics context clip. Useful to ignore clip during a drawing. The clip is automatically re-enabled when calling LLUI_DISPLAY_requestDrawing().

Parameters:

• gc – [in] the MicroUI GraphicsContext where ignoring the clip.

• enable – [in] false to disable the clip.

bool LLUI_DISPLAY_isClipEnabled(MICROUI_GraphicsContext *gc)

Tells if the clip is enabled or not. This call should be performed at the beginning of a drawing function in order to prevent to make some useless operations when the clip is disabled.

When it is disabled, that means the caller considers the drawing is fitting the clip. In this case checking the clip bounds is useless.

Parameters:

• gc – [in] the MicroUI GraphicsContext where checking the clip.

Returns:

true when the clip is enabled (the clip must be checked).

void LLUI_DISPLAY_setClip(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height)

Function to modify the clip area in a graphics context.

The user must save the current clip area before modifying it and restore it afterwards.

This function sets the flag DRAWING_LOG_CLIP_MODIFIED as it does not modify the clip values of the GraphicsContext used in the application.

Parameters:

• gc – [in] the MicroUI GraphicsContext to modify.

• x – [in] the x coordinate of the clip area.

• y – [in] the y coordinate of the clip area.

• width – [in] the width of the clip area.

• height – [in] the height of the clip area.

void LLUI_DISPLAY_intersectClip(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height)

Function to modify the clip area in a graphics context.

The resulting clip area will be the intersection of the current clip area and the clip area passed as arguments.

The user must save the current clip area before modifying it and restore it afterwards.

This function sets the flag DRAWING_LOG_CLIP_MODIFIED as it does not modify the clip values of the GraphicsContext used in the application.

Parameters:

• gc – [in] the MicroUI GraphicsContext to modify.

• x – [in] the x coordinate of the clip area.

• y – [in] the y coordinate of the clip area.

• width – [in] the width of the clip area.

• height – [in] the height of the clip area.

bool LLUI_DISPLAY_isPixelInClip(MICROUI_GraphicsContext *gc, jint x, jint y)

Tells if given pixel fits the clip or not.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the pixel X coordinate.

• y – [in] the pixel Y coordinate.

Returns:

false when the point is outside the clip.

bool LLUI_DISPLAY_isHorizontalLineInClip(MICROUI_GraphicsContext *gc, jint x1, jint x2, jint y)

Tells if given horizontal line fully fits the clip or not.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x1 – [in] the first pixel line X coordinate.

• x2 – [in] the last pixel line X coordinate.

• y – [in] the both pixels line Y coordinate.

Returns:

false when the line is fully or partially outside the clip, true when line fully fits the clip (clip can be disabled).

bool LLUI_DISPLAY_isVerticalLineInClip(MICROUI_GraphicsContext *gc, jint y1, jint y2, jint x)

Tells if given vertical line fully fits the clip or not.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the both pixels line X coordinate.

• y1 – [in] the first pixel line Y coordinate.

• y2 – [in] the last pixel line Y coordinate.

Returns:

false when the line is fully or partially outside the clip, true when line fully fits the clip (clip can be disabled).

bool LLUI_DISPLAY_isRectangleInClip(MICROUI_GraphicsContext *gc, jint x1, jint y1, jint x2, jint y2)

Tells if given rectangle fully fits the clip or not.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x1 – [in] the top-left pixel X coordinate.

• y1 – [in] the top-left pixel Y coordinate.

• x2 – [in] the bottom-right pixel X coordinate.

• y2 – [in] the bottom-right pixel Y coordinate.

Returns:

false when the rectangle is fully or partially outside the clip, true when rectangle fully fits the clip (clip can be disabled).

bool LLUI_DISPLAY_isRegionInClip(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height)

Tells if given region (from x,y to x+width-1,y+height-1) fully fits the clip or not.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the region width.

• height – [in] the region height.

Returns:

false when the region is fully or partially outside the clip, true when region fully fits the clip (clip can be disabled).

bool LLUI_DISPLAY_clipHorizontalLine(MICROUI_GraphicsContext *gc, jint *x1, jint *x2, jint y)

Tells if given horizontal line fits the clip or not. If at least one pixel fits the clip, the horizontal line size is cropped. The line may be partially cropped even if the line is fully outside the clip. The line is not cropped when the line fully fits the clip.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x1 – [inout] pointer on the first pixel line X coordinate.

• x2 – [inout] pointer on the last pixel line X coordinate.

• y – [in] the both pixels line Y coordinate.

Returns:

false when the line is fully outside the clip, true when at least one pixel fits the clip.

bool LLUI_DISPLAY_clipVerticalLine(MICROUI_GraphicsContext *gc, jint *y1, jint *y2, jint x)

Tells if given vertical line fits the clip or not. If at least one pixel fits the clip, the vertical line size is cropped. The line may be partially cropped even if the line is fully outside the clip. The line is not cropped when the line fully fits the clip.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the both pixels line X coordinate.

• y1 – [inout] pointer on the first pixel line Y coordinate.

• y2 – [inout] pointer on the last pixel line Y coordinate.

Returns:

false when the line is fully outside the clip, true when at least one pixel fits the clip.

bool LLUI_DISPLAY_clipRectangle(MICROUI_GraphicsContext *gc, jint *x1, jint *y1, jint *x2, jint *y2)

Tells if given rectangle fits the clip or not. If at least one pixel fits the clip, the rectangle size is cropped. The rectangle may be partially cropped even if the rectangle is fully outside the clip. The rectangle is not cropped when the rectangle fully fits the clip.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x1 – [inout] pointer on the top-left pixel X coordinate.

• y1 – [inout] pointer on the top-left pixel Y coordinate.

• x2 – [inout] pointer on the bottom-right pixel X coordinate.

• y2 – [inout] pointer on the bottom-right pixel Y coordinate.

Returns:

false when the rectangle is fully outside the clip, true when at least one pixel fits the clip.

bool LLUI_DISPLAY_clipRegion(MICROUI_GraphicsContext *gc, jint *x, jint *y, jint *width, jint *height, jint *destX, jint *destY)

Tells if given region (from x,y to x+width-1,y+height-1) fits the clip or not. If at least one pixel fits the clip, the region size is cropped and the destination point is increased. The region may be partially cropped even if the region is fully outside the clip. The region is not cropped when the region fully fits the clip.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [inout] pointer on the top-left pixel X coordinate.

• y – [inout] pointer on the top-left pixel Y coordinate.

• width – [inout] pointer on the region width.

• height – [inout] pointer on the region height.

• destX – [inout] pointer on the top-left destination pixel X coordinate.

• destY – [inout] pointer on the top-left destination pixel Y coordinate.

Returns:

false when the region is fully outside the clip, true when at least one pixel fits the clip.

bool LLUI_DISPLAY_regionsOverlap(MICROUI_GraphicsContext *gc, MICROUI_Image *img, jint regionX, jint regionY, jint width, jint height, jint destX, jint destY)

Tells if source and destination share a region.

Source and destination can share a region if and only if source and destination target the same MicroUI Image. In that case, this function checks if there is an intersection of source and destination regions. This function is useful when drawing an image on same image.

Parameters:

• gc – [in] the MicroUI GraphicsContext target of destination.

• img – [in] the MicroUI Image to draw.

• regionX – [in] the x coordinate of the upper-left corner of the region to check.

• regionY – [in] the y coordinate of the upper-left corner of the region to check.

• width – [in] the width of the region to check.

• height – [in] the height of the region to check.

• destX – [in] the x coordinate of the top-left point in the destination.

• destY – [in] the y coordinate of the top-left point in the destination.

Returns:

true when source and destination are same image and when destination region intersects source region.

uint32_t LLUI_DISPLAY_getEllipsisWidth(MICROUI_GraphicsContext *gc)

Tells if the ellipsis is enabled or not. Returns 0 when ellipsis is disabled, a positive value otherwise. This value is the maximum string width in pixels. If string width is higher than this value, an ellipsis will be drawn to crop the string.

Parameters:

• gc – [in] the MicroUI GraphicsContext where reading the ellipsis width.

Returns:

the ellipsis width or 0.

bool LLUI_DISPLAY_requestFlush(void)

Requests a call to LLUI_DISPLAY_IMPL_flush() if something has been drawn in the back buffer (application dirty region is not null). The call of LLUI_DISPLAY_IMPL_flush() is synchronized with the MicroEJ application drawing (see MicroUI event pump).

Returns:

true when request has been added, false when queue is full.

bool LLUI_DISPLAY_requestRender(void)

Requests a call to Displayable.render(). The call of Displayable.render() is synchronized with the MicroEJ application drawing (see MicroUI event pump).

Returns:

true when request has been added, false when queue is full.

uint8_t *LLUI_DISPLAY_getAddress(MICROUI_Image *image)

Returns the memory address of the given MicroUI Image. This image can be located in runtime memory (RAM, SRAM, SDRAM etc.) or in read-only memory (internal flash, NOR etc.).

Parameters:

• image – [in] the MicroUI Image.

Returns:

the MicroUI Image pixels memory address.

uint32_t LLUI_DISPLAY_getSize(MICROUI_Image *image)

Returns the memory full size (in bytes) of the given MicroUI Image. This size includes the image header and the pixels buffer.

Parameters:

• image – [in] the MicroUI Image.

Returns:

the MicroUI Image memory size in bytes.

uint8_t *LLUI_DISPLAY_getBufferAddress(MICROUI_Image *image)

Returns the buffer address of the given MicroUI Image. This buffer can be located in runtime memory (RAM, SRAM, SDRAM etc.) or in read-only memory (internal flash, NOR etc.).

If exists, the returned pointer points on the image custom header (see LLUI_DISPLAY_IMPL_adjustNewImageCharacteristics() for more details).

If not exists, the returned pointer points on first image pixel.

Parameters:

• image – [in] the MicroUI Image.

Returns:

the MicroUI Image pixels buffer address.

bool LLUI_DISPLAY_isMutable(MICROUI_Image *image)

Tells if the MicroUI Image is a mutable image or not. If yes, the image can be casted as a MICROUI_GraphicsContext.

Parameters:

• image – [in] the MicroUI Image.

Returns:

true when the image is mutable.

bool LLUI_DISPLAY_isDisplayFormat(jbyte format)

Tells if format is the display buffer format or not. If yes, all software algorithms listed in ui_drawing_soft.h and dw_drawing_soft.h can be used. If not, these software algorithms must not be used (no check).

See also

MICROUI_ImageFormat

Parameters:

• format – [in] the format to check. The format is one value from the MICROUI_ImageFormat enumeration.

Returns:

true if format refers to the display format

bool LLUI_DISPLAY_isCustomFormat(jbyte format)

Tells if format is a custom format or not.

See also

MICROUI_ImageFormat

Parameters:

• format – [in] the format to check. The format is one value from the MICROUI_ImageFormat enumeration.

Returns:

true if format refers to a custom format

uint32_t LLUI_DISPLAY_getFormatBPP(jbyte format)

Returns the bit per pixel from a MicroUI image format.

Parameters:

• format – [in] The MicroUI format of the image

Returns:

The bit per pixel of the image, or 0 if the image format is unknown or custom.

uint32_t LLUI_DISPLAY_getImageBPP(MICROUI_Image *image)

Returns the bit per pixel from a MicroUI image.

Parameters:

• image – [in] The MicroUI image

Returns:

The bit per pixel of the image, or 0 if the image format is unknown or custom.

uint32_t LLUI_DISPLAY_getStrideInBytes(MICROUI_Image *image)

Returns the MicroUI Image row stride in bytes. This value may be higher than the formula “width * bpp / 8” when some padding bytes are available before and/or after the row.

Parameters:

• image – [in] the MicroUI Image.

Returns:

the MicroUI Image row stride in bytes.

uint32_t LLUI_DISPLAY_getStrideInPixels(MICROUI_Image *image)

Returns the MicroUI Image row stride in pixels. This value may be higher than “image width” when some padding pixels are available before and/or after the row.

Parameters:

• image – [in] the MicroUI Image.

Returns:

the MicroUI Image row stride in pixels.

uint32_t LLUI_DISPLAY_getLUTSize(MICROUI_Image *image)

Returns the MicroUI Image LUT size when the image format is MICROUI_IMAGE_FORMAT_LARGB8888 or MICROUI_IMAGE_FORMAT_LRGB888. This LUT is located at the beginning of the address returned by LLUI_DISPLAY_getBufferAddress(). The indexed pixels are located just after this LUT.

Parameters:

• image – [in] the MicroUI Image.

Returns:

the MicroUI Image LUT size in bytes or 0 when the image format is not MICROUI_IMAGE_FORMAT_LARGB8888 or MICROUI_IMAGE_FORMAT_LRGB888.

bool LLUI_DISPLAY_isTransparent(MICROUI_Image *image)

Tells if the MicroUI Image is not fully opaque. An image may be fully opaque even if its format contains an alpha level. This notion is useful to prevent to use some blending algorithms when the image is fully opaque.

Parameters:

• image – [in] the MicroUI Image.

Returns:

true when the image is not fully opaque.

uint32_t LLUI_DISPLAY_convertARGBColorToDisplayColor(uint32_t color)

Converts the 32-bit ARGB color format (A-R-G-B) into the display color format.

Note: the alpha level may be ignored if the display pixel representation does not hold the alpha level information.

Parameters:

• color – [in] the color to convert.

Returns:

the converted color.

uint32_t LLUI_DISPLAY_convertDisplayColorToARGBColor(uint32_t color)

Converts the display color format into a 32-bit ARGB color format (A-R-G-B).

Note: the alpha level may be ignored if the display pixel representation does not hold the alpha level information. In this case, the returned alpha level is 0xff (full opaque).

Parameters:

• color – [in] the color to convert.

Returns:

the converted color.

uint32_t LLUI_DISPLAY_readPixel(MICROUI_Image *img, int32_t x, int32_t y)

Returns the 32-bit ARGB color format (A-R-G-B) of a pixel of the image.

Parameters:

• img – [in] the MicroUI Image.

• x – [in] the x coordinate of the pixel.

• y – [in] the y coordinate of the pixel.

Returns:

an ARGB8888 color or 0 if the pixel is out-of-bounds.

uint32_t LLUI_DISPLAY_blend(uint32_t foreground, uint32_t background, uint32_t alpha)

Blends two colors applying a global alpha factor.

Parameters:

• foreground – [in] the ARGB8888 foreground color.

• background – [in] the ARGB8888 background color.

• alpha – [in] the global alpha factor.

Returns:

an ARGB8888 color.

bool LLUI_DISPLAY_allocateImageBuffer(MICROUI_Image *img, uint8_t rowAlignmentInBytes)

Allocates a memory area in the images heap.

On success, caller has to use the functions LLUI_DISPLAY_getBufferAddress() and LLUI_DISPLAY_getStride*() to retrieve image buffer characteristics.

The caller has the responsibility to register the image (see SNI_registerResource()).

If this function is called outside the MicroJvm virtual machine task, the LLUI port must handle reentrant mode in the Graphics Engine. The functions LLUI_DISPLAY_IMPL_lockJob() and LLUI_DISPLAY_IMPL_unlockJob() need to be implemented.

Deprecated:

and not used: allocator will call LLUI_DISPLAY_IMPL_getNewImageStrideInBytes() function instead.

Parameters:

• img – [inout] the MicroUI Image.

• rowAlignmentInBytes – [in]

Returns:

false when buffer cannot be allocated (out of memory)

void LLUI_DISPLAY_freeImageBuffer(MICROUI_Image *img)

Frees manually an image buffer. This action is useless when the image has been allocated by a call to LLUI_DISPLAY_IMPL_decodeImage() because the allocated image will be freed by the MicroEJ application thanks a call to Image.close().

The caller has the responsibility to unregister the image (see SNI_unregisterResource()).

If this function is called outside the MicroJvm virtual machine task, the LLUI port must handle reentrant mode in the Graphics Engine. The functions LLUI_DISPLAY_IMPL_lockJob() and LLUI_DISPLAY_IMPL_unlockJob() need to be implemented.

Parameters:

• img – [in] the MicroUI Image.

bool LLUI_DISPLAY_setBackBuffer(uint8_t flushIdentifier, uint8_t *new_back_buffer, bool from_isr)

Callback to call by LLUI_DISPLAY_IMPL.h implementation when the flush (update of the front buffer) is finished. See LLUI_DISPLAY_IMPL_flush() function.

Parameters:

• flushIdentifier – [in] the identifier given by LLUI_DISPLAY_IMPL_flush()

• new_back_buffer – [in] the new back buffer the Graphics Engine has to use.

• from_isr – [in] true when this function is called from an interrupt context.

Returns:

true if the new back buffer will be used for next drawings, false if the current back buffer is already is use or if this call occurs too late.

LLUI_DISPLAY_Status LLUI_DISPLAY_decodeImage(uint8_t *addr, uint32_t length, MICROUI_ImageFormat expectedFormat, MICROUI_Image *image)

Calls the MicroUI image decoding framework to decode an image (PNG, WEBP, etc.). This framework is an abstraction of all available image decoders: the MicroUI internal decoders (such as PNG decoder) or BSP custom decoders (such as WEBP decoder). It produces a binary image (RAW).

Note that the RAW image format may be different from the expected format. Only the format of the MicroUI enum OutputFormat are respected: ARGB8888, ARGB4444, ARGB1555, RGB565, RGB888 and A8; plus the formats ARGB8888_PRE, ARGB4444_PRE and ARGB1555_PRE. The formats A4, A2 and A1 are replaced by the format A8. For all others formats, the default decoder format is used (often ARGB8888).

The image buffer is stored in the MicroUI Image heap. The image must be freed by calling “LLUI_DISPLAY_freeImageBuffer()”.

The caller has the responsibility to register the image (see SNI_registerResource()).

According to the encoded image format (PNG, WEBP, etc.), the implementation function “LLUI_DISPLAY_IMPL_decodeImage()” may be called to use a custom image decoder.

If this function is called outside the MicroJvm virtual machine task, the LLUI port must handle reentrant mode in the Graphics Engine. The functions LLUI_DISPLAY_IMPL_lockJob() and LLUI_DISPLAY_IMPL_unlockJob() need to be implemented.

Parameters:

• addr – [in] the source image address.

• length – [in] the source image size in bytes.

• expectedFormat – [in] the RAW image format

• image – [out] the output RAW image

Returns:

LLUI_DISPLAY_OK when decoding is successful.

bool LLUI_DISPLAY_requestDrawing(MICROUI_GraphicsContext *gc, SNI_callback callback)

Requests the graphics engine to start a drawing. This allows to suspend another Java thread until the drawing is performed. In addition, this call may suspend the current thread until the previous drawing is done. In this case, a second call to the caller will be automatically performed.

This function can only be called from a Java native function context.

When returning true, a call to LLUI_DISPLAY_setDrawingStatus() is mandatory after performing the drawing.

Java native function pattern is:

void _drawing_native_xxx(MICROUI_GraphicsContext* gc, …) { // tell to graphics engine if drawing can be performed if (LLUI_DISPLAY_requestDrawing(gc, (SNI_callback)_drawing_native_xxx)) { // perform the drawings (respecting clip if not disabled) DRAWING_Status status = _drawing_xxx(gc, …);

// notify drawing status LLUI_DISPLAY_setDrawingStatus(status); } // else: refused drawing }

Parameters:

• gc – [in] the MicroUI GraphicsContext

• callback – [in] the Java native function (or another function with same signature than Java native function) to (re)call if the thread must be suspended.

Returns:

true if the drawing can start or false when the drawing does not need to be done for any reason.

void LLUI_DISPLAY_setDrawingStatus(DRAWING_Status status)

Notifies the graphics engine about the drawing status.

This function must be called when the call to LLUI_DISPLAY_requestDrawing() has returned true.

Parameters:

• status – [in] drawing status: drawing is done (synchronous drawing): DRAWING_DONE or drawing has been launched / is running (asynchronous drawing): DRAWING_RUNNING.

void LLUI_DISPLAY_notifyAsynchronousDrawingEnd(bool from_isr)

Callback to call by LLUI_DISPLAY_IMPL implementation when the asynchronous drawing (launched just after the call to LLUI_DISPLAY_requestDrawing()) is finished.

Parameters:

• from_isr – [in] true when this function is called from an interrupt context.

void LLUI_DISPLAY_waitAsynchronousDrawingEnd(void)

This function must be invoked prior to releasing any resource that has been registered with the API SNI_registerResource(). It should be specifically called within the close() function provided as an argument to SNI_registerResource().

Using this function outside the context of memory management for one or more resources is not guaranteed and may lead to undefined behavior.

The virtual machine maintains a record of native resources to prevent memory leaks when either the virtual machine or an application is terminated (refer to SNI_registerResource()). This function ensures that no asynchronous workers (tasks, GPU processes) are currently using the resource, thereby preventing premature resource deallocation before the completion of these asynchronous operations.

uint8_t LLUI_DISPLAY_testAndSetUserFlag(MICROUI_GraphicsContext *gc, uint8_t mask, bool set)

Modifies the state of user flags in the MicroUI GraphicsContext.

This function allows setting or clearing one or more flags (up to 8 bits) in the specified GraphicsContext using a mask of flags.

See also

LLUI_DISPLAY_IMPL_notifyDrawingSoft

Parameters:

• gc – [in] the MicroUI GraphicsContext

• mask – [in] a mask that specifies the flags to modify.

• set – [in] a boolean that determines the action to perform:

  • If ‘true’, the bits specified in the mask will be set.

  • If ‘false’, the bits specified in the mask will be cleared.

Returns:

the previous value of the flags before the operation

Defines

MICROUI_DISPLAY_FORMAT_DISPLAY 0x00

Preprocessor-visible codes for the display (screen) pixel formats.

These #define macros mirror the display-capable subset of the MICROUI_ImageFormat enumeration below — useful to check LLUI_DISPLAY_FORMAT (resolved at VEE Port build) against the expected format at compile time: #if LLUI_DISPLAY_FORMAT != MICROUI_DISPLAY_FORMAT_RGB565. The enumeration derives its display-format members from these macros, so there is a single source of truth. Image-only formats (A8, ARGB8888_PRE, custom, …) are not display formats and keep their literal enum values.

MICROUI_DISPLAY_FORMAT_ARGB8888 0x02

The 32-bit ARGB display format.

MICROUI_DISPLAY_FORMAT_RGB888 0x03

The 24-bit RGB display format.

MICROUI_DISPLAY_FORMAT_RGB565 0x04

The 16-bit RGB display format.

MICROUI_DISPLAY_FORMAT_ARGB1555 0x05

The 16-bit ARGB, 1 bit of alpha display format.

MICROUI_DISPLAY_FORMAT_ARGB4444 0x06

The 16-bit ARGB, 4 bits of alpha display format.

MICROUI_DISPLAY_FORMAT_C4 0x0D

The Color4 display format.

MICROUI_DISPLAY_FORMAT_C2 0x0E

The Color2 display format.

MICROUI_DISPLAY_FORMAT_C1 0x0F

The Color1 display format.

Enums

enum LLUI_DISPLAY_Status

LLUI_DISPLAY error and status codes.

These values are used by several functions. See each function comment to know which are the available codes.

Values:

enumerator LLUI_DISPLAY_OK = 0

Value when everything has been correctly executed.

enumerator LLUI_DISPLAY_OUT_OF_MEMORY = -2

Value when a function cannot be executed due to an out of memory error.

enumerator LLUI_DISPLAY_NOK = -9

Value when an error has occurred or when a function is not able to implement the expected behavior.

enum DRAWING_Status

Drawing functions’ return status.

A function has to return DRAWING_DONE when the drawing has been fully done during the function call (synchronous drawing). When the drawing is performed by an asynchronous third party process (software or hardware), the function has to return DRAWING_RUNNING to notify to the Graphics Engine the drawing is not fully done yet.

Values:

enumerator DRAWING_DONE = 0

Value to return when the drawing has been synchronously performed.

enumerator DRAWING_RUNNING = 1

Value to return when the drawing will be asynchronously performed.

enum DRAWING_Incident

Flags describing incidents occurring during drawings.

Values:

enumerator DRAWING_SUCCESS = 0

Value used when no incident occurred.

enumerator DRAWING_LOG_ERROR = 1 << 31

Flag stating that an error occurred during a drawing.

This flag will cause an exception to be thrown when checking the flags in the application. No exception will be thrown if this flag is not set, although other flags will keep their state and be readable in the application. This flag is to be combined with other flags describing the error.

enumerator DRAWING_LOG_NOT_IMPLEMENTED = 1 << 0

Flag stating that a drawing function is lacking an implementation.

enumerator DRAWING_LOG_FORBIDDEN = 1 << 1

Flag stating that a function was called in a context that does not allow that operation.

enumerator DRAWING_LOG_OUT_OF_MEMORY = 1 << 2

Flag stating that the system ran out of memory while attempting to perform a drawing.

enumerator DRAWING_LOG_CLIP_MODIFIED = 1 << 3

Flag stating that the clip area of a graphics context was modified by LLUI_DISPLAY_setClip or LLUI_DISPLAY_intersectClip.

If this flag is set, the caller is responsible for saving the previous clip area and restore it afterwards.

This flag merely warns the user that the clip values returned by GraphicsContext.getClipX, GraphicsContext.getClipY, GraphicsContext.getClipWidth and GraphicsContext.getClipHeight may not be identical to the clip values used in the low-level side. It is meant to be used as a debugging hint if a drawing seems incorrect.

See also

LLUI_DISPLAY_setClip

See also

LLUI_DISPLAY_intersectClip

enumerator DRAWING_LOG_MISSING_CHARACTER = 1 << 4

Flag stating that an undefined character was drawn.

This happens when drawing a string that contains a character that is not included in the font used.

enumerator DRAWING_LOG_LIBRARY_INCIDENT = 1 << 29

Flag describing incidents occurring in a drawing library.

Refer to the MicroUI implementation in the VEE port for more information about this incident.

enumerator DRAWING_LOG_UNKNOWN_INCIDENT = 1 << 30

Flag describing incidents that do not match other values.

enum MICROUI_ImageFormat

Enumerates all MicroUI Image RAW formats.

The type of the formats used by MicroUI and by the Graphics Engine is encoded on a jbyte (see sni.h). This format can be cast with this enumeration:

• typedef MICROUI_Image: the image format

• all functions that use a jbyte format: LLUI_DISPLAY_IMPL_getDrawerIdentifier(), LLUI_DISPLAY_isDisplayFormat(), etc.

• the format returned by Format.getSNIContext() and OutputFormat.getSNIContext().

Values:

enumerator MICROUI_IMAGE_FORMAT_DISPLAY = MICROUI_DISPLAY_FORMAT_DISPLAY

Defines an image with the same pixel representation and layout as the LCD memory.

enumerator MICROUI_IMAGE_FORMAT_ARGB8888 = MICROUI_DISPLAY_FORMAT_ARGB8888

Defines an image whose pixel format is ARGB8888.

enumerator MICROUI_IMAGE_FORMAT_ARGB1555 = MICROUI_DISPLAY_FORMAT_ARGB1555

Defines an image whose pixel format is ARGB1555.

enumerator MICROUI_IMAGE_FORMAT_ARGB4444 = MICROUI_DISPLAY_FORMAT_ARGB4444

Defines an image whose pixel format is ARGB4444.

enumerator MICROUI_IMAGE_FORMAT_ARGB8888_PRE = 0x18

Defines an image whose pixel format is ARGB8888 pre-multiplied: each color component is multiplied by the opacity.

enumerator MICROUI_IMAGE_FORMAT_ARGB1555_PRE = 0x19

Defines an image whose pixel format is ARGB1555 pre-multiplied: each color component is multiplied by the opacity.

enumerator MICROUI_IMAGE_FORMAT_ARGB4444_PRE = 0x1A

Defines an image whose pixel format is ARGB4444 pre-multiplied: each color component is multiplied by the opacity.

enumerator MICROUI_IMAGE_FORMAT_RGB888 = MICROUI_DISPLAY_FORMAT_RGB888

Defines an image whose pixel format is RGB888.

enumerator MICROUI_IMAGE_FORMAT_RGB565 = MICROUI_DISPLAY_FORMAT_RGB565

Defines an image whose pixel format is RGB565.

enumerator MICROUI_IMAGE_FORMAT_A1 = 0x0C

Defines an image whose pixel format is Alpha1.

enumerator MICROUI_IMAGE_FORMAT_A2 = 0x0B

Defines an image whose pixel format is Alpha2.

enumerator MICROUI_IMAGE_FORMAT_A4 = 0x07

Defines an image whose pixel format is Alpha4.

enumerator MICROUI_IMAGE_FORMAT_A8 = 0x08

Defines an image whose pixel format is Alpha8.

enumerator MICROUI_IMAGE_FORMAT_C1 = MICROUI_DISPLAY_FORMAT_C1

Defines an image whose pixel format is Color1.

enumerator MICROUI_IMAGE_FORMAT_C2 = MICROUI_DISPLAY_FORMAT_C2

Defines an image whose pixel format is Color2.

enumerator MICROUI_IMAGE_FORMAT_C4 = MICROUI_DISPLAY_FORMAT_C4

Defines an image whose pixel format is Color4.

enumerator MICROUI_IMAGE_FORMAT_AC11 = 0x12

Defines an image whose pixel format is Alpha1-Color1.

enumerator MICROUI_IMAGE_FORMAT_AC22 = 0x11

Defines an image whose pixel format is Alpha2-Color2.

enumerator MICROUI_IMAGE_FORMAT_AC44 = 0x10

Defines an image whose pixel format is Alpha4-Color4.

enumerator MICROUI_IMAGE_FORMAT_LARGB8888 = 0x0A

Defines an image whose pixel format is a LUT entry on 8 bits and target an ARGB8888 color.

enumerator MICROUI_IMAGE_FORMAT_UNDEFINED = 0x80

Defines an undefined format. Used by LLUI_DISPLAY_IMPL_decodeImage() to not specify a specific format.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_7 = 0xF8

Defines the custom format 7.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_6 = 0xF9

Defines the custom format 6.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_5 = 0xFA

Defines the custom format 5.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_4 = 0xFB

Defines the custom format 4.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_3 = 0xFC

Defines the custom format 3.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_2 = 0xFD

Defines the custom format 2.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_1 = 0xFE

Defines the custom format 1.

enumerator MICROUI_IMAGE_FORMAT_CUSTOM_0 = 0xFF

Defines the custom format 0 (0xff).

enum MICROUI_FontFormat

Enumerates all MicroUI Font RAW formats.

The type of the formats used by MicroUI and by the Graphics Engine is encoded on a jbyte (see sni.h). This format can be cast with this enumeration (typedef MICROUI_Font: the font format).

Values:

enumerator MICROUI_FONT_FORMAT_CUSTOM_7 = 0xF8

Defines the custom format 7.

enumerator MICROUI_FONT_FORMAT_CUSTOM_6 = 0xF9

Defines the custom format 6.

enumerator MICROUI_FONT_FORMAT_CUSTOM_5 = 0xFA

Defines the custom format 5.

enumerator MICROUI_FONT_FORMAT_CUSTOM_4 = 0xFB

Defines the custom format 4.

enumerator MICROUI_FONT_FORMAT_CUSTOM_3 = 0xFC

Defines the custom format 3.

enumerator MICROUI_FONT_FORMAT_CUSTOM_2 = 0xFD

Defines the custom format 2.

enumerator MICROUI_FONT_FORMAT_CUSTOM_1 = 0xFE

Defines the custom format 1.

enumerator MICROUI_FONT_FORMAT_CUSTOM_0 = 0xFF

Defines the custom format 0 (0xff).

struct MICROUI_Image

#include <LLUI_DISPLAY_types.h>

Public Members

jint reserved0

Graphics Engine reserved field.

jchar width

MicroUI Image width in pixels.

jchar height

MicroUI Image height in pixels.

jchar reserved1

Graphics Engine reserved field.

jbyte format

MicroUI Image pixel representation.

The format is one value from the MICROUI_ImageFormat enumeration.

jbyte reserved2

Graphics Engine reserved field.

struct MICROUI_Font

#include <LLUI_DISPLAY_types.h>

Public Members

jbyte format

MicroUI Font format.

The format is one value from the MICROUI_FontFormat enumeration.

int __pad0__

struct MICROUI_GraphicsContext

#include <LLUI_DISPLAY_types.h>

Public Members

MICROUI_Image image

A graphics context targets a mutable image (size and format).

jint foreground_color

Current graphics context foreground color. This color must be used to render the drawing. The color format is 0xAARRGGBB (where alpha level is always 0xff == fully opaque).

jint reserved0

Graphics Engine reserved field.

ui_rect_t clip

Current clip.

Read-only. Call LLUI_DISPLAY_setClip to modify this value.

jint drawing_log_flags

Log flags from drawing operations.

uint8_t drawer

The drawing engine identifier. Useful to retrieve the engine able to draw in the GraphicsContext buffer. The “0” value indicates the default engine: the same engine used to draw in the display buffer.

See also

LLUI_DISPLAY_IMPL_getDrawerIdentifier()

Defines

CONCAT_STRINGS(p, s) p ## s

Useful macros to concatenate easily some strings and defines.

CONCAT_DEFINES(p, s) CONCAT_STRINGS(p, s)

Concatenates the values of two defines.

Functions

void LLUI_PAINTER_IMPL_writePixel(MICROUI_GraphicsContext *gc, jint x, jint y)

Draws a pixel at given position.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the pixel X coordinate.

• y – [in] the pixel Y coordinate.

void LLUI_PAINTER_IMPL_drawLine(MICROUI_GraphicsContext *gc, jint startX, jint startY, jint endX, jint endY)

Draws a line at between points startX,startY (included) and endX,endY (included). Note: startX may be higher than endX (and/or startX may be higher than endY).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• startX – [in] the first pixel line X coordinate.

• startY – [in] the first pixel line Y coordinate.

• endX – [in] the last pixel line X coordinate.

• endY – [in] the last pixel line Y coordinate.

void LLUI_PAINTER_IMPL_drawHorizontalLine(MICROUI_GraphicsContext *gc, jint x, jint y, jint length)

Draws a horizontal line at between points x,y (included) and x+length-1,y (included).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the first pixel line X coordinate.

• y – [in] the first pixel line Y coordinate.

• length – [in] the line size.

void LLUI_PAINTER_IMPL_drawVerticalLine(MICROUI_GraphicsContext *gc, jint x, jint y, jint length)

Draws a vertical line at between points x,y (included) and x,y+length-1 (included).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the first pixel line X coordinate.

• y – [in] the first pixel line Y coordinate.

• length – [in] the line size.

void LLUI_PAINTER_IMPL_drawRectangle(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height)

Draws an orthogonal rectangle at from top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the rectangle width.

• height – [in] the rectangle height.

void LLUI_PAINTER_IMPL_fillRectangle(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height)

Fills a rectangle at from top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the rectangle width.

• height – [in] the rectangle height.

void LLUI_PAINTER_IMPL_drawRoundedRectangle(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height, jint cornerEllipseWidth, jint cornerEllipseHeight)

Draws a rounded rectangle at from top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the rectangle width.

• height – [in] the rectangle height.

• cornerEllipseWidth – [in] the horizontal diameter of the arc at the corners.

• cornerEllipseHeight – [in] the vertical diameter of the arc at the corners.

void LLUI_PAINTER_IMPL_fillRoundedRectangle(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height, jint cornerEllipseWidth, jint cornerEllipseHeight)

Fills a rounded rectangle at from top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the rectangle width.

• height – [in] the rectangle height.

• cornerEllipseWidth – [in] the horizontal diameter of the arc at the corners.

• cornerEllipseHeight – [in] the vertical diameter of the arc at the corners.

void LLUI_PAINTER_IMPL_drawCircleArc(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle)

Draws a circular arc covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included).

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the square whose origin is at (x,y) (upper-left corner) and whose dimension is given by diameter.

Angles are interpreted such that 0 degrees is at the 3 o’clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If either the given diameter is negative or zero, or if arcAngle is zero, nothing is drawn.

The angles are given relative to the square. For instance an angle of 45 degrees is always defined by the line from the center of the square to the upper right corner of the square.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• diameter – [in] the diameter of the arc to draw.

• startAngle – [in] the beginning angle of the arc to draw

• arcAngle – [in] the angular extent of the arc from startAngle

void LLUI_PAINTER_IMPL_drawEllipseArc(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height, jfloat startAngle, jfloat arcAngle)

Draws an elliptical arc covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the rectangle whose origin is at (x,y) (upper-left corner) and whose dimension is given by width and height.

Angles are interpreted such that 0 degrees is at the 3 o’clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If either the given width or height is negative or zero, or if arcAngle is zero, nothing is drawn.

The angles are given relative to the rectangle. For instance an angle of 45 degrees is always defined by the line from the center of the rectangle to the upper right corner of the rectangle. Thus for a non squared rectangle angles are skewed along either height or width.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the rectangle width.

• height – [in] the rectangle height.

• startAngle – [in] the beginning angle of the arc to draw

• arcAngle – [in] the angular extent of the arc from startAngle

void LLUI_PAINTER_IMPL_fillCircleArc(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle)

Fills a circular arc covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included).

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the square whose origin is at (x,y) (upper-left corner) and whose dimension is given by diameter.

Angles are interpreted such that 0 degrees is at the 3 o’clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If either the given diameter is negative or zero, or if arcAngle is zero, nothing is drawn.

The angles are given relative to the square. For instance an angle of 45 degrees is always defined by the line from the center of the square to the upper right corner of the square.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• diameter – [in] the diameter of the arc to draw.

• startAngle – [in] the beginning angle of the arc to draw

• arcAngle – [in] the angular extent of the arc from startAngle

void LLUI_PAINTER_IMPL_fillEllipseArc(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height, jfloat startAngle, jfloat arcAngle)

Fills an elliptical arc covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the rectangle whose origin is at (x,y) (upper-left corner) and whose dimension is given by width and height.

Angles are interpreted such that 0 degrees is at the 3 o’clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If either the given width or height is negative or zero, or if arcAngle is zero, nothing is drawn.

The angles are given relative to the rectangle. For instance an angle of 45 degrees is always defined by the line from the center of the rectangle to the upper right corner of the rectangle. Thus for a non squared rectangle angles are skewed along either height or width.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the rectangle width.

• height – [in] the rectangle height.

• startAngle – [in] the beginning angle of the arc to draw

• arcAngle – [in] the angular extent of the arc from startAngle

void LLUI_PAINTER_IMPL_drawEllipse(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height)

Draws an ellipse covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included). Ellipses which focal points are not on the same axis are not supported.

If either the given width or height is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the ellipse width.

• height – [in] the ellipse height.

void LLUI_PAINTER_IMPL_fillEllipse(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height)

Fills an ellipse covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

If either the given width or height is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• width – [in] the ellipse width.

• height – [in] the ellipse height.

void LLUI_PAINTER_IMPL_drawCircle(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter)

Draws a circle covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included).

If the given diameter is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• diameter – [in] the diameter of the circle to draw.

void LLUI_PAINTER_IMPL_fillCircle(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter)

Fills a circle covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included).

If the given diameter is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the top-left pixel X coordinate.

• y – [in] the top-left pixel Y coordinate.

• diameter – [in] the circle square size.

void LLUI_PAINTER_IMPL_drawImage(MICROUI_GraphicsContext *gc, MICROUI_Image *img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha)

Draws a region of an image.

The region of the image to draw is given relative to the image (origin at the upper-left corner) as a rectangle.

If the specified source region exceeds the image bounds, the copied region is limited to the image boundary. If the copied region goes out of the bounds of the graphics context area, pixels out of the range will not be drawn.

A global opacity value is given. When this value is 0xff (255, opaque), that means the image is drawn on the graphics context without managing an extra opacity. Only the image transparent pixels must have been merged with destination. All image opaque pixels override destination.

When this value is a value between 0 and 0xff, that means each pixel of the image must be merged with destination in addition with the image transparent pixels. An image opaque pixel becomes transparent (its opacity is the given alpha) and the opacity of an image transparent pixel becomes (alpha * alpha(pixel)) / 255.

When this value is lower than 0 or higher than 255, this value must be clamped.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• img – [in] the MicroUI Image to draw.

• regionX – [in] the x coordinate of the upper-left corner of the region to copy.

• regionY – [in] the y coordinate of the upper-left corner of the region to copy.

• width – [in] the width of the region to copy.

• height – [in] the height of the region to copy.

• x – [in] the x coordinate of the top-left point in the destination.

• y – [in] the y coordinate of the top-left point in the destination.

• alpha – [in] the opacity level to apply to the region.

void LLUI_PAINTER_IMPL_drawString(MICROUI_GraphicsContext *gc, jchar *chars, jint offset, jint length, MICROUI_Font *font, jint x, jint y)

Draws a string.

Parameters:

• gc – [in] the targeted MicroUI GraphicsContext

• chars – [in] a string of characters

• offset – [in] the index of the first character of the string in chars

• length – [in] the number of characters

• font – [in] the MicroUI Font to use

• x – [in] the left coordinate

• y – [in] the top coordinate

jint LLUI_PAINTER_IMPL_stringWidth(jchar *chars, jint offset, jint length, MICROUI_Font *font)

Computes the rendered width of a string.

Parameters:

• chars – [in] a string of characters

• offset – [in] the index of the first character of the string in chars

• length – [in] the number of characters

• font – [in] the MicroUI Font used

Returns:

the width in pixels

jint LLUI_PAINTER_IMPL_initializeRenderableStringSNIContext(jchar *chars, jint offset, jint length, MICROUI_Font *font, MICROUI_RenderableString *renderableString)

Computes the rendered width of a renderable string and fills its SNI context.

Parameters:

• chars – [in] the renderable string of characters

• offset – [in] the index of the first character of the renderable string in chars

• length – [in] the number of characters

• font – [in] the MicroUI Font to use

• renderableString – [inout] the SNI context of the renderable string

Returns:

the renderable string width in pixels

void LLUI_PAINTER_IMPL_drawRenderableString(MICROUI_GraphicsContext *gc, jchar *chars, jint offset, jint length, MICROUI_Font *font, jint width, MICROUI_RenderableString *renderableString, jint x, jint y)

Draws a renderable string.

Parameters:

• gc – [in] the targeted MicroUI GraphicsContext

• chars – [in] the renderable string of characters

• offset – [in] the index of the first character of the renderable string in chars

• length – [in] the number of characters

• font – [in] the MicroUI Font to use

• width – [in] the renderable string width in pixels

• renderableString – [in] the renderable string

• x – [in] the left coordinate

• y – [in] the top coordinate

Enums

enum DRAWING_Cap

Defines the start and end caps to draw when rendering an anti-aliased drawing.

Values:

enumerator DRAWING_ENDOFLINE_NONE = 0

No specific cap is drawn.

enumerator DRAWING_ENDOFLINE_ROUNDED = 1

Cap is represented by a semi circle.

enumerator DRAWING_ENDOFLINE_PERPENDICULAR = 2

Cap is perpendicular to the line.

enum DRAWING_Flip

Defines the transformation to apply when drawing an image with flip.

Values:

enumerator DRAWING_FLIP_NONE = 0

Defines the flip mode “none”: no flip must be performed.

The image

A B C D E F

is drawn:

A B C D E F

enumerator DRAWING_FLIP_90 = 7

Defines the flip mode 90°: image must be rotated to 90° anticlockwise.

The image

A B C D E F

is drawn:

B D F A C E

enumerator DRAWING_FLIP_180 = 4

Defines the flip mode 180°: image must be rotated to 180° anticlockwise.

The image

A B C D E F

is drawn:

F E D C B A

enumerator DRAWING_FLIP_270 = 2

Defines the flip mode 270°: image must be rotated to 270° anticlockwise.

The image

A B C D E F

is drawn:

E C A F D B

enumerator DRAWING_FLIP_MIRROR = 3

Defines the flip mode mirror + “none”: only a vertical mirror must be applied.

The image

A B C D E F

is drawn:

B A D C F E

enumerator DRAWING_FLIP_MIRROR_90 = 1

Defines the flip mode mirror + 90°: a vertical mirror must be applied and then the image must be rotated to 90° anticlockwise.

The image

A B C D E F

is drawn:

A C E B D F and then mirrored

enumerator DRAWING_FLIP_MIRROR_180 = 6

Defines the flip mode mirror + 180°: a vertical mirror must be applied and then the image must be rotated to 180° anticlockwise.

The image

A B C D E F

is drawn:

E F C D A B

enumerator DRAWING_FLIP_MIRROR_270 = 5

Defines the flip mode mirror + 270°: a vertical mirror must be applied and then the image must be rotated to 270° anticlockwise.

The image

A B C D E F

is drawn:

F D B E C A

Functions

void LLDW_PAINTER_IMPL_drawThickFadedPoint(MICROUI_GraphicsContext *gc, jint x, jint y, jint thickness, jint fade)

Draws a thick point with fade at given position.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the point X coordinate.

• y – [in] the point Y coordinate.

• thickness – [in] the point thickness.

• fade – [in] the fade to apply.

void LLDW_PAINTER_IMPL_drawThickFadedLine(MICROUI_GraphicsContext *gc, jint startX, jint startY, jint endX, jint endY, jint thickness, jint fade, DRAWING_Cap startCap, DRAWING_Cap endCap)

Draws a thick line with fade between given points.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• startX – [in] the x coordinate of the start of the line

• startY – [in] the y coordinate of the start of the line

• endX – [in] the x coordinate of the end of the line

• endY – [in] the y coordinate of the end of the line

• thickness – [in] the line thickness.

• fade – [in] the fade to apply.

• startCap – [in] cap representation of start of shape

• endCap – [in] cap representation of end of shape

void LLDW_PAINTER_IMPL_drawThickFadedCircle(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter, jint thickness, jint fade)

Draws a thick circle with fade covering the square specified by its diameter.

If diameter is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the x coordinate of the upper-left corner of the square where the circle is drawn

• y – [in] the y coordinate of the upper-left corner of the square where the circle is drawn

• diameter – [in] the diameter of the circle to draw

• thickness – [in] the circle thickness.

• fade – [in] the fade to apply.

void LLDW_PAINTER_IMPL_drawThickFadedCircleArc(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle, jint thickness, jint fade, DRAWING_Cap start, DRAWING_Cap end)

Draws a thick circle with fade arc covering the specified square.

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the square whose origin is at (x,y) (upper-left corner) and whose dimension is given by diameter.

Angles are interpreted such that 0 degrees is at the 3 o’clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If diameter is negative or zero, nothing is drawn.

The angles are given relative to the square. For instance an angle of 45 degrees is always defined by the line from the center of the square to the upper right corner of the square.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the x coordinate of the upper-left corner of the square where the arc is drawn

• y – [in] the y coordinate of the upper-left corner of the square where the arc is drawn

• diameter – [in] the diameter of the circle to draw

• startAngle – [in] the beginning angle of the arc to draw

• arcAngle – [in] the angular extent of the arc from startAngle

• thickness – [in] the arc thickness.

• fade – [in] the fade to apply.

• start – [in] cap representation of start of shape

• end – [in] cap representation of end of shape

void LLDW_PAINTER_IMPL_drawThickFadedEllipse(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height, jint thickness, jint fade)

Draws a thick ellipse with fade covering the specified rectangle.

The center of the ellipse is defined as the center of the rectangle whose origin is at (x,y) (upper-left corner) and whose dimension is given by width and height.

If either width or height is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the x coordinate of the upper-left corner of the rectangle where the ellipse is drawn

• y – [in] the y coordinate of the upper-left corner of the rectangle where the ellipse is drawn

• width – [in] the width of the ellipse to draw

• height – [in] the height of the ellipse to draw

• thickness – [in] the ellipse thickness.

• fade – [in] the fade to apply.

void LLDW_PAINTER_IMPL_drawThickLine(MICROUI_GraphicsContext *gc, jint startX, jint startY, jint endX, jint endY, jint thickness)

Draws a thick line between given points.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• startX – [in] the x coordinate of the start of the line

• startY – [in] the y coordinate of the start of the line

• endX – [in] the x coordinate of the end of the line

• endY – [in] the y coordinate of the end of the line

• thickness – [in] the line thickness.

void LLDW_PAINTER_IMPL_drawThickCircle(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter, jint thickness)

Draws a thick circle covering the square specified by its diameter.

If diameter is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the x coordinate of the upper-left corner of the square where the circle is drawn

• y – [in] the y coordinate of the upper-left corner of the square where the circle is drawn

• diameter – [in] the diameter of the circle to draw

• thickness – [in] the circle thickness.

void LLDW_PAINTER_IMPL_drawThickEllipse(MICROUI_GraphicsContext *gc, jint x, jint y, jint width, jint height, jint thickness)

Draws a thick ellipse covering the specified rectangle.

The center of the ellipse is defined as the center of the rectangle whose origin is at (x,y) (upper-left corner) and whose dimension is given by width and height.

If either width or height is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the x coordinate of the upper-left corner of the rectangle where the ellipse is drawn

• y – [in] the y coordinate of the upper-left corner of the rectangle where the ellipse is drawn

• width – [in] the width of the ellipse to draw

• height – [in] the height of the ellipse to draw

• thickness – [in] the ellipse thickness.

void LLDW_PAINTER_IMPL_drawThickCircleArc(MICROUI_GraphicsContext *gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle, jint thickness)

Draws a thick arc covering the square specified by its diameter.

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the square whose origin is at (x,y) (upper-left corner) and whose dimension is given by diameter.

Angles are interpreted such that 0 degrees is at the 3 o’clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If diameter is negative or zero, nothing is drawn.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• x – [in] the x coordinate of the upper-left corner of the square where the arc is drawn

• y – [in] the y coordinate of the upper-left corner of the square where the arc is drawn

• diameter – [in] the diameter of the circle to draw

• startAngle – [in] the beginning angle of the arc to draw

• arcAngle – [in] the angular extent of the arc from startAngle

• thickness – [in] the arc thickness.

void LLDW_PAINTER_IMPL_drawFlippedImage(MICROUI_GraphicsContext *gc, MICROUI_Image *img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, DRAWING_Flip transformation, jint alpha)

Draws an image applying a flip (0, 90, 180 or 270 degrees with or without mirror).

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• img – [in] the MicroUI Image to draw.

• regionX – [in] the x coordinate of the upper-left corner of the region to draw.

• regionY – [in] the y coordinate of the upper-left corner of the region to draw.

• width – [in] the width of the region to copy.

• height – [in] the height of the region to copy.

• x – [in] the x coordinate of the top-left point in the destination.

• y – [in] the y coordinate of the top-left point in the destination.

• transformation – [in] the flip to apply.

• alpha – [in] the opacity level to apply to the region.

void LLDW_PAINTER_IMPL_drawRotatedImageNearestNeighbor(MICROUI_GraphicsContext *gc, MICROUI_Image *img, jint x, jint y, jint rotationX, jint rotationY, jfloat angle, jint alpha)

Draws an image applying a free rotation (0 to 360 degrees).

The rotation is specified by the center and the angle. The reference point is the graphical object top-left corner. The rotation point is relative where the graphical object will be drawn.

This method uses the nearest neighbor algorithm to render the content. This algorithm performs faster rendering than the bilinear algorithm but it provides a lower quality.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• img – [in] the MicroUI Image to draw.

• x – [in] the x coordinate of the image reference anchor top-left point.

• y – [in] the y coordinate of the image reference anchor top-left point.

• rotationX – [in] the x coordinate of the rotation center.

• rotationY – [in] the y coordinate of the rotation center.

• angle – [in] the rotation angle.

• alpha – [in] the opacity level to apply to the region.

void LLDW_PAINTER_IMPL_drawRotatedImageBilinear(MICROUI_GraphicsContext *gc, MICROUI_Image *img, jint x, jint y, jint rotationX, jint rotationY, jfloat angle, jint alpha)

Draws an image applying a free rotation (0 to 360 degrees).

The rotation is specified by the center and the angle. The reference point is the graphical object top-left corner. The rotation point is relative where the graphical object will be drawn.

This method uses the bilinear algorithm to render the content. This algorithm performs better rendering than nearest neighbor algorithm but it is slower to apply.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• img – [in] the MicroUI Image to draw.

• x – [in] the x coordinate of the image reference anchor top-left point.

• y – [in] the y coordinate of the image reference anchor top-left point.

• rotationX – [in] the x coordinate of the rotation center.

• rotationY – [in] the y coordinate of the rotation center.

• angle – [in] the rotation angle.

• alpha – [in] the opacity level to apply to the region.

void LLDW_PAINTER_IMPL_drawScaledImageNearestNeighbor(MICROUI_GraphicsContext *gc, MICROUI_Image *img, jint x, jint y, jfloat factorX, jfloat factorY, jint alpha)

Draws an image applying a scaling.

This method uses the nearest neighbor algorithm to render the content. This algorithm performs faster rendering than the bilinear algorithm but it provides a lower quality.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• img – [in] the MicroUI Image to draw.

• x – [in] the x coordinate of the image reference anchor top-left point.

• y – [in] the y coordinate of the image reference anchor top-left point.

• factorX – [in] scaling X factor.

• factorY – [in] scaling Y factor.

• alpha – [in] the opacity level to apply to the region.

void LLDW_PAINTER_IMPL_drawScaledImageBilinear(MICROUI_GraphicsContext *gc, MICROUI_Image *img, jint x, jint y, jfloat factorX, jfloat factorY, jint alpha)

Draws an image applying a scaling.

This method uses the bilinear algorithm to render the content. This algorithm performs better rendering than nearest neighbor algorithm but it is slower to apply.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• img – [in] the MicroUI Image to draw.

• x – [in] the x coordinate of the image reference anchor top-left point.

• y – [in] the y coordinate of the image reference anchor top-left point.

• factorX – [in] scaling X factor.

• factorY – [in] scaling Y factor.

• alpha – [in] the opacity level to apply to the region.

void LLDW_PAINTER_IMPL_drawScaledStringBilinear(MICROUI_GraphicsContext *gc, jchar *chars, jint length, MICROUI_Font *font, jint x, jint y, jfloat xRatio, jfloat yRatio)

Draws a string applying a scaling.

This method uses the bilinear algorithm to render the characters. This algorithm performs better rendering than nearest neighbor algorithm but it is slower to apply.

Parameters:

• gc – [in] the targeted MicroUI GraphicsContext

• chars – [in] a string of characters

• length – [in] the number of characters

• font – [in] the MicroUI Font to use

• x – [in] the left coordinate

• y – [in] the top coordinate

• xRatio – [in] the horizontal scaling ratio (1.0f meaning no scaling)

• yRatio – [in] the vertical scaling ratio (1.0f meaning no scaling)

void LLDW_PAINTER_IMPL_drawScaledRenderableStringBilinear(MICROUI_GraphicsContext *gc, jchar *chars, jint length, MICROUI_Font *font, jint width, MICROUI_RenderableString *renderableString, jint x, jint y, jfloat xRatio, jfloat yRatio)

Draws a renderable string applying a scaling.

This method uses the bilinear algorithm to render the characters. This algorithm performs better rendering than nearest neighbor algorithm but it is slower to apply.

Parameters:

• gc – [in] the targeted MicroUI GraphicsContext

• chars – [in] a string of characters

• length – [in] the number of characters

• font – [in] the MicroUI Font to use

• width – [in] the renderable string width in pixels

• renderableString – [in] the renderable string

• x – [in] the left coordinate

• y – [in] the top coordinate

• xRatio – [in] the horizontal scaling ratio (1.0f meaning no scaling)

• yRatio – [in] the vertical scaling ratio (1.0f meaning no scaling)

void LLDW_PAINTER_IMPL_drawCharWithRotationBilinear(MICROUI_GraphicsContext *gc, jchar c, MICROUI_Font *font, jint x, jint y, jint xRotation, jint yRotation, jfloat angle, jint alpha)

Draws a character applying a rotation and an alpha value.

This method uses the bilinear algorithm to render the character. This algorithm performs better rendering than nearest neighbor algorithm but it is slower to apply.

Parameters:

• gc – [in] the targeted MicroUI GraphicsContext

• c – [in] a character

• font – [in] the MicroUI font to use

• x – [in] the left coordinate

• y – [in] the top coordinate

• xRotation – [in] the horizontal coordinate of the rotation center

• yRotation – [in] the vertical coordinate of the rotation center

• angle – [in] the rotation angle, in degrees

• alpha – [in] the alpha value to use

void LLDW_PAINTER_IMPL_drawCharWithRotationNearestNeighbor(MICROUI_GraphicsContext *gc, jchar c, MICROUI_Font *font, jint x, jint y, jint xRotation, jint yRotation, jfloat angle, jint alpha)

Draws a character applying a rotation and an alpha value.

This method uses the nearest neighbor algorithm to render the character. This algorithm performs faster rendering than the bilinear algorithm but it provides a lower quality.

Parameters:

• gc – [in] the targeted MicroUI GraphicsContext

• c – [in] a character

• font – [in] the MicroUI font to use

• x – [in] the left coordinate

• y – [in] the top coordinate

• xRotation – [in] the horizontal coordinate of the rotation center

• yRotation – [in] the vertical coordinate of the rotation center

• angle – [in] the rotation angle, in degrees

• alpha – [in] the alpha value to use

LLUI_LED: LEDs

Principle

The LEDs engine provides Low Level APIs for connecting LED drivers. The file LLUI_LED_impl.h, which comes with the LEDs engine, defines the API headers to be implemented.

Initialization

The first function called is LLUI_LED_IMPL_initialize, which allows the driver to initialize all LED devices. This method must return the available number of LEDs. Each LED has a unique identifier. The first LED has the ID 0, and the last has the ID NbLEDs – 1.

This UI extension provides support to efficiently implement the set of methods that interact with the LEDs provided by a device. Below are the relevant C functions:

• LLUI_LED_IMPL_getIntensity: Get the intensity of a specific LED using its ID.

• LLUI_LED_IMPL_setIntensity: Set the intensity of an LED using its ID.

Header Files

The version macros of LLUI_LED_impl.h are described with the display header files.

LLUI_LED_MIN_INTENSITY (0)

Intensity value to turn off a LED.

LLUI_LED_MAX_INTENSITY (255)

Maximum intensity that a LED can handle. If a LED does not handle intensity, any valid intensity different from LLUI_LED_MIN_INTENSITY turns the LED on.

Functions

jint LLUI_LED_IMPL_initialize(void)

Initializes the LEDs.

Returns:

the number of LEDs in the group. First LED will have the identifier 0 and last one the identifier nbLeds - 1.

jint LLUI_LED_IMPL_getIntensity(jint ledID)

Get the intensity of the LED. The implementation should be able to return the state of an LED. If it is not able to do so (for example GPIO is not accessible in read mode), the BSP has to save the LED state in a global variable.

Parameters:

• ledID – [in] the LED identifier.

Returns:

the intensity of the LED.

void LLUI_LED_IMPL_setIntensity(jint ledID, jint intensity)

Set the intensity of the LED.

A 0 intensity turns off the LED, intensity of 255 turns on the LED to max power.

Parameters:

• ledID – [in] the LED identifier.

• intensity – [in] the intensity of the LED.

LLVG: VectorGraphics

Principle

The VG Pack provides a Low Level API for initializing the Vector Graphics engine. The file LLVG_impl.h, which comes with the VG Pack, defines the API headers to be implemented.

Initialization

The function LLVG_IMPL_initialize is the first native function called by the MicroVG implementation. It allows to initialize all C components: GPU initialization, Font engine, heap management, etc.

Header Files

The VG Pack replaces the tokens @LLVG_MAJOR_VERSION@, @LLVG_MINOR_VERSION@ and @LLVG_PATCH_VERSION@ with its own version.

Defines

LLVG_MAJOR_VERSION @LLVG_MAJOR_VERSION@

Low-Level API VG major version.

LLVG_MINOR_VERSION @LLVG_MINOR_VERSION@

Low-Level API VG minor version.

LLVG_PATCH_VERSION @LLVG_PATCH_VERSION@

Low-Level API VG patch version.

LLVG_SUCCESS 0

Value returned on success.

LLVG_DATA_INVALID_PATH -1

Value returned on invalid path.

LLVG_DATA_INVALID -2

Value returned on invalid data.

LLVG_RESOURCE_CLOSED -6

Value returned when resource is closed.

LLVG_OUT_OF_MEMORY -9

Value returned when an out of memory error occurs.

LLVG_FILLTYPE_WINDING 0

Non-zero winding fill rule.

LLVG_FILLTYPE_EVEN_ODD 1

Even-odd fill rule.

LLVG_BLEND_SRC 0

Source blending mode.

LLVG_BLEND_SRC_OVER 1

Source over blending mode.

LLVG_BLEND_DST_OVER 2

Destination over blending mode.

LLVG_BLEND_SRC_IN 3

Source in blending mode.

LLVG_BLEND_DST_IN 4

Destination in blending mode.

LLVG_BLEND_DST_OUT 5

Destination out blending mode.

LLVG_BLEND_PLUS 6

Plus blending mode.

LLVG_BLEND_SCREEN 7

Screen blending mode.

LLVG_BLEND_MULTIPLY 8

Multiply blending mode.

struct MICROVG_Image

#include <LLVG_impl.h>

Public Members

void *data

Pointer on the image’s data.

uint32_t size

Size of the image’s data.

float width

Image width.

float height

Image height.

uint32_t duration

Animation duration (0 if no animation).

uint8_t flags

Image internal flags.

Functions

void LLVG_IMPL_initialize(jint LLVG_TRACE_group)

Initializes the implementation. This is the first native called by the library.

Parameters:

• LLVG_TRACE_group – [in] The identifier of the MicroVG traces group

Defines

BVI_FORMAT MICROUI_IMAGE_FORMAT_CUSTOM_7

Specifies the BufferedVectorImage format.

IS_BVI(image) (BVI_FORMAT == (MICROUI_ImageFormat)((image)->format))

Tells if the image is a BufferedVectorImage.

MAP_BVI_ON_IMAGE(image) (void *)LLUI_DISPLAY_getBufferAddress((image))

Maps a BufferedVectorImage on a MicroUI Image.

MAP_BVI_ON_GC(gc) (void *)MAP_BVI_ON_IMAGE(&((gc)->image))

Maps a BufferedVectorImage on a MicroUI GraphicsContext.

Functions

void LLVG_BVI_IMPL_map_context(MICROUI_Image *ui, MICROVG_Image *vg)

Maps the MicroVG BufferedVectorImage on the MicroUI Image.

Parameters:

• ui – [in] the MicroUI Image.

• vg – [out] the MicroVG Image.

void LLVG_BVI_IMPL_clear(MICROUI_GraphicsContext *gc)

Clears the content of the BufferedVectorImage.

Parameters:

• gc – [in] the Graphics Context that holds the BufferedVectorImage.

Functions

jint LLVG_PAINTER_IMPL_drawPath(MICROUI_GraphicsContext *gc, jbyte *path, jint x, jint y, jfloat *matrix, jint fillRule, jint blend, jint color)

Draws a path filled with the specified color (not the one of the Graphics Context).

Parameters:

• gc – [in] the destination

• path – [in] the path’s data

• x – [in] the destination X coordinate

• y – [in] the destination Y coordinate

• matrix – [in] the deformation to apply

• fillRule – [in] the fill type

• blend – [in] the blend mode

• color – [in] the color to apply (with an opacity)

Returns:

LLVG_SUCCESS on success

jint LLVG_PAINTER_IMPL_drawGradient(MICROUI_GraphicsContext *gc, jbyte *path, jint x, jint y, jfloat *matrix, jint fillRule, jint alpha, jint blend, jint *gradient, jfloat *gradientMatrix)

Draws a path filled with a linear gradient.

Parameters:

• gc – [in] the destination

• path – [in] the path’s data

• x – [in] the destination X coordinate

• y – [in] the destination Y coordinate

• matrix – [in] the deformation to apply

• fillRule – [in] the fill type

• alpha – [in] the global opacity to apply

• blend – [in] the blend mode

• gradient – [in] the gradient to apply

• gradientMatrix – [in] the gradient deformation, may be null (means identity)

Returns:

LLVG_SUCCESS on success

jint LLVG_PAINTER_IMPL_drawString(MICROUI_GraphicsContext *gc, jchar *text, jint faceHandle, jfloat size, jfloat x, jfloat y, jfloat *matrix, jint alpha, jint blend, jfloat letterSpacing)

Draws a string with the color of the Graphics Context.

The top/left position of the first drawn character is placed at coordinate x/y.

The x coordinate anchors the leftmost pixel the text draws, whichever character carries it, which is the left edge of the box LLVG_FONT_IMPL_string_width() measures.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• text – [in] the array of characters to draw.

• faceHandle – [in] the font reference handle.

• size – [in] the height of the font in pixels.

• x – [in] the horizontal coordinate of the top/left of the first drawn character.

• y – [in] the vertical coordinate of the top/left of the first drawn character.

• matrix – [in] deformation matrix, may be null (means identity)

• alpha – [in] the opacity level to apply to the character.

• blend – [in] the blend mode to use

• letterSpacing – [in] the extra letter spacing to use

Returns:

LLVG_SUCCESS on success

jint LLVG_PAINTER_IMPL_drawStringGradient(MICROUI_GraphicsContext *gc, jchar *text, jint faceHandle, jfloat size, jfloat x, jfloat y, jfloat *matrix, jint alpha, jint blend, jfloat letterSpacing, jint *gradientData, jfloat *gradientMatrix)

Draws a string with a linear gradient.

The x coordinate anchors the leftmost pixel the text draws, whichever character carries it, which is the left edge of the box LLVG_FONT_IMPL_string_width() measures.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• text – [in] the array of characters to draw.

• faceHandle – [in] the font reference handle.

• size – [in] the height of the font in pixels.

• x – [in] the horizontal coordinate of the top/left of the first drawn character.

• y – [in] the vertical coordinate of the top/left of the first drawn character.

• matrix – [in] deformation matrix, may be null (means identity)

• alpha – [in] the opacity level to apply to the character.

• blend – [in] the blend mode to use

• letterSpacing – [in] the extra letter spacing to use

• gradientData – [in] the gradient to apply

• gradientMatrix – [in] the gradient deformation, may be null (means identity)

Returns:

LLVG_SUCCESS on success

jint LLVG_PAINTER_IMPL_drawStringOnCircle(MICROUI_GraphicsContext *gc, jchar *text, jint faceHandle, jfloat size, jint x, jint y, jfloat *matrix, jint alpha, jint blend, jfloat letterSpacing, jfloat radius, jint direction)

Draws a string along a circle, with the color of the Graphics Context.

The x coordinate anchors the leftmost pixel the text draws, whichever character carries it, which is the left edge of the box LLVG_FONT_IMPL_string_width() measures.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• text – [in] the array of characters to draw.

• faceHandle – [in] the font reference handle.

• size – [in] the height of the font in pixels.

• x – [in] the horizontal coordinate of the top/left of the first drawn character.

• y – [in] the vertical coordinate of the top/left of the first drawn character.

• matrix – [in] deformation matrix, may be null (means identity)

• alpha – [in] the opacity level to apply to the character.

• blend – [in] the blend mode to use

• letterSpacing – [in] the extra letter spacing to use

• radius – [in] the radius of the circle

• direction – [in] the direction of the text along the circle

Returns:

LLVG_SUCCESS on success

jint LLVG_PAINTER_IMPL_drawStringOnCircleGradient(MICROUI_GraphicsContext *gc, jchar *text, jint faceHandle, jfloat size, jint x, jint y, jfloat *matrix, jint alpha, jint blend, jfloat letterSpacing, jfloat radius, jint direction, jint *gradientData, jfloat *gradientMatrix)

Draws a string along a circle, with a linear gradient.

The x coordinate anchors the leftmost pixel the text draws, whichever character carries it, which is the left edge of the box LLVG_FONT_IMPL_string_width() measures.

Parameters:

• gc – [in] the MicroUI GraphicsContext target.

• text – [in] the array of characters to draw.

• faceHandle – [in] the font reference handle.

• size – [in] the height of the font in pixels.

• x – [in] the horizontal coordinate of the top/left of the first drawn character.

• y – [in] the vertical coordinate of the top/left of the first drawn character.

• matrix – [in] deformation matrix, may be null (means identity)

• alpha – [in] the opacity level to apply to the character.

• blend – [in] the blend mode to use

• letterSpacing – [in] the extra letter spacing to use

• radius – [in] the radius of the circle

• direction – [in] the direction of the text along the circle

• gradientData – [in] the gradient to apply

• gradientMatrix – [in] the gradient deformation, may be null (means identity)

Returns:

LLVG_SUCCESS on success

jint LLVG_PAINTER_IMPL_drawImage(MICROUI_GraphicsContext *gc, MICROVG_Image *image, jint x, jint y, jfloat *matrix, jint alpha, jlong elapsed, const float color_matrix[])

Draws an image with transformation and opacity. Optionally apply an animation and / or a color filtering.

Parameters:

• gc – [in] the graphics context to draw on

• image – [in] the image to draw

• x – [in] the destination X coordinate

• y – [in] the destination Y coordinate

• matrix – [in] the transformation matrix to apply

• alpha – [in] the global opacity rendering value

• elapsed – [in] the elapsed time since the beginning of the animation, in milliseconds

• color_matrix – [in] the color matrix used to transform colors, may be null (means no color deformation)

Returns:

LLVG_SUCCESS on success

LLVG_MATRIX: Matrix

Principle

The Matrix module provides Low Level APIs for manipulating matrices. The file LLVG_MATRIX_impl.h, which comes with the Matrix module, defines the API headers to be implemented.

Implementation

The matrix functions are divided in four groups:

1. identity and copy: fill an identity matrix or copy a matrix to another one.

2. setXXX: erase the content of the matrix by an operation (translate, rotation, scaling, concatenate).

3. xxx (no prefix): perform an operation with the matrix as first argument: M' = M * xxx(x, y) where xxx is the operation (translate, rotation, scaling, concatenate).

4. postXXX: perform an operation with the matrix as second argument: M' = xxx(x, y) * M where xxx is the operation (translate, rotation, scaling, concatenate).

Header Files

One C header file is provided:

Defines

LLVG_MATRIX_SIZE 9

Number of float values of a MicroVG matrix.

Functions

void LLVG_MATRIX_IMPL_identity(jfloat *matrix)

Creates an identity matrix.

Parameters:

• matrix – [out] the matrix to initialize

void LLVG_MATRIX_IMPL_copy(jfloat *dest, const jfloat *src)

Deep copies the given matrix into destination.

Parameters:

• dest – [out] the matrix to copy to

• src – [in] the matrix to copy from

void LLVG_MATRIX_IMPL_multiply(jfloat *dest, const jfloat *a, const jfloat *b)

Sets the matrix to the concatenation of the two specified matrices.

Contrary to LLVG_MATRIX_IMPL_setConcat(), dest must not be a or b.

Parameters:

• dest – [out] the destination

• a – [in] the first matrix

• b – [in] the second matrix

void LLVG_MATRIX_IMPL_setTranslate(jfloat *matrix, jfloat dx, jfloat dy)

Sets the matrix to translate by (dx, dy).

Parameters:

• matrix – [out] the matrix to translate

• dx – [in] the translation on x

• dy – [in] the translation on y

void LLVG_MATRIX_IMPL_setScale(jfloat *matrix, jfloat sx, jfloat sy)

Sets the matrix to scale by (sx, sy).

Parameters:

• matrix – [out] the matrix to scale

• sx – [in] the scale on x

• sy – [in] the scale on y

void LLVG_MATRIX_IMPL_setRotate(jfloat *matrix, jfloat degrees)

Sets the matrix to rotate about (0,0) by the specified number of degrees.

Parameters:

• matrix – [out] the matrix to rotate

• degrees – [in] the degrees to rotate

void LLVG_MATRIX_IMPL_setConcat(jfloat *dest, const jfloat *a, const jfloat *b)

Sets the matrix to the concatenation of the two specified matrices.

Either of the two matrices may also be the target matrix, that is matrixA.setConcat(matrixA, matrixB); is valid.

Parameters:

• dest – [out] the destination

• a – [in] the first matrix

• b – [in] the second matrix

void LLVG_MATRIX_IMPL_translate(jfloat *matrix, jfloat x, jfloat y)

Preconcats the matrix with the specified translation. M’ = M * T(dx, dy)

Parameters:

• matrix – [inout] the matrix to translate

• x – [in] the translation on x

• y – [in] the translation on y

void LLVG_MATRIX_IMPL_scale(jfloat *matrix, jfloat scaleX, jfloat scaleY)

Preconcats the matrix with the specified scale. M’ = M * S(sx, sy)

Parameters:

• matrix – [inout] the matrix to scale

• scaleX – [in] the scale on x

• scaleY – [in] the scale on y

void LLVG_MATRIX_IMPL_rotate(jfloat *matrix, jfloat degrees)

Preconcats the matrix with the specified rotation. M’ = M * R(degrees)

Parameters:

• matrix – [inout] the matrix to rotate

• degrees – [in] the degrees to rotate

void LLVG_MATRIX_IMPL_concatenate(jfloat *matrix, const jfloat *other)

Preconcats the matrix with the specified matrix. M’ = M * other.

Parameters:

• matrix – [inout] the matrix to concat

• other – [in] the matrix to concat with

void LLVG_MATRIX_IMPL_postTranslate(jfloat *matrix, jfloat dx, jfloat dy)

Postconcats the matrix with the specified translation. M’ = T(dx, dy) * M.

Parameters:

• matrix – [inout] the matrix to translate

• dx – [in] the translation on x

• dy – [in] the translation on y

void LLVG_MATRIX_IMPL_postScale(jfloat *matrix, jfloat sx, jfloat sy)

Postconcats the matrix with the specified scale. M’ = S(sx, sy) * M.

Parameters:

• matrix – [inout] the matrix to scale

• sx – [in] the scale on x

• sy – [in] the scale on y

void LLVG_MATRIX_IMPL_postRotate(jfloat *matrix, jfloat degrees)

Postconcats the matrix with the specified rotation. M’ = R(degrees) * M.

Parameters:

• matrix – [inout] the matrix to rotate

• degrees – [in] the degrees to rotate

void LLVG_MATRIX_IMPL_postConcat(jfloat *matrix, const jfloat *other)

Postconcats the matrix with the specified matrix. M’ = other * M.

Parameters:

• matrix – [inout] the matrix to concat

• other – [in] the matrix to concat with

void LLVG_MATRIX_IMPL_transformPoint(jfloat *x, jfloat *y, const jfloat *matrix)

Transforms a point by the specified matrix.

Parameters:

• x – [inout] the X-point to transform

• y – [inout] the Y-point to transform

• matrix – [in] the transformation to apply

LLVG_PATH: Vector Path

Principle

The Path module provides Low Level APIs for creating paths in target specific format. The file LLVG_PATH_impl.h, which comes with the Path module, defines the API headers to be implemented. The file LLVG_PAINTER_impl.h defines the API headers to be implemented to draw the paths (with a color or a gradient).

Creation

The header file LLVG_PATH_impl.h allows to convert a MicroVG library format path in a buffer that represents the same vectorial path in the target specific format (generally GPU format).

The first function called is LLVG_PATH_IMPL_initializePath, which allows the implementation to initialize the path buffer. The buffer is allocated in the Managed Heap and its size is fixed by the MicroVG implementation. When the buffer is too small for the target specific format, the implementation has to return the expected buffer size instead of the keyword LLVG_SUCCESS.

The next steps consist in appending some commands in the path buffer. The command encoding depends on the target specific format. When the buffer is too small to add the new command, the implementation has to return a value that indicates the number of bytes the array must be enlarged with.

List of commands:

• LLVG_PATH_CMD_CLOSE: MicroVG “CLOSE” command.

• LLVG_PATH_CMD_MOVE: MicroVG “MOVE ABS” command.

• LLVG_PATH_CMD_MOVE_REL: MicroVG “MOVE REL” command.

• LLVG_PATH_CMD_LINE: MicroVG “LINE ABS” command.

• LLVG_PATH_CMD_LINE_REL: MicroVG “LINE REL” command.

• LLVG_PATH_CMD_QUAD: MicroVG “QUAD ABS” command.

• LLVG_PATH_CMD_QUAD_REL: MicroVG “QUAD REL” command.

• LLVG_PATH_CMD_CUBIC: MicroVG “CUBIC ABS” command.

• LLVG_PATH_CMD_CUBIC_REL: MicroVG “CUBIC REL” command.

List of operations:

• LLVG_PATH_IMPL_appendPathCommand1: Adds a command with 1 point parameter in the array.

• LLVG_PATH_IMPL_appendPathCommand2: Adds a command with 2 points parameter in the array.

• LLVG_PATH_IMPL_appendPathCommand3: Adds a command with 3 points parameter in the array.

A path is automatically closed by the MicroVG implementation (by adding the command LLVG_PATH_CMD_CLOSE). A path can be reopened (function LLVG_PATH_IMPL_reopenPath), that consists in removing the last added command (LLVG_PATH_CMD_CLOSE command) from the buffer.

Drawing

The header file LLVG_PAINTER_impl.h provides the functions called by the Application via VectorGraphicsPainter to draw a path.

• A path can be drawn with a 32-bit color (ARGB8888): LLVG_PAINTER_IMPL_drawPath.

• A path can be drawn with a linear gradient: LLVG_PAINTER_IMPL_drawGradient.

The drawing destination is symbolized by a MicroUI GraphicsContext: a pointer to a MICROUI_GraphicsContext instance. Like MicroUI Painter natives, the implementation has to synchronize the drawings with the MicroUI Graphics Engine.

Header Files

One C header file is provided:

Defines

LLVG_PATH_CMD_CLOSE 0

VectorGraphics library “CLOSE” command.

LLVG_PATH_CMD_MOVE 1

VectorGraphics library “MOVE ABS” command.

LLVG_PATH_CMD_MOVE_REL 2

VectorGraphics library “MOVE REL” command.

LLVG_PATH_CMD_LINE 3

VectorGraphics library “LINE ABS” command.

LLVG_PATH_CMD_LINE_REL 4

VectorGraphics library “LINE REL” command.

LLVG_PATH_CMD_QUAD 5

VectorGraphics library “QUAD ABS” command.

LLVG_PATH_CMD_QUAD_REL 6

VectorGraphics library “QUAD REL” command.

LLVG_PATH_CMD_CUBIC 7

VectorGraphics library “CUBIC ABS” command.

LLVG_PATH_CMD_CUBIC_REL 8

VectorGraphics library “CUBIC REL” command.

Functions

jint LLVG_PATH_IMPL_initializePath(jbyte *path, jint length)

Initializes the path array.

If the implementation requires a bigger array, it must return the number of required bytes.

Parameters:

• path – [out] the array to initialize

• length – [in] the array size

Returns:

LLVG_SUCCESS on success or a value that indicates the minimal required size of the array.

jint LLVG_PATH_IMPL_appendPathCommand1(jbyte *path, jint length, jint cmd, jfloat x, jfloat y)

Adds a command with 1 point parameter in the array.

If the data (command and its parameters) cannot be added (out of memory), the implementation must return the number of bytes required to add the data. The caller has to increase the array and call again the native method.

Parameters:

• path – [inout] the array to update with the command and parameters.

• length – [in] the array length.

• cmd – [in] the command to add in the array.

• x – [in] the command data 1.

• y – [in] the command data 2.

Returns:

LLVG_SUCCESS on success or a value that indicates the number of bytes the array must be enlarged.

jint LLVG_PATH_IMPL_appendPathCommand2(jbyte *path, jint length, jint cmd, jfloat x1, jfloat y1, jfloat x2, jfloat y2)

Adds a command with 2 points parameter in the array.

If the data (command and its parameters) cannot be added (out of memory), the implementation must return the number of bytes required to add the data. The caller has to increase the array and call again the native method.

Parameters:

• path – [inout] the array to update with the command and parameters.

• length – [in] the array length.

• cmd – [in] the command to add in the array.

• x1 – [in] the command data 1.

• y1 – [in] the command data 2.

• x2 – [in] the command data 3.

• y2 – [in] the command data 4.

Returns:

LLVG_SUCCESS on success or a value that indicates the number of bytes the array must be enlarged.

jint LLVG_PATH_IMPL_appendPathCommand3(jbyte *path, jint length, jint cmd, jfloat x1, jfloat y1, jfloat x2, jfloat y2, jfloat x3, jfloat y3)

Adds a command with 3 points parameter in the array.

If the data (command and its parameters) cannot be added (out of memory), the implementation must return the number of bytes required to add the data. The caller has to increase the array and call again the native method.

Parameters:

• path – [inout] the array to update with the command and parameters.

• length – [in] the array length.

• cmd – [in] the command to add in the array.

• x1 – [in] the command data 1.

• y1 – [in] the command data 2.

• x2 – [in] the command data 3.

• y2 – [in] the command data 4.

• x3 – [in] the command data 5.

• y3 – [in] the command data 6.

Returns:

LLVG_SUCCESS on success or a value that indicates the number of bytes the array must be enlarged.

void LLVG_PATH_IMPL_reopenPath(jbyte *path)

Opens again the closed path (the last path command is CMD_CLOSED for sure).

The implementation resets the data offset at the end of the previous command.

Parameters:

• path – [inout] the array to update.

LLVG_GRADIENT: Vector Linear Gradient

Principle

The Gradient module provides Low Level APIs for creating linear gradients in target specific format. The file LLVG_GRADIENT_impl.h, which comes with the Gradient module, defines the API headers to be implemented.

Implementation

Only one function has to be implemented: LLVG_GRADIENT_IMPL_initializeGradient. It consists in encoding the MicroVG LinearGradient in a buffer that represents the linear gradient in target specific format (generally GPU format).

This function allows the implementation to initialize the gradient buffer. The buffer is allocated in the Managed Heap and its size is fixed by the MicroVG implementation. When the buffer is too small for the target specific format, the implementation has to return the expected buffer size instead of the keyword LLVG_SUCCESS.

Header Files

One C header file is provided:

Functions

jint LLVG_GRADIENT_IMPL_initializeGradient(jint *gradient, jint length, const jint *colors, jint count, const jfloat *positions, jfloat xStart, jfloat yStart, jfloat xEnd, jfloat yEnd)

Initializes the gradient array.

If the implementation requires a bigger array, it must return the number of required bytes.

The position array may be null; in that case, a linear distribution is set.

Parameters:

• gradient – [out] the array to initialize

• length – [in] the array size

• colors – [in] the colors to store

• count – [in] the available number of colors

• positions – [in] the colors positions or null to set default positions.

• xStart – [in] the x-coordinate for the start of the gradient vector

• yStart – [in] the y-coordinate for the start of the gradient vector

• xEnd – [in] the x-coordinate for the end of the gradient vector

• yEnd – [in] the y-coordinate for the end of the gradient vector

Returns:

LLVG_SUCCESS on success or a value that indicates the minimal required size of the array.

LLVG_FONT: Vector Font

Principle

The Font module provides Low Level APIs for decoding fonts (LLVG_FONT_impl.h) and rendering texts (LLVG_PAINTER_impl.h). Both header files, which come with the Font module, define the API headers to be implemented.

Initialization

The first function called is LLVG_FONT_IMPL_load_font, which allows the driver to open a font file from its name. This function takes a parameter to configure the text rendering engine:

• Simple layout: uses the glyph advance metrics and the font kerning table.

• Complex layout: uses the font GPOS and GSUB tables.

See VectorFont for more information.

The implementation must manage its own heap to keep the font opened. The font’s data are disposed by a call to LLVG_FONT_IMPL_dispose.

Font Characteristics

The other functions in LLVG_FONT_impl.h consist in retrieving some font characteristics according a text and a font size: string width, string height, baseline, etc.

See VectorFont for more information.

Drawing

The header file LLVG_PAINTER_impl.h provides the functions called by the Application via VectorGraphicsPainter to draw a path.

• A string can be drawn with a 32-bit color (ARGB8888): LLVG_PAINTER_IMPL_drawString.

• A string can be drawn with a linear gradient: LLVG_PAINTER_IMPL_drawStringGradient.

• A string can be draw on a circle: LLVG_PAINTER_IMPL_drawStringOnCircle and LLVG_FONT_PAINTER_IMPL_drawStringOnCircleGradient.

The drawing destination is symbolized by a MicroUI GraphicsContext: a pointer to a MICROUI_GraphicsContext instance. Like MicroUI Painter natives, the implementation has to synchronize the drawings with the MicroUI Graphics Engine.

Header Files

One C header file is provided:

Defines

LLVG_FONT_UNLOADED 0

Font handle value for unloaded font.

LLVG_FONT_DEFAULT_LETTER_SPACING 0

Defines the letter spacing to use to let the vector font engine use the internal vector font’s letter spacing.

LAYOUT_SIMPLE_MODE 0

Simple layout mode, for latin scripts where only Kerning feature is needed.

LAYOUT_COMPLEX_MODE 1

Complex layout mode, for arabic, thai and other complex scripts where glyphs substitutions and positioning features are needed.

UI_FONT_FORMAT_VG MICROUI_FONT_FORMAT_CUSTOM_7

Specifies the MicroUI font format over MicroVG.

Functions

jint LLVG_FONT_IMPL_load_font(jchar *font_name, jboolean complex_layout)

Loads a font from a path.

Parameters:

• font_name – [in] the path of the font

• complex_layout – [in] enable the complex layouter for that font.

Returns:

the reference handle of the font or 0 if the font could not be loaded.

jfloat LLVG_FONT_IMPL_string_width(jchar *text, jint faceHandle, jfloat size, jfloat letterSpacing)

Measures the width of a text for the specified font and size.

The width is the union of the ink of every glyph, each placed at its own pen position: the leftmost pixel any glyph draws to the rightmost, whichever glyphs those are. A glyph that draws nothing contributes nothing, at either end.

A font size that is not strictly positive returns 0.

Parameters:

• text – [in] the character string to measure

• faceHandle – [in] the font reference handle

• size – [in] the font size, in pixels

• letterSpacing – [in] the extra letter spacing to use

Returns:

the width of the specified string, in pixels. The returned value is a finite value, positive or zero; the error codes are the negative values.

jfloat LLVG_FONT_IMPL_string_height(jchar *text, jint faceHandle, jfloat size)

Measures the height of a text for the specified font and size.

The text is measured from upper pixel of the upper glyph to the lower pixel of the lower glyph.

A font size that is not strictly positive returns 0.

Parameters:

• text – [in] the character string to measure

• faceHandle – [in] the font reference handle

• size – [in] the font size, in pixels

Returns:

the height of the specified string, in pixels. The returned value is a finite value, positive or zero; the error codes are the negative values.

jfloat LLVG_FONT_IMPL_get_baseline_position(jint faceHandle, jfloat size)

Gets the baseline position for a font at the given font size.

A font size that is not strictly positive returns 0.

Parameters:

• faceHandle – [in] the font reference handle.

• size – [in] the font size, in pixels.

Returns:

the distance from the top to the baseline position, in pixels. The returned value is a finite value, positive or zero; the error codes are the negative values.

jfloat LLVG_FONT_IMPL_get_height(jint faceHandle, jfloat size)

Gets the height for a font at the given font size.

The height of a font is the distance between the max ascent line and the max descent line.

A font size that is not strictly positive returns 0.

Parameters:

• faceHandle – [in] the font reference handle.

• size – [in] the height of the font in pixels.

Returns:

the distance from the top of the font to the bottom, in pixels. The returned value is a finite value, positive or zero; the error codes are the negative values.

void LLVG_FONT_IMPL_dispose(jint faceHandle)

Disposes the resources associated to the font.

Parameters:

• faceHandle – [in] the font reference handle.

bool LLVG_FONT_IMPL_has_complex_layouter(void)

Determines if a complex layouter is available.

Returns:

true if a complex layouter is available otherwise false.

LLNET: Network

Header Files

Several header files are provided:

• LLNET_CHANNEL_impl.h

  Defines a set of functions that the BSP must implement to initialize the Net native component. It also defines some configuration operations to setup a network connection.

• LLNET_SOCKETCHANNEL_impl.h

  Defines a set of functions that the BSP must implement to create, connect and retrieve information on a network connection.

• LLNET_STREAMSOCKETCHANNEL_impl.h

  Defines a set of functions that the BSP must implement to do some I/O operations on connection oriented socket (TCP). It also defines function to put a server connection in accepting mode (waiting for a new client connection).

• LLNET_DATAGRAMSOCKETCHANNEL_impl.h

  Defines a set of functions that the BSP must implement to do some I/O operations on connectionless oriented socket (UDP).

• LLNET_DNS_impl.h

  Defines a set of functions that the BSP must implement to request host IP address associated to a host name or to request Domain Name Service (DNS) host IP addresses setup in the underlying system.

• LLNET_NETWORKADDRESS_impl.h

  Defines a set of functions that the BSP must implement to convert string IP address or retrieve specific IP addresses (lookup, localhost or loopback IP address).

• LLNET_NETWORKINTERFACE_impl.h

  Defines a set of functions that the BSP must implement to retrieve information on a network interface (MAC address, interface link status, etc.).

LLNET_SSL: SSL

Header Files

Three header files are provided:

• LLNET_SSL_CONTEXT_impl.h

  Defines a set of functions that the BSP must implement to create a SSL Context and to load CA (Certificate Authority) certificates as trusted certificates.

• LLNET_SSL_SOCKET_impl.h

  Defines a set of functions that the BSP must implement to initialize the SSL native components, to create an underlying SSL Socket and to initiate a SSL session handshake. It also defines some I/O operations such as LLNET_SSL_SOCKET_IMPL_write or LLNET_SSL_SOCKET_IMPL_read used for encrypted data exchange between the client and the server.

• LLNET_SSL_X509_CERT_impl.h

  Defines a function named LLNET_SSL_X509_CERT_IMPL_parse for certificate parsing. This function checks if a given certificate is an X.509 digital certificate and returns its encoded format type : Distinguished Encoding Rules (DER) or Privacy-Enchanced Mail (PEM).

LLECOM_NETWORK: Network Interfaces

Header Files

One header file is provided:

• LLECOM_NETWORK_impl.h

  Defines the set of functions that the BSP must implement to manage and configure and TCP/IP network interfaces.

LLECOM_WIFI: Wi-Fi Management

Header Files

One header file is provided:

• LLECOM_WIFI_impl.h

  Defines the set of functions that the BSP must implement to manage and configure Wi-FI access points.

LLBLUETOOTH: Bluetooth

The following API corresponds to the Bluetooth library version 3.1.0.

Header Files

Two header files are provided:

• LLBLUETOOTH_defines.h

  Defines constants and types which are used by the functions to implement.

Defines

ATTRIBUTE_TYPE_CHARACTERISTIC (0)

Attribute type: the attribute is a characteristic.

ATTRIBUTE_TYPE_DESCRIPTOR (1)

Attribute type: the attribute is a descriptor.

ATTRIBUTE_PERMISSION_NONE (0x00)

Attribute permission: no read or write permission.

ATTRIBUTE_PERMISSION_READ (0x01)

Attribute permission: read permission.

ATTRIBUTE_PERMISSION_READ_ENCRYPT (0x02)

Attribute permission: read permission requiring an encrypted link.

ATTRIBUTE_PERMISSION_READ_AUTH (0x04)

Attribute permission: read permission requiring an authenticated link.

ATTRIBUTE_PERMISSION_WRITE (0x08)

Attribute permission: write permission.

ATTRIBUTE_PERMISSION_WRITE_ENCRYPT (0x10)

Attribute permission: write permission requiring an encrypted link.

ATTRIBUTE_PERMISSION_WRITE_AUTH (0x20)

Attribute permission: write permission requiring an authenticated link.

ADDRESS_TYPE_PUBLIC (0)

Address type: public device address.

ADDRESS_TYPE_PRIVATE (1)

Address type: private device address.

SCAN_FILTER_ACTION_NONE (0)

Scan filter action: do not filter the scan results.

SCAN_FILTER_ACTION_FIELD_EXISTS (1)

Scan filter action: keep only the scan results whose advertisement data contains a field of the filter type.

SCAN_FILTER_ACTION_FIELD_EQUALS (2)

Scan filter action: keep only the scan results whose advertisement data contains a field of the filter type and whose field value is equal to the filter data.

SCAN_FILTER_ACTION_FIELD_STARTS_WITH (3)

Scan filter action: keep only the scan results whose advertisement data contains a field of the filter type and whose field value starts with the filter data.

EVENT_GAP_SCAN_RESULT (1)

Event type: a scan result has been received (see LLBLUETOOTH_event_gap_scan_result_t).

EVENT_GAP_SCAN_COMPLETED (2)

Event type: the scan has completed (see LLBLUETOOTH_event_gap_scan_completed_t).

EVENT_GAP_ADVERTISEMENT_COMPLETED (3)

Event type: the advertisement has completed (see LLBLUETOOTH_event_gap_advertisement_completed_t).

EVENT_GAP_CONNECT_FAILED (4)

Event type: the connection with a device has failed (see LLBLUETOOTH_event_gap_connect_failed_t).

EVENT_GAP_CONNECTED (5)

Event type: a device has been connected (see LLBLUETOOTH_event_gap_connected_t).

EVENT_GAP_DISCONNECTED (6)

Event type: a device has been disconnected (see LLBLUETOOTH_event_gap_disconnected_t).

EVENT_GAP_PAIR_REQUEST (7)

Event type: a pair request has been received (see LLBLUETOOTH_event_gap_pair_request_t).

EVENT_GAP_PAIR_COMPLETED (8)

Event type: the pairing procedure has completed (see LLBLUETOOTH_event_gap_pair_completed_t).

EVENT_GAP_PASSKEY_REQUEST (9)

Event type: a passkey request has been received (see LLBLUETOOTH_event_gap_passkey_request_t).

EVENT_GAP_PASSKEY_GENERATED (10)

Event type: a passkey has been generated (see LLBLUETOOTH_event_gap_passkey_generated_t).

EVENT_GATTC_DISCOVERY_RESULT (11)

Event type: a service discovery result has been received (see LLBLUETOOTH_event_gattc_discovery_result_t).

EVENT_GATTC_DISCOVERY_COMPLETED (12)

Event type: the service discovery has completed (see LLBLUETOOTH_event_gattc_discovery_completed_t).

EVENT_GATTC_READ_COMPLETED (13)

Event type: a read request has completed (see LLBLUETOOTH_event_gattc_read_completed_t).

EVENT_GATTC_WRITE_COMPLETED (14)

Event type: a write request has completed (see LLBLUETOOTH_event_gattc_write_completed_t).

EVENT_GATTC_NOTIFICATION_RECEIVED (15)

Event type: a notification or indication has been received (see LLBLUETOOTH_event_gattc_notification_received_t).

EVENT_GATTS_READ_REQUEST (16)

Event type: a read request has been received (see LLBLUETOOTH_event_gatts_read_request_t).

EVENT_GATTS_WRITE_REQUEST (17)

Event type: a write request has been received (see LLBLUETOOTH_event_gatts_write_request_t).

EVENT_GATTS_NOTIFICATION_SENT (18)

Event type: a notification or indication has been sent (see LLBLUETOOTH_event_gatts_notification_sent_t).

EVENT_GATTS_EXECUTE_WRITE_REQUEST (19)

Event type: an execute write request has been received (see LLBLUETOOTH_event_gatts_execute_write_request_t).

ADV_TYPE_ADV_IND (0)

Advertising type: scannable and connectable advertising.

ADV_TYPE_ADV_DIRECT_IND (1)

Advertising type: directed and connectable advertising.

ADV_TYPE_ADV_NONCONN_IND (2)

Advertising type: non-scannable and non-connectable advertising.

ADV_TYPE_ADV_SCAN_IND (3)

Advertising type: scannable and non-connectable advertising.

struct LLBLUETOOTH_address_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t type

Type of address: one of the ADDRESS_TYPE_* values.

uint8_t addr[6]

Address bytes, in big-endian.

struct LLBLUETOOTH_uuid_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t uuid[16]

UUID bytes, in big-endian.

struct LLBLUETOOTH_gatts_attribute_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t type

Type of attribute: one of the ATTRIBUTE_TYPE_* values.

uint8_t _padding

Padding (unused).

LLBLUETOOTH_uuid_t uuid

UUID of the attribute.

uint8_t permissions

Permissions of the attribute: combination of the ATTRIBUTE_PERMISSION_* values.

uint8_t properties

Properties of the characteristic.

struct LLBLUETOOTH_gatts_attribute_t characteristic

Characteristic information (if the type is ATTRIBUTE_TYPE_CHARACTERISTIC).

struct LLBLUETOOTH_gatts_attribute_t descriptor

Descriptor information (if the type is ATTRIBUTE_TYPE_DESCRIPTOR).

struct LLBLUETOOTH_gatts_service_t

#include <LLBLUETOOTH_defines.h>

Public Members

LLBLUETOOTH_uuid_t uuid

UUID of the service.

uint8_t num_characteristics

Number of characteristics in the service.

uint8_t num_descriptors

Number of descriptors in the service. The attributes of the service (LLBLUETOOTH_gatts_attribute_t) follow this structure in memory.

struct LLBLUETOOTH_gattc_attribute_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t type

Type of attribute: one of the ATTRIBUTE_TYPE_* values.

uint8_t _padding

Padding (unused).

LLBLUETOOTH_uuid_t uuid

UUID of the attribute.

uint16_t value_handle

Handle of the characteristic value.

uint8_t properties

Properties of the characteristic.

struct LLBLUETOOTH_gattc_attribute_t characteristic

Characteristic information (if the type is ATTRIBUTE_TYPE_CHARACTERISTIC).

uint16_t handle

Handle of the descriptor.

struct LLBLUETOOTH_gattc_attribute_t descriptor

Descriptor information (if the type is ATTRIBUTE_TYPE_DESCRIPTOR).

struct LLBLUETOOTH_event_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: one of the EVENT_* values.

struct LLBLUETOOTH_event_gap_scan_result_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_SCAN_RESULT.

LLBLUETOOTH_address_t addr

Address of the device which sent the advertisement.

int8_t rssi

RSSI of the received advertisement.

int8_t adv_type

Advertising type: one of the ADV_TYPE_* values.

uint8_t adv_data_size

Size of the advertisement data, in bytes. The advertisement data follows this structure in memory.

struct LLBLUETOOTH_event_gap_scan_completed_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_SCAN_COMPLETED.

struct LLBLUETOOTH_event_gap_advertisement_completed_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_ADVERTISEMENT_COMPLETED.

struct LLBLUETOOTH_event_gap_connect_failed_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_CONNECT_FAILED.

LLBLUETOOTH_address_t addr

Address of the device which could not be connected.

struct LLBLUETOOTH_event_gap_connected_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_CONNECTED.

LLBLUETOOTH_address_t addr

Address of the connected device.

uint16_t conn_handle

Connection handle of the device.

struct LLBLUETOOTH_event_gap_disconnected_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_DISCONNECTED.

uint8_t _padding

Padding (unused).

uint16_t conn_handle

Connection handle of the device.

struct LLBLUETOOTH_event_gap_pair_request_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_PAIR_REQUEST.

uint8_t _padding

Padding (unused).

uint16_t conn_handle

Connection handle of the device.

struct LLBLUETOOTH_event_gap_pair_completed_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_PAIR_COMPLETED.

uint8_t success

True if the pairing procedure completed successfully, false otherwise.

uint16_t conn_handle

Connection handle of the device.

struct LLBLUETOOTH_event_gap_passkey_request_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_PASSKEY_REQUEST.

uint8_t _padding

Padding (unused).

uint16_t conn_handle

Connection handle of the device.

struct LLBLUETOOTH_event_gap_passkey_generated_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GAP_PASSKEY_GENERATED.

uint8_t _padding

Padding (unused).

uint16_t conn_handle

Connection handle of the device.

uint32_t passkey

Passkey value (6-digit PIN code).

struct LLBLUETOOTH_event_gattc_discovery_result_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTC_DISCOVERY_RESULT.

uint8_t num_attributes

Number of attributes in the discovered service. The attributes of the service (LLBLUETOOTH_gattc_attribute_t) follow this structure in memory.

uint16_t conn_handle

Connection handle of the device.

uint16_t service_handle

Handle of the discovered service.

LLBLUETOOTH_uuid_t service_uuid

UUID of the discovered service.

struct LLBLUETOOTH_event_gattc_discovery_completed_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTC_DISCOVERY_COMPLETED.

uint8_t _padding

Padding (unused).

uint16_t conn_handle

Connection handle of the device.

struct LLBLUETOOTH_event_gattc_read_completed_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTC_READ_COMPLETED.

uint8_t status

Status of the read operation.

uint16_t conn_handle

Connection handle of the device.

uint16_t attr_handle

Handle of the attribute which was read.

uint16_t value_size

Size of the value which was read, in bytes. The value follows this structure in memory.

struct LLBLUETOOTH_event_gattc_write_completed_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTC_WRITE_COMPLETED.

uint8_t status

Status of the write operation.

uint16_t conn_handle

Connection handle of the device.

uint16_t attr_handle

Handle of the attribute which was written.

struct LLBLUETOOTH_event_gattc_notification_received_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTC_NOTIFICATION_RECEIVED.

uint8_t _padding

Padding (unused).

uint16_t conn_handle

Connection handle of the device.

uint16_t attr_handle

Handle of the attribute on which the notification was received.

uint16_t value_size

Size of the received value, in bytes. The value follows this structure in memory.

struct LLBLUETOOTH_event_gatts_read_request_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTS_READ_REQUEST.

uint8_t _padding

Padding (unused).

uint16_t conn_handle

Connection handle of the device.

uint16_t attr_handle

Handle of the attribute to read.

uint16_t offset

Offset of the read request.

struct LLBLUETOOTH_event_gatts_write_request_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTS_WRITE_REQUEST.

uint8_t prepare

True if the write request is a prepare write request, false otherwise.

uint16_t conn_handle

Connection handle of the device.

uint16_t attr_handle

Handle of the attribute to write.

uint16_t offset

Offset of the write request.

uint16_t value_size

Size of the value to write, in bytes. The value follows this structure in memory.

struct LLBLUETOOTH_event_gatts_execute_write_request_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTS_EXECUTE_WRITE_REQUEST.

uint8_t execute

True if the pending prepared writes should be executed, false if they should be cancelled.

uint16_t conn_handle

Connection handle of the device.

uint16_t attr_handle

Handle of the attribute on which the execute write request was received.

struct LLBLUETOOTH_event_gatts_notification_sent_t

#include <LLBLUETOOTH_defines.h>

Public Members

uint8_t event_type

Type of event: EVENT_GATTS_NOTIFICATION_SENT.

uint8_t success

True if the notification was sent successfully, false otherwise.

uint16_t conn_handle

Connection handle of the device.

uint16_t attr_handle

Handle of the attribute on which the notification was sent.

• LLBLUETOOTH_impl.h

  Defines the set of functions that the BSP must implement to manage and configure the Bluetooth module.

Functions

uint8_t LLBLUETOOTH_IMPL_enable(void)

Enables Bluetooth.

If Bluetooth is already enabled, this function returns true without performing any operation.

Returns:

true if Bluetooth was enabled successfully, false otherwise.

void LLBLUETOOTH_IMPL_disable(void)

Disables Bluetooth.

This function frees up all resources allocated during Bluetooth operations and resumes the event thread. If Bluetooth is not enabled, this function returns without performing any operation. After this function has been called, the enable function may be called again.

uint32_t LLBLUETOOTH_IMPL_waitEvent(LLBLUETOOTH_event_t *event, uint32_t max_event_size)

Waits for a Bluetooth event.

If an event is available, this function writes the event data in the structure and returns the number of bytes written. If no event is available, this function returns zero immediately and suspends the calling Java thread until an event is available.

Parameters:

• event – the event structure to fill.

• max_event_size – the maximum size of the event, in bytes.

Returns:

the number of bytes written if an event is available, zero if no event is available.

uint8_t LLBLUETOOTH_IMPL_startScanning(uint8_t filter_action, uint8_t filter_type, const uint8_t *filter_data, uint32_t filter_data_size)

Starts scanning. If a connection is initiated while scanning, the scan is stopped. It may be started again once the connection is established.

Parameters:

• filter_action – the filter action.

• filter_type – the filter type.

• filter_data – the filter data.

• filter_data_size – the size of the filter data.

Returns:

true if scanning was started successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_stopScanning(void)

Stops scanning.

Returns:

true if scanning was stopped successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_startAdvertising(const uint8_t *adv_data, uint32_t adv_data_size)

Starts advertising. If a device connects while advertising, the advertisement is stopped. It may be started again once the connection is established.

Parameters:

• adv_data – the advertisement data.

• adv_data_size – the size of the advertisement data.

Returns:

true if advertising was started successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_stopAdvertising(void)

Stops advertising.

Returns:

true if advertising was stopped successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_connect(const LLBLUETOOTH_address_t *addr)

Initiates connection with a device.

Parameters:

• addr – the device address.

Returns:

true if connection was initiated successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_disconnect(uint16_t conn_handle)

Initiates disconnection with a device.

Parameters:

• conn_handle – the connection handle of the device.

Returns:

true if disconnection was initiated successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_sendPairRequest(uint16_t conn_handle)

Sends a pair request to a device.

Parameters:

• conn_handle – the connection handle of the device.

Returns:

true if the pair request was sent successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_sendPairResponse(uint16_t conn_handle, uint8_t accept)

Replies to the pair request of a device.

Parameters:

• conn_handle – the connection handle of the device.

• accept – true if the pairing request should be accepted, false otherwise.

Returns:

true if the reply was sent successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_sendPasskeyResponse(uint16_t conn_handle, uint8_t accept, uint32_t passkey)

Replies to the passkey request of a device.

Parameters:

• conn_handle – the connection handle of the device.

• accept – true if the pairing request should be accepted, false otherwise.

• passkey – the passkey value (6-digits PIN code).

Returns:

true if the reply was sent successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_discoverServices(uint16_t conn_handle, const LLBLUETOOTH_uuid_t *uuid)

Discovers the services which are provided by this device.

Parameters:

• conn_handle – the connection handle of the device.

• uuid – the UUID of the service to discover, or NULL to discover all services.

Returns:

true if services discovery was initiated successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_addService(const LLBLUETOOTH_gatts_service_t *service, uint16_t *handles)

Adds a service to the GATT server.

The handles buffer is filled with the handle of the service, the value handle of each characteristic and the handle of each descriptor.

Parameters:

• service – the service.

• handles – the handles buffer.

Returns:

true if the service was added successfully, false otherwise.

uint8_t LLBLUETOOTH_IMPL_sendReadRequest(uint16_t conn_handle, uint16_t attr_handle)

Sends a read request on one of the attributes provided by a device.

Parameters:

• conn_handle – the connection handle of the device.

• attr_handle – the attribute handle.

Returns:

true if the read request was sent successfully.

uint8_t LLBLUETOOTH_IMPL_sendWriteRequest(uint16_t conn_handle, uint16_t attr_handle, const uint8_t *value, uint32_t value_size, uint8_t no_response)

Sends a write request on one of the attributes provided by a device.

Parameters:

• conn_handle – the connection handle of the device.

• attr_handle – the attribute handle.

• value – the value to write.

• value_size – the size of the value.

• no_response – true to use the write without response procedure, false to use the write procedure.

Returns:

true if the write request was sent successfully.

uint8_t LLBLUETOOTH_IMPL_sendReadResponse(uint16_t conn_handle, uint16_t attr_handle, uint8_t status, const uint8_t *value, uint32_t value_size)

Sends the response to a read request sent by the given device on an attribute.

Parameters:

• conn_handle – the connection handle of the device.

• attr_handle – the attribute handle.

• status – the status to send back.

• value – the value to send back.

• value_size – the size of the value.

Returns:

true if the read response was sent successfully.

uint8_t LLBLUETOOTH_IMPL_sendWriteResponse(uint16_t conn_handle, uint16_t attr_handle, uint8_t status)

Sends the response to a write request sent by the given device on an attribute.

Parameters:

• conn_handle – the connection handle of the device.

• attr_handle – the attribute handle.

• status – the status to send back.

Returns:

true if the write response was sent successfully.

uint8_t LLBLUETOOTH_IMPL_sendPrepareWriteResponse(uint16_t conn_handle, uint16_t attr_handle, uint8_t status, const uint8_t *value, uint32_t value_size, uint32_t offset)

Sends the response to a prepare write request sent by the given device on an attribute.

Parameters:

• conn_handle – the connection handle of the device.

• attr_handle – the attribute handle.

• status – the status to send back.

• value – the value of the prepare write request.

• value_size – the size of the value of the prepare write request.

• offset – the offset of the prepare write request.

Returns:

true if the write response was sent successfully.

uint8_t LLBLUETOOTH_IMPL_sendExecuteWriteResponse(uint16_t conn_handle, uint16_t attr_handle, uint8_t status)

Sends the response to an execute write request sent by the given device on an attribute.

Parameters:

• conn_handle – the connection handle of the device.

• attr_handle – the attribute handle.

• status – the status to send back.

Returns:

true if the write response was sent successfully.

uint8_t LLBLUETOOTH_IMPL_sendNotification(uint16_t conn_handle, uint16_t attr_handle, const uint8_t *value, uint32_t value_size, uint8_t confirm)

Sends a notification or indication on a characteristic to the given device.

Parameters:

• conn_handle – the connection handle of the device.

• attr_handle – the attribute handle.

• value – the value to send.

• value_size – the size of the value.

• confirm – true to request a confirmation (GATT indication), false otherwise (GATT notification).

Returns:

true if the notification was sent successfully.

LLAUDIO: Audio

Header Files

Three header files is provided:

• LLAUDIO_defines.h

  Defines constants and types which are used by the functions to implement.

• LLAUDIO_RECORD_impl.h

  Defines the set of functions that the BSP must implement for audio recording.

• LLAUDIO_TRACK_impl.h

  Defines the set of functions that the BSP must implement for audio playback.

LLML: MicroAI

Header Files

One header file is provided:

• LLML_impl.h

  Defines the set of functions that the BSP must implement to load a model file, set the input data and read output data. This API also implements a number of helper functions to get the model characteristics such as tensor sizes, quantization parameters, etc…

Enums

enum LLML_Tensor_Type

LLML tensor types.

These values are used to get the tensor type of the input and output tensor of the model.

Values:

enumerator LLML_TENSOR_TYPE_UNKNOWN = 0

enumerator LLML_TENSOR_TYPE_INT8 = 1

enumerator LLML_TENSOR_TYPE_UINT8 = 2

enumerator LLML_TENSOR_TYPE_FLOAT32 = 3

enumerator LLML_TENSOR_TYPE_INT32 = 4

enumerator LLML_TENSOR_TYPE_UINT32 = 5

Functions

jlong LLML_IMPL_init_model_from_resource(jbyte *modelPath, jint inferenceMemoryPoolSize)

Initializes the model : Map the model into a usable data structure, build an interpreter to run the model with and allocate memory for the model’s tensors.

Parameters:

• modelPath – [in] the model path.

• inferenceMemoryPoolSize – [in] Memory allocated to load the tensors and perform inferences.

Returns:

model interpreter handle.

jlong LLML_IMPL_init_model_from_buffer(jlong modelBufferHandle, jint modelByteSize, jint inferenceMemoryPoolSize)

Initializes the model : Map the model into a usable data structure, build an interpreter to run the model with and allocate memory for the model’s tensors.

Parameters:

• modelBufferHandle – [in] the model native buffer handle.

• modelByteSize – [in] the model size in bytes.

• inferenceMemoryPoolSize – [in] Memory allocated to load the tensors and perform inferences.

Returns:

model interpreter handle.

jlong LLML_IMPL_allocate_model(jint modelByteSize)

Allocates native space to store the model data on the native side.

Parameters:

• modelByteSize – [in] the model size in bytes.

Returns:

model native buffer handle.

void LLML_IMPL_free_model(jlong modelBufferHandle)

Frees native space allocated to store the model data.

Parameters:

• modelBufferHandle – [in] the model native buffer handle.

void LLML_IMPL_load_model_chunk(jbyte *data, jlong modelBufferHandle, jint index, jint length)

Loads length bytes of the model data on the native side at the specified index.

Parameters:

• data – [in] the data to be loaded.

• modelBufferHandle – [in] the model native buffer handle.

• index – [in] the index where data must be loaded.

• length – [in] the number of bytes to be loaded.

void LLML_IMPL_clean(jlong modelHandle)

Deletes the model and free the allocated native resources.

Parameters:

• modelHandle – [in] the model interpreter handle.

jint LLML_IMPL_reset(jlong modelHandle)

Resets the state of the model interpreter.

Parameters:

• modelHandle – [in] the model interpreter handle.

Returns:

the execution status : 0 if the execution succeeds, 1 otherwise.

jint LLML_IMPL_run(jlong modelHandle)

Runs an inference on the model.

Parameters:

• modelHandle – [in] the model interpreter handle.

Returns:

the execution status : 0 if the execution succeeds, 1 otherwise.

jint LLML_IMPL_get_input_tensor_count(jlong modelHandle)

Gets the number of input tensors.

Parameters:

• modelHandle – [in] the model interpreter handle.

Returns:

number of input tensors.

jint LLML_IMPL_get_output_tensor_count(jlong modelHandle)

Gets the number of output tensors.

Parameters:

• modelHandle – [in] the model interpreter handle.

Returns:

number of output tensors.

jint LLML_IMPL_get_input_num_dimensions(jlong modelHandle, jint index)

Gets the number of dimensions of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

number of dimensions of the input tensor.

void LLML_IMPL_get_input_shape(jlong modelHandle, jint index, jint *sizes)

Gets the shape of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

• sizes – [out] sizes of the dimensions of the input tensor.

jint LLML_IMPL_get_input_data_type(jlong modelHandle, jint index)

Gets the data type of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

- 0 : unknown type

• 1 : int8

• 2 : uint8

• 3 : float32

• 4 : int32

• 5 : uint32

jint LLML_IMPL_get_input_num_elements(jlong modelHandle, jint index)

Gets the number of elements of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

number of elements of the input tensor.

jint LLML_IMPL_get_input_num_bytes(jlong modelHandle, jint index)

Gets the number of bytes the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

number of bytes of the input tensor.

jint LLML_IMPL_get_input_zero_point(jlong modelHandle, jint index)

Gets the zero point of data of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

the zero point.

jfloat LLML_IMPL_get_input_scale(jlong modelHandle, jint index)

Gets the scale of data of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

the scale.

jboolean LLML_IMPL_input_quantized(jlong modelHandle, jint index)

Get the status of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

true if the index is valid and the input tensor is quantized, false otherwise.

jint LLML_IMPL_get_output_num_dimensions(jlong modelHandle, jint index)

Gets the number of dimensions of the output tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

number of dimensions of the output tensor.

void LLML_IMPL_get_output_shape(jlong modelHandle, jint index, jint *sizes)

Gets the shape of the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

• sizes – [out] sizes of the dimensions of the output tensor.

jint LLML_IMPL_get_output_data_type(jlong modelHandle, jint index)

Gets the data type of the output tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

- 0 : unknown type

• 1 : int8

• 2 : uint8

• 3 : float32

• 4 : int32

• 5 : uint32

jint LLML_IMPL_get_output_num_elements(jlong modelHandle, jint index)

Gets the number of elements of the output tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

number of elements of the output tensor.

jint LLML_IMPL_get_output_num_bytes(jlong modelHandle, jint index)

Gets the number of bytes the output tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

number of bytes of the output tensor.

jint LLML_IMPL_get_output_zero_point(jlong modelHandle, jint index)

Gets the zero point of data of the output tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

the zero point.

jfloat LLML_IMPL_get_output_scale(jlong modelHandle, jint index)

Gets the scale of data of the output tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

the scale.

jboolean LLML_IMPL_output_quantized(jlong modelHandle, jint index)

Gets the status of the output tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

Returns:

true if the index is valid and the output tensor is quantized, false otherwise.

void LLML_IMPL_set_input_data_as_byte_array(jlong modelHandle, jint index, jbyte *inputData)

Sets the inputData as array of signed or unsigned bytes to the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

• inputData – [in] data to be loaded into the model.

void LLML_IMPL_set_input_data_as_int_array(jlong modelHandle, jint index, jint *inputData)

Sets the inputData as array of signed or unsigned integers to the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index

• inputData – [in] data to be loaded into the model.

void LLML_IMPL_set_input_data_as_float_array(jlong modelHandle, jint index, jfloat *inputData)

Sets the inputData as array of floats to the input tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

• inputData – [in] data to be loaded into the model.

void LLML_IMPL_get_output_data_as_byte_array(jlong modelHandle, jint index, jbyte *outputData)

Gets the outputData of the tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

• outputData – [out] the inference result as array of signed or unsigned bytes if index is valid, null otherwise.

void LLML_IMPL_get_output_data_as_integer_array(jlong modelHandle, jint index, jint *outputData)

Gets the outputData of the tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

• outputData – [out] the inference result as array of signed or unsigned integers if index is valid, null otherwise.

void LLML_IMPL_get_output_data_as_float_array(jlong modelHandle, jint index, jfloat *outputData)

Gets the outputData of the tensor specified by index.

Parameters:

• modelHandle – [in] the model interpreter handle.

• index – [in] the tensor index.

• outputData – [out] the inference result as array of floats if index is valid, null otherwise.

LLEVENT: Event Queue

Two header files are provided:

LLEVENT_impl.h

Defines the set of functions that the BSP must implement to manage, offer/handle events from the Event Queue.

Functions

void LLEVENT_IMPL_initialize(void)

Initializes the event queue.

bool LLEVENT_IMPL_offer_event(uint32_t type, uint32_t data)

Offers an event to the queue.

Parameters:

• type – the type of the event.

• data – the data of the event.

Returns:

true if the message has been sent, false otherwise.

bool LLEVENT_IMPL_offer_extended_event(uint32_t type, const void *data, uint32_t data_length)

Offers an extended event to the queue.

Parameters:

• type – the type of the event.

• data – the data of the event.

Returns:

true if the message has been sent, false otherwise.

uint32_t LLEVENT_IMPL_wait_event(void)

Waits for an event from the queue and returns it.

Returns:

the read event.

void LLEVENT_IMPL_start_read_extended_data(uint32_t data_length)

Starts to read an extended data. Set the data_length_extended_data to the data_length and reset the offset_extended_data_read.

void LLEVENT_IMPL_end_read_extended_data(void)

The Java listener finished to read the data from the event queue. If there is any left data left in the queue, purge it.

jboolean LLEVENT_IMPL_read_boolean(void)

Returns the next boolean of data. Throws IOException if there is no boolean remaining in the extended data.

jbyte LLEVENT_IMPL_read_byte(void)

Returns the next byte of data. Throws IOException if there is no byte remaining in the extended data.

jchar LLEVENT_IMPL_read_char(void)

Returns the next char of data. Throws IOException if there is no char remaining in the extended data.

jdouble LLEVENT_IMPL_read_double(void)

Returns the next double of data. Throws IOException if there is no double remaining in the extended data.

jfloat LLEVENT_IMPL_read_float(void)

Returns the next float of data. Throws IOException if there is no float remaining in the extended data.

jint LLEVENT_IMPL_read(uint8_t *b, uint32_t off, uint32_t len)

Reads len bytes of data from the event queue and store it into the buffer at the offset off. Returns the total number of bytes read into the buffer. Throws IOException if there are not enough bytes available or if the buffer is too small.

jint LLEVENT_IMPL_read_int(void)

Returns the next integer of data. Throws IOException if there is no integer remaining in the extended data.

jlong LLEVENT_IMPL_read_long(void)

Returns the next long of data. Throws IOException if there is no long remaining in the extended data.

jshort LLEVENT_IMPL_read_short(void)

Returns the next short of data. Throws IOException if there is no short remaining in the extended data.

jboolean LLEVENT_IMPL_read_unsigned_byte(void)

Returns the next unsigned byte of data. Throws IOException if there is no unsigned byte remaining in the extended data.

jchar LLEVENT_IMPL_read_unsigned_short(void)

Returns the next unsigned short of data. Throws IOException if there is no unsigned short remaining in the extended data.

jint LLEVENT_IMPL_skip_bytes(uint32_t n)

Skips n bytes. Returns -1 if it did not work.

uint32_t LLEVENT_IMPL_available(void)

Gets the number of available data bytes. Returns the number of available data bytes.

LLEVENT.h

Defines the set of functions that the BSP must implement to use the Event Queue from the native side.

Defines

NO_ERR 0

ERR_WRONG_ARGS -1

ERR_FIFO_FULL -2

Functions

int32_t LLEVENT_offerEvent(int32_t type, int32_t data)

Inserts an event into the FIFO.

The type must be higher than or equal to 0 and lower than 128. The data must not exceed 24-bit. Otherwise use offerExtendedEvent().

Returns:

NO_ERR -> success, ERR_WRONG_ARGS -> failed: illegal arguments, ERR_FIFO_FULL -> failed: the FIFO is full

int32_t LLEVENT_offerExtendedEvent(int32_t type, void *data, int32_t data_length)

Inserts a extended event into the FIFO.

The type must be higher than or equal to 0 and lower than 128. The data_length must not exceed 24-bit.

Returns:

NO_ERR -> success, ERR_WRONG_ARGS -> failed: illegal arguments, ERR_FIFO_FULL -> failed: the FIFO is full

LLFS: File System

Header Files

Two C header files are provided:

• LLFS_impl.h

  Defines a set of functions that the BSP must implement to initialize the FS native component. It also defines some functions to manage files, directories and retrieve information about the underlying File System (free space, total space, etc.).

• LLFS_File_impl.h

  Defines a set of functions that the BSP must implement to do some I/O operations on files (open, read, write, close, etc.).

LLGNSS: GNSS (Global Navigation Satellite System)

Header Files

One header file is provided:

• LLGNSS_impl.h

  Defines the set of functions that the BSP must implement to manage and configure GNSS engine.

LLHAL: Hardware Abstraction Layer

Header Files

One header file is provided:

• LLHAL_impl.h

  Defines the set of functions that the BSP must implement to configure and drive some MCU GPIO.

LLDEVICE: Device Information

Header Files

One C header file is provided:

• LLDEVICE_impl.h

  Defines a set of functions that the BSP must implement to get the Architecture name and unique device identifier.

LLWATCHDOG_TIMER: Watchdog Timer

Header Files

One C header file is provided:

• LLWATCHDOG_TIMER_impl.h

  Defines a set of functions that can be used at BSP level if required.

This C header file contains functions to implement:

• watchdog_timer_helper.h

  Defines a set of functions that the BSP must implement to link the VEE Port watchdog timer to the Watchdog Timer library.

LLCRYPTO: Crypto engine

Header Files

Several C header files are provided, to be implemented by the BSP to integrate a native crypto engine (such as Mbed TLS, OpenSSL or wolfSSL):

• LLCRYPTO_impl.h

  Defines the entry point used to initialize the native crypto engine.

• LLCRYPTO_CIPHER_impl.h

  Defines a set of functions that must be implemented by the BSP in order to decrypt and encrypt data using cryptographic ciphers.

• LLCRYPTO_RSA_CIPHER_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support RSA cipher operations.

• LLCRYPTO_AES_KEY_WRAP_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support AES key wrapping and unwrapping.

• LLCRYPTO_DIGEST_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support message digest algorithms such as SHA-1 or SHA-256.

• LLCRYPTO_MAC_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support MAC algorithms.

• LLCRYPTO_SIG_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support signatures functionalities.

• LLCRYPTO_RANDOM_impl.h

  Defines a set of functions that must be implemented by the BSP in order to generate random data.

• LLCRYPTO_KEY_FACTORY_impl.h

  Defines a set of functions that must be implemented by the BSP in order to get keys informations such as algorithm or encoded form.

• LLCRYPTO_KEY_PAIR_GENERATOR_impl.h

  Defines a set of functions that must be implemented by the BSP in order to generate private/public key pairs.

• LLCRYPTO_SECRET_KEY_FACTORY_impl.h

  Defines a set of functions that must be implemented by the BSP in order to derive secret keys (for example for password-based encryption).

• LLCRYPTO_PRIVATE_KEY_impl.h

  Defines a set of functions that must be implemented by the BSP in order to encode private keys in DER format.

• LLCRYPTO_PUBLIC_KEY_impl.h

  Defines a set of functions that must be implemented by the BSP in order to encode public keys.

• LLCRYPTO_SECRET_KEY_impl.h

  Defines a set of functions that must be implemented by the BSP in order to manage secret keys.

• LLCRYPTO_KEY_AGREEMENT_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support key agreement algorithms such as ECDH.

• LLCRYPTO_CERT_PATH_VALIDATOR_impl.h

  Defines a set of functions that must be implemented by the BSP in order to validate certificate paths (PKIX).

• LLCRYPTO_X509_CERT_impl.h

  Defines a set of functions that must be implemented by the BSP in order to manage X509 certificates operations like getting the public key, extracting the issuer, etc.

• LLCRYPTO_EXTERNAL_KEYSTORE_impl.h

  Defines a set of functions that must be implemented by the BSP in order to access keys and certificates stored in an external key store.

• LLCRYPTO_CONSTANTS.h

  Defines constants for certificates encoding formats.

• LLCRYPTO_ERRORS.h

  Defines the Crypto API error return codes.

LLSEC: Security (deprecated)

Warning

The LLSEC_* LLAPI is deprecated and replaced by the LLCRYPTO_* LLAPI. The legacy LLSEC_*.h headers are kept as backward-compatibility shims that alias the renamed LLCRYPTO_* API and emit a compilation #warning. They will be removed in a future release. New VEE Ports must implement the LLCRYPTO_* headers instead.

Each legacy LLSEC_* header, macro, constant, enum and type maps to its LLCRYPTO_* counterpart by replacing the LLSEC_ prefix with LLCRYPTO_ (the J_* error codes and the CERT_PEM_FORMAT / CERT_DER_FORMAT constants keep their names):

Legacy header (deprecated)	Replacement header
LLSEC_CIPHER_impl.h	LLCRYPTO_CIPHER_impl.h
LLSEC_DIGEST_impl.h	LLCRYPTO_DIGEST_impl.h
LLSEC_MAC_impl.h	LLCRYPTO_MAC_impl.h
LLSEC_SIG_impl.h	LLCRYPTO_SIG_impl.h
LLSEC_RANDOM_impl.h	LLCRYPTO_RANDOM_impl.h
LLSEC_KEY_FACTORY_impl.h	LLCRYPTO_KEY_FACTORY_impl.h
LLSEC_KEY_PAIR_GENERATOR_impl.h	LLCRYPTO_KEY_PAIR_GENERATOR_impl.h
LLSEC_PRIVATE_KEY_impl.h	LLCRYPTO_PRIVATE_KEY_impl.h
LLSEC_PUBLIC_KEY_impl.h	LLCRYPTO_PUBLIC_KEY_impl.h
LLSEC_X509_CERT_impl.h	LLCRYPTO_X509_CERT_impl.h
LLSEC_CONSTANTS.h	LLCRYPTO_CONSTANTS.h
LLSEC_ERRORS.h	LLCRYPTO_ERRORS.h

LLTRACE: Trace

The following API corresponds to architecture version 8.6.0.

Principle

The Trace module provides Low Level APIs to produce lightweight events for debugging and monitoring purposes. The file LLTRACE_impl.h, which comes with the Core Engine, defines the API headers to be implemented.

LLTRACE_impl.h

Set of functions that the BSP must implement to launch and schedule the Core Engine.

Functions

void LLTRACE_IMPL_start(void)

Starts to record the events.

By default, the trace system is stopped.

This function must not be called by the application. Use the corresponding function TRACE_*().

void LLTRACE_IMPL_stop(void)

Stops to record the events. When the record system is stopped, any call to the LLTRACE_IMPL_record_event_* functions must not record any events.

By default, the trace system is stopped.

This function must not be called by the application. Use the corresponding function TRACE_*().

bool LLTRACE_IMPL_is_started(void)

Tests whether the trace system is started or not.

This function must not be called by the application. Use the corresponding function TRACE_*().

Returns:

true if the trace system is started, false otherwise.

int32_t LLTRACE_IMPL_declare_event_group(const char *group_name, int32_t nb_event_types)

Declare a new group of events with the given name. The created group will define nb_event_types types of events. The event IDs available for this group are from 0 to nb_event_types-1.

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_name – name that identifies the group. Must not be null.

• nb_event_types – maximum number of event types available for the group.

Returns:

the ID of the created group or -1 on error.

void LLTRACE_IMPL_record_event_void(int32_t group_id, int32_t event_id)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

void LLTRACE_IMPL_record_event_u32(int32_t group_id, int32_t event_id, uint32_t value1)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x2(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x3(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x4(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x5(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x6(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x7(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x8(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7, uint32_t value8)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

• value8 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x9(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7, uint32_t value8, uint32_t value9)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

• value8 – custom value for the event.

• value9 – custom value for the event.

void LLTRACE_IMPL_record_event_u32x10(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7, uint32_t value8, uint32_t value9, uint32_t value10)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_IMPL_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_IMPL_start()).

This function must not be called by the application. Use the corresponding function TRACE_*().

Parameters:

• group_id – ID of the group returned by LLTRACE_IMPL_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

• value8 – custom value for the event.

• value9 – custom value for the event.

• value10 – custom value for the event.

void LLTRACE_IMPL_record_event_end(int32_t group_id, int32_t event_id)

Record the end of the execution of an event for the given group. Call this function to trace the duration of an event previously record with one of the LLTRACE_IMPL_record_event_*()

void LLTRACE_IMPL_record_event_end_u32(int32_t group_id, int32_t event_id, uint32_t value1)

Record the end of the execution of an event for the given group. Call this function to trace the duration of an event previously record with one of the LLTRACE_IMPL_record_event_()

LLTRACE.h

Set of functions provided by Core Engine that can be called by the BSP to generate event traces.

Functions

void LLTRACE_start(void)

Starts to record the events.

By default, the trace system is stopped.

void LLTRACE_stop(void)

Stops to record the events. When the record system is stopped, any call to the LLTRACE_record_event_* functions will not record any events.

By default, the trace system is stopped.

bool LLTRACE_is_started(void)

Tests whether the trace system is started or not.

Returns:

true if the trace system is started, false otherwise.

int32_t LLTRACE_declare_event_group(const char *group_name, int32_t nb_event_types)

Declare a new group of events with the given name. The created group defines nb_event_types types of events. The event IDs available for this group are from 0 to nb_event_types-1.

Parameters:

• group_name – name that identifies the group. Must not be null.

• nb_event_types – maximum number of event types available for the group.

Returns:

the ID of the created group or -1 on error.

void LLTRACE_record_event_void(int32_t group_id, int32_t event_id)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

void LLTRACE_record_event_u32(int32_t group_id, int32_t event_id, uint32_t value0)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

void LLTRACE_record_event_u32x2(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

void LLTRACE_record_event_u32x3(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

void LLTRACE_record_event_u32x4(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

void LLTRACE_record_event_u32x5(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

void LLTRACE_record_event_u32x6(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

void LLTRACE_record_event_u32x7(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

void LLTRACE_record_event_u32x8(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7, uint32_t value8)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

• value8 – custom value for the event.

void LLTRACE_record_event_u32x9(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7, uint32_t value8, uint32_t value9)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

• value8 – custom value for the event.

• value9 – custom value for the event.

void LLTRACE_record_event_u32x10(int32_t group_id, int32_t event_id, uint32_t value1, uint32_t value2, uint32_t value3, uint32_t value4, uint32_t value5, uint32_t value6, uint32_t value7, uint32_t value8, uint32_t value9, uint32_t value10)

Record an event for the given group. The given event ID must be valid for the specified group (i.e., between 0 and nb_event_types-1 included where nb_event_types is the value given to LLTRACE_declare_event_group()).

The record is done only if the trace system is started (see LLTRACE_start()).

Parameters:

• group_id – ID of the group returned by LLTRACE_declare_event_group().

• event_id – ID of the event.

• value1 – custom value for the event.

• value2 – custom value for the event.

• value3 – custom value for the event.

• value4 – custom value for the event.

• value5 – custom value for the event.

• value6 – custom value for the event.

• value7 – custom value for the event.

• value8 – custom value for the event.

• value9 – custom value for the event.

• value10 – custom value for the event.

void LLTRACE_record_event_end(int32_t group_id, int32_t event_id)

Record the end of the execution of an event for the given group. Call this function to trace the duration of an event previously record with one of the LLTRACE_record_event_*()

void LLTRACE_record_event_end_u32(int32_t group_id, int32_t event_id, uint32_t value1)

Record the end of the execution of an event for the given group. Call this function to trace the duration of an event previously record with one of the LLTRACE_record_event_()

LLMJVM_MONITOR: Core Engine Monitoring

Principle

The Core Engine Monitoring provides Low Level APIs to track the Core Engine behavior at runtime through events and sending task information. The file LLMJVM_MONITOR_impl.h, which comes with the Core Engine, defines the API headers to be implemented.

LLMJVM_MONITOR_impl.h

Set of functions that the BSP must implement to enable trace recording from Core Engine events.

Functions

void LLMJVM_MONITOR_IMPL_initialize(bool auto_start)

This function is called once during Core Engine startup. It may be used to initialize specific data.

When auto_start is true, the monitoring traces must be generated now (i.e., call the LLTRACE_start() function). If auto_start is false, the monitoring traces must not be generated until the function LLTRACE_start() is called. Even if auto_start is false, the Core Engine will call the LLMJVM_MONITOR_IMPL_* functions.

Parameters:

• auto_start – true to start monitoring now, false otherwise.

void LLMJVM_MONITOR_IMPL_on_shutdown(void)

This function is called during Core Engine end. It may be used to freed specific data.

void LLMJVM_MONITOR_IMPL_on_thread_create(int32_t thread_id)

This function is called by the Core Engine when a new Java thread is started.

Implementation can use the function MJVM_MONITOR_get_thread_info() to retrieve more information about the created thread.

Parameters:

• thread_id – ID of the created thread.

void LLMJVM_MONITOR_IMPL_on_thread_modified(int32_t thread_id)

This function is called by the Core Engine when the priority or the name of a Java thread is modified.

Implementation can use the function MJVM_MONITOR_get_thread_info() to retrieve more information about the modified thread.

Parameters:

• thread_id – ID of the modified thread.

void LLMJVM_MONITOR_IMPL_on_thread_state_changed(int32_t thread_id, MJVM_MONITOR_state_t new_state)

This function is called by the Core Engine when the state of a Java thread is modified (e.g., when a thread is waiting, running, etc.).

Parameters:

• thread_id – ID of the modified thread.

• new_state – New state of the thread.

void LLMJVM_MONITOR_IMPL_on_idle(void)

This function is called by the Core Engine when it enter in idle mode (i.e., all the Java threads are sleeping).

void LLMJVM_MONITOR_IMPL_on_gc_start(int32_t current_thread_id)

This function is called by the Core Engine when a garbage collector operation is started.

Parameters:

• current_thread_id – ID of the thread that raises the GC.

void LLMJVM_MONITOR_IMPL_on_gc_phase(int32_t current_thread_id, int32_t phase_id)

This function is called by the Core Engine when a garbage collector intermediate phase is started.

Parameters:

• current_thread_id – ID of the thread that raises the GC.

• phase_id – ID of the GC phase.

void LLMJVM_MONITOR_IMPL_on_gc_stop(int32_t current_thread_id)

This function is called by the Core Engine when a garbage collector operation is finished.

Parameters:

• current_thread_id – ID of the thread that raises the GC.

void LLMJVM_MONITOR_IMPL_on_invoke_method(void *method)

This function is called by the Core Engine when an method is invoked.

Parameters:

• method – the invoked method.

void LLMJVM_MONITOR_IMPL_on_return_method(void *method)

This function is called by the Core Engine when a method returns.

Parameters:

• method – the invoked method.

void LLMJVM_MONITOR_IMPL_on_allocate(void *type, int32_t size, void *method, void *instruction_address, int32_t total_memory, int32_t free_memory, bool immortal)

This function is called by the Core Engine when a new Java object is allocated.

Parameters:

• type – Class of the Java object.

• size – Size in bytes of the Java object.

• method – The Java method that allocates the object.

• instruction_address – Address of the Java instruction that allocates the object.

• total_memory – Total size of the Java heap in bytes.

• free_memory – Amount of the free memory in the Java heap in bytes.

• immortal – true is the allocated object is immortal, false otherwise.

void LLMJVM_MONITOR_IMPL_on_exception(void *exception_type, void *throw_method, void *throw_instruction_address, void *catch_method, void *catch_instruction_address, const char *message)

This function is called by the Core Engine when a Java exception is thrown.

Parameters:

• exception_type – Class of the Java exception.

• throw_method – The Java method that throws the exception.

• throw_instruction_address – Address of the Java instruction that throws the exception.

• catch_method – The Java method that catches the exception.

• catch_instruction_address – Address of the Java instruction that catches the exception.

• message – Message of the exception.

void LLMJVM_MONITOR_IMPL_on_quota_reset(int32_t context_id, int32_t quota)

This function is called by the Core Engine when the quota for an execution context is updated.

Parameters:

• context_id – ID of the execution context being updated.

• quota – The new quota assigned to the execution context.

void LLMJVM_MONITOR_IMPL_on_quota_reached(int32_t context_id)

This function is called by the Core Engine wwhen the quota for an execution context has been reached.

Parameters:

• context_id – ID of the execution context which quota is reached.

void LLMJVM_MONITOR_IMPL_on_quantum_counters_reset(void)

This function is called by the Core Engine when all the quantum counters are reset to zero.

void LLMJVM_MONITOR_IMPL_on_thread_added_to_context(int32_t thread_id, int32_t context_id)

This function is called by the Core Engine when a thread is added to an execution context.

Parameters:

• thread_id – ID of the added thread.

• context_id – ID of the execution context.

MJVM_MONITOR.h

Set of functions provided by Core Engine Monitoring that can be called by the BSP.

Functions

int32_t MJVM_MONITOR_get_threads_ids(int32_t *threads_ids, int32_t threads_ids_length)

Fills in the int32_t array threads_ids with the ID of the alive Java threads.

If the given array is not large enough to contains all the Java threads IDs, the threads_ids_length first Java threads IDs are stored.

This function must be called within the Core Engine task.

Parameters:

• threads_ids – pointer to an int32_t array of threads_ids_length elements.

• threads_ids_length – length of threads_ids array.

Returns:

the number of alive Java threads or MJVM_MONITOR_ERROR if this function is not called within the Core Engine task.

int32_t MJVM_MONITOR_get_thread_info(int32_t thread_id, MJVM_MONITOR_thread_info_t *thread_info, char *name, int32_t name_length)

Fills in the given thread_info structure and name array with the info of the thread and the name of the thread.

Given name array may null. In this case, the name of the thread is not filled in. If given name array is not large enough to copy the name of the thread, then the name is truncated to name_length-1 characters (last character is ‘\0’).

This function must be called within the Core Engine task.

Parameters:

• thread_id – ID of the thread.

• thread_info – pointer to the structure to fill in.

• name – pointer to a char array to fill in with the name of the thread. May be null.

• name_length – length in bytes of the given name array.

Returns:

MJVM_MONITOR_OK on success, MJVM_MONITOR_INVALID_THREAD_ID if the given thread ID is invalid, MJVM_MONITOR_INVALID_THREAD_INFO if thread_info is null

void MJVM_MONITOR_dump_vm(void)

Prints the state of the Core Engine to the standard output stream. For each Java thread, the Java stack trace, the name, the state and the priority are printed.

MJVM_MONITOR_types.h

Types and macros used in the LLMJVM_MONITOR MJVM_MONITOR APIs.

Defines

MJVM_MONITOR_OK (0)

Returned value when function call has succeeded.

MJVM_MONITOR_ERROR (-1)

Returned value when function call has failed.

MJVM_MONITOR_INVALID_THREAD_INFO (-2)

Returned value when an invalid MJVM_MONITOR_ThreadInfo struct is given to a function.

MJVM_MONITOR_INVALID_THREAD_ID (-3)

Returned value when an invalid Java thread ID is given to a function.

Enums

enum MJVM_MONITOR_state_t

Specifies the states of the Java threads.

Values:

enumerator MJVM_MONITOR_STATE_READY = 1

In the ready state, all functional prerequisites for a transition into the running state exist, and the thread only waits for allocation of the processor. The scheduler decides which ready thread is executed next.

enumerator MJVM_MONITOR_STATE_RUNNING = 2

In the running state, the CPU is assigned to the thread, so that its instructions can be executed. Only one thread can be in this state at any point in time, while all the other states can be adopted simultaneously by several threads.

enumerator MJVM_MONITOR_STATE_WAITING = 3

Thread state for a waiting thread. A thread is in the waiting state due to calling one of the following methods:

• Thread.sleep

• Object.wait

• Thread.join

• SNI_suspendCurrentJavaThread

enumerator MJVM_MONITOR_STATE_MONITOR_QUEUED = 4

In the monitor queued state, a thread cannot continue execution because a monitor it tries to acquire is already owned by another thread. When this monitor is released, it will try to gain the ownership of the monitor. If it succeeds, it will be transferred into the ready state, otherwise it will remain in the monitor queued state.

enumerator MJVM_MONITOR_STATE_TERMINATED = 6

In the terminated state the thread is passive and has completed its execution.

struct MJVM_MONITOR_thread_info_t

#include <MJVM_MONITOR_types.h>

Public Members

int32_t id

ID of the thread.

int32_t priority

Java priority of the thread.

MJVM_MONITOR_state_t state

Current state of the thread.

int32_t max_stack_usage

Maximum Java stack usage in bytes. -1 if not available.