Difference between revisions of "BareMetal"

Latest revision as of 09:27, 11 August 2021

µGFX can run on any system without any underlying OS or RTOS. The RAW32 port provides all the required implementations to run on a bare metal system. The only thing required to implement by the user are two small functions which are used to calculate delays. See #SysTick.

The RAW32 port also provides a multi-tasker that you can use in your own applications. The threads created are co-operative (non-preemptive) threads (you have to use gfxSleepMilliseconds() or gfxYield() to give another task a chance to run). See GOS.

Using RAW32

To run µGFX on a bare-metal platform without any underlying operating system, the Raw32 port has to be enabled by setting GFX_USE_OS_RAW32 to TRUE in the configuration file.

Memory Management

µGFX can run either completely on static memory or on dynamic memory. While the first is very important for security and time critical applications it can be very tedious in generic applications. The RAW32 provides a memory manager to work with dynamic memory on any bare metal system. The following two configuration options are available:

• Use the µGFX built-in memory manager
• Use the C runtime library memory manager

Which one is used depends on the value of GFX_OS_HEAP_SIZE inside of the configuration file.

Built-in memory manager

When GFX_OS_HEAP_SIZE is set to a value greater than 0 then the built-in memory manager of µGFX is used. In this case the value of GFX_OS_HEAP_SIZE specifies the size of the memory pool which the built-in memory manager will use.

C runtime library memory manager

When GFX_OS_HEAP_SIZE is set to 0 then the memory manager of the C runtime library will be used. In that case gfxAlloc() and gfxFree() are just wrappers around malloc() and free().

Note that many C library implementations of malloc() and free() have bugs that cause them to crash if the stack is changed (as it is for threading as required by µGFX). For this reason, if you are getting strange crashes it is advisable to use the built-in memory manager and to avoid using malloc() and free() in your own code (use gfxAlloc() and gfxFree() instead).

SysTick

Some parts of the µGFX library require how much time passed by. For this access to the systems tick counter (SysTick) is required. To give µGFX the ability to calculate how much time passed the following to functions need to be implemented in the users application code:

gTicks gfxSystemTicks(void);
gTicks gfxMillisecondsToTicks(delaytime_t ms);

The first one, gfxSystemTicks(), needs to return the current value of the systick counter. The second one, gfxMillisecondsToTicks() needs to convert the provided value in milliseconds to systicks.

Example

The following is an example showing how to implement the two functions when using an STM32F4 microcontroller using the STM32Cube HAL. Note that in this case the systick was set up to be incremented once every millisecond. If your systick updates in a different interval you need to do the corresponding calculations in gfxMillisecondsToTicks().

#include "stm32f4xx_hal.h"
#include "gfx.h"
 
gTicks gfxSystemTicks(void)
{
	return HAL_GetTick();
}
 
gTicks gfxMillisecondsToTicks(gDelay ms)
{
	return ms;
}

Note: It is important that gfx.h is included after stm32f4xx_hal.h to avoid naming conflicts when using the CubeHAL with µGFX.