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

Naming Convention

The Low Level Core Engine API, the LLMJVM API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLMJVM_IMPL_* pattern.

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 the application object file has not been correclty linked by the third-party linker.

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 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.

LLKERNEL: Multi-Sandbox

Naming Convention

The Low Level Kernel API, the LLKERNEL API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLKERNEL_IMPL_* pattern.

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..LLKERNEL_getAllocatedFeaturesCount-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..LLKERNEL_getAllocatedFeaturesCount-1].

See also

LLKERNEL_getAllocatedFeaturesCount

Parameters:

index – an index within the range [0..LLKERNEL_getAllocatedFeaturesCount-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

Naming Convention

The Low Level Shielded Plug API, the LLSP API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLSP_IMPL_* pattern.

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.

Naming Convention

The Low Level API, the LLEXT_RES API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLEXT_RES_IMPL_* pattern.

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.

LLCOMM: Serial Communications

Naming Convention

The Low Level Comm API (LLCOMM), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLCOM_BUFFERED_CONNECTION_IMPL_* or the LLCOM_CUSTOM_CONNECTION_IMPL_*pattern.

Header Files

Four C header files are provided:

• LLCOMM_BUFFERED_CONNECTION_impl.h

  Defines the set of functions that the driver must implement to provide a Buffered connection

• LLCOMM_BUFFERED_CONNECTION.h

  Defines the set of functions provided by ECOM Comm that can be called by the driver (or other C code) when using a Buffered connection

• LLCOMM_CUSTOM_CONNECTION_impl.h

  Defines the set of functions that the driver must implement to provide a Custom connection

• LLCOMM_CUSTOM_CONNECTION.h

  Defines the set of functions provided by ECOM Comm that can be called by the driver (or other C code) when using a Custom connection

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).

LLUI_DISPLAY: Display

Principle & Naming Convention

The Graphics Engine provides some Low Level APIs to connect a display driver. The file LLUI_DISPLAY_impl.h defines the API headers to be implemented. For the APIs themselves, the naming convention is that their names match the *_IMPL_* pattern when the functions need to be implemented:

• LLUI_DISPLAY_IMPL_initialize

• LLUI_DISPLAY_IMPL_binarySemaphoreTake

• LLUI_DISPLAY_IMPL_binarySemaphoreGive

• LLUI_DISPLAY_IMPL_flush

Some additional Low Level APIs allow you to connect display extra features. These Low Level APIs are not required. When they are not implemented, a default implementation is used (weak function). It concerns backlight, contrast, etc.

This describes succinctly some LLUI_DISPLAY_IMPL functions. Please refer to documentation inside header files to have more information.

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.

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.

Naming Convention

The Low Level APIs rely on functions that must be implemented. The naming convention for such functions is that their names match the *_IMPL_* pattern.

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.

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.

Naming Convention

The Low Level APIs rely on functions that must be implemented. The naming convention for such functions is that their names match the *_IMPL_* pattern.

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.

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.

Naming Convention

The Low Level APIs rely on functions that must be implemented. The naming convention for such functions is that their names match the *_IMPL_* pattern.

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).

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).

Naming Convention

The Low Level APIs rely on functions that must be implemented. The naming convention for such functions is that their names match the *_IMPL_* pattern.

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.

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.

Naming Convention

The Low Level APIs rely on functions that must be implemented. The naming convention for such functions is that their names match the *_IMPL_* pattern.

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.

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.

Naming Convention

The Low Level APIs rely on functions that must be implemented. The naming convention for such functions is that their names match the *_IMPL_* pattern.

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.

LLNET: Network

Naming Convention

The Low Level API, the LLNET API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLNET_IMPL_* pattern.

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

Naming Convention

The Low Level API, the LLNET_SSL API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLNET_SSL_* pattern.

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

Naming Convention

The Low Level Network Interfaces API (LLECOM_NETWORK), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLECOM_NETWORK_IMPL_* pattern.

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

Naming Convention

The Low Level Wi-FI API (LLECOM_WIFI), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLECOM_WIFI_IMPL_* pattern.

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

Naming Convention

The Low Level Bluetooth API (LLBLUETOOTH), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLBLUETOOTH_IMPL_* pattern.

Header Files

Two header files are provided:

• LLBLUETOOTH_defines.h

  Defines constants and types which are used by the functions to implement.

• LLBLUETOOTH_impl.h

  Defines the set of functions that the BSP must implement to manage and configure and Bluetooth module.

LLAUDIO: Audio

Naming Convention

The Low Level Audio API (LLAUDIO), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLAUDIO_*_IMPL_* pattern.

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

Naming Convention

The Low Level MicroAI API (LLML), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLML_IMPL_* pattern.

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…

LLEVENT: Event Queue

Naming Convention

The Low Level Event Queue API (LLEVENT), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLEVENT_IMPL_* or LLEVENT_* pattern.

Header Files

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.

• LLEVENT.h

  Defines the set of functions that the BSP must implement to use the Event Queue from the native side.

LLFS: File System

Naming Convention

The Low Level File System API (LLFS), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLFS_IMPL_* and the LLFS_File_IMPL_* pattern.

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)

Naming Convention

The Low Level GNSS API (LLGNSS), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLGNSS_IMPL_* pattern.

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

Naming Convention

The Low Level API, the LLHAL API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLHAL_IMPL_* pattern.

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

Naming Convention

The Low Level Device API (LLDEVICE), relies on functions that need to be implemented by engineers in a driver. The names of these functions match the LLDEVICE_IMPL_* pattern.

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

Naming Convention

The Low Level Watchdog Timer API (LLWATCHDOG_TIMER), provides functions that allow the use of this API at the BSP level in C. The names of these functions match the LLWATCHDOG_TIMER_IMPL_* pattern.

The Watchdog API is delivered with a Generic C implementation on which the VEE Port must depend. This implementation relies on functions that need to be implemented by engineers in a driver. The name of these functions match the LLWATCHDOG_TIMER_IMPL_*_action pattern.

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.

LLSEC: Security

Naming Convention

The Low Level Security API (LLSEC) provides functions that allow the use of this API at the BSP level in C. The names of these functions match the LLSEC_*_IMPL_* pattern.

Header Files

Several C header files are provided:

• LLSEC_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.

• LLSEC_CONSTANTS.h

  Defines constants for certificates encoding formats.

• LLSEC_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.

• LLSEC_ERRORS.h

  Defines the Security API error return codes.

• LLSEC_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.

• LLSEC_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.

• LLSEC_MAC_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support MAC algorithms.

• LLSEC_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.

• LLSEC_PUBLIC_KEY_impl.h

  Defines a set of functions that must be implemented by the BSP in order to encode public keys.

• LLSEC_RANDOM_impl.h

  Defines a set of functions that must be implemented by the BSP in order to generate random data.

• LLSEC_SIG_impl.h

  Defines a set of functions that must be implemented by the BSP in order to support signatures functionalities.

• LLSEC_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.

LLTRACE: Trace

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.

Naming Convention

The Low Level Trace API LLTRACE relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLTRACE_IMPL_* pattern described in the file LLTRACE_impl.h.

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_*() function. This function should not be called for event that has no duration.

For example, if you want to trace the execution of a function, you can call LLTRACE_IMPL_record_event_*() at the beginning of the function and LLTRACE_IMPL_record_event_end*() at the end of the function.

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_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_() function. This function should not be called for event that has no duration.

For example, if you want to trace the execution of a function, you can call LLTRACE_IMPL_record_event_*() at the beginning of the function and LLTRACE_IMPL_record_event_end*() at the end of the function.

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 end.

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.

• value0 – 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_*() functions. This function should not be called for event that has no duration.

For example, if you want to trace the execution of a function, you can call LLTRACE_record_event_*() at the beginning of the function and LLTRACE_record_event_end*() at the end of the function.

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_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_() functions. This function should not be called for event that has no duration.

For example, if you want to trace the execution of a function, you can call LLTRACE_record_event_*() at the beginning of the function and LLTRACE_record_event_end*() at the end of the function.

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 end.

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.

Naming Convention

The Low Level Core Engine Monitoring API, the LLMJVM_MONITOR API, relies on functions that need to be implemented. The naming convention for such functions is that their names match the LLMJVM_MONITOR_IMPL_* pattern.

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_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()

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.