GOS
GOS is the module which builds the abstraction layer between µGFX and the underlying system. The underlying system can be an RTOS such as ChibiOS or FreeRTOS, or also just a stand-alone library like the STDperiph library from STmicroelectronics. The GOS module allows to write completely platform independent application code.
Contents
API reference
The API reference of the GOS module can be found here.
Configuration
ToDo
Initialization
For code portability reasons the underlying system will be automatically initialized when gosInit()
is called unless GFX_NO_OS_INIT is set to TRUE in the configuration file.
Threading
It is highly recommended to use the uGFX API to create and manage threads. This way the application is fully portable. In most cases these are just 1:1 wrappers to the calls from the underlying operating systems so there is no additional overhead.
Please take a look at the API reference of the GOS module to learn about all the available functions.
The following demos which can be found in the uGFX repository show how to properly use the threading API:
- /demos/modules/gos/threads
- /demos/modules/gos/threads_advanced
Thread priority
The number of different thread priorities is not clearly defined as every underlying operating system implements this feature differently. However, the GOS module ensures that the following three priority levels are defined:
LOW_PRIORITY NORMAL_PRIORITY HIGH_PRIORITY
As thread priorities are usually implemented in form of integer variables, you can increment and decrement these defines in order to further split the thread priorities. For example:
/* Normal priority thread */ NORMAL_PRIORITY /* High priority thread */ HIGH_PRIORITY /* A thread that has a slightly higher priority than the normal priority but with a still smaller priority than the high priroty thread */ NORMAL_PRIORITY + 1
Terminating a thread
The uGFX API does not provide any function to terminate a running thread. This is due to the fact that only very few operating systems provide the feature to terminate a running thread from within another thread. However, it's still possible to tell a thread to terminate itself. This can for example be accomplished by implementing a 'falling over the edge' algorithm where a variable is passed to the custom parameter of the thread function. The thread will frequently check this variable which tells whether the thread should return or not. As the variable is only passed as a pointer it can be modified out of another thread.
The /demos/modules/gos/threads_advanced demo shows how to implement such an algorithm. Basically it looks like this:
threadreturn_t threadFunction(void* param) { /* Cast the paramter into a bool pointer so we can use it */ bool_t* doExit = (bool_t*)param; /* Execute this until we shall be terminated */ while (*doExit == FALSE) { /* Do the actual work... */ } /* Don't return anything (or return something) */ return (threadreturn_t)0; } int main(void) { bool_t exitThread = FALSE; /* Start the thread and pass the variable as a parameter to tell the thread to terminate later */ gfxThreadCreate(NULL, 128, NORMAL_PRIORITY, threadFunction, (void*)&exitThread); /* Tell the thread to return */ exitThread = TRUE; }
Memory management
It is highly recommended to use the uGFX API for memory management. This way the application is fully portable. In most cases these calls are just 1:1 wrappers to the calls from the underlying operating system so there is no additional overhead.
Please take a look at the API reference of the GOS module to learn about all the available functions.
Existing ports
The following ports already exist and are part of the official repository:
- ChibiOS/RT
- FreeRTOS
- eCos
- rawrtos
- BareMetal (no OS at all)
- Arduino
- Linux
- Mac OS X
- Windows
BareMetal
It's possible to run µGFX directly on a bare-metal system like the stdperipheral library for the STM controller without any underlying OS. Start with the RAW32 implementation. This supports a simple non-preemptive scheduler. You still need to provide some basic routines such as a routine to get the system tick count.
Porting
Porting uGFX to a new underlying system is fairly easy. Only a couple of functions and data types have to be implemented and declared.
Functions
ToDo
void gfxHalt(const char *msg); void gfxExit(void); void* gfxAlloc(size_t sz); void* gfxRealloc(void *p, size_t oldsz, size_t newsz); void gfxFree(void *ptr); void gfxYield(void); void gfxSleepMilliseconds(delaytime_t ms); void gfxSleepMicroseconds(delaytime_t ms); systemticks_t gfxSystemTicks(void); systemticks_t gfxMillisecondsToTicks(delaytime_t ms); void gfxSystemLock(void); void gfxSystemUnlock(void); void gfxMutexInit(gfxMutex *pmutex); void gfxMutexDestroy(gfxMutex *pmutex); void gfxMutexEnter(gfxMutex *pmutex); void gfxMutexExit(gfxMutex *pmutex); void gfxSemInit(gfxSem *psem, semcount_t val, semcount_t limit); void gfxSemDestroy(gfxSem *psem); bool_t gfxSemWait(gfxSem *psem, delaytime_t ms); void gfxSemSignal(gfxSem *psem); void gfxSemSignalI(gfxSem *psem); semcount_t gfxSemCounter(gfxSem *pSem); semcount_t gfxSemCounterI(gfxSem *pSem); gfxThreadHandle gfxThreadCreate(void *stackarea, size_t stacksz, threadpriority_t prio, DECLARE_THREAD_FUNCTION((*fn),p), void *param); threadreturn_t gfxThreadWait(gfxThreadHandle thread); gfxThreadHandle gfxThreadMe(void) void gfxThreadClose(gfxThreadHandle thread);
Data types
ToDo
Examples
When creating a new port, taking a look at existing ones can help a lot. The existing ports can be found under /src/gos/