version 2.8
GOS

Detailed Description

Module to build a uniform abstraction layer between uGFX and the underlying system.

Note
Some of the routines specified below may be implemented simply as a macro to the real operating system call.

Data Structures

struct  gfxSem
 A semaphore. More...
 
struct  gfxMutex
 A mutex. More...
 

Functions

void gfxHalt (const char *msg)
 Halt the GFX application due to an error. More...
 
void gfxExit (void)
 Exit the GFX application. More...
 
void * gfxAlloc (size_t sz)
 Allocate memory. More...
 
void * gfxRealloc (void *ptr, size_t oldsz, size_t newsz)
 Re-allocate memory. More...
 
void gfxFree (void *ptr)
 Free memory. More...
 
void gfxYield (void)
 Yield the current thread. More...
 
void gfxSleepMilliseconds (delaytime_t ms)
 Put the current thread to sleep for the specified period in milliseconds. More...
 
void gfxSleepMicroseconds (delaytime_t us)
 Put the current thread to sleep for the specified period in microseconds. More...
 
systemticks_t gfxSystemTicks (void)
 Get the current operating system tick time. More...
 
systemticks_t gfxMillisecondsToTicks (delaytime_t ms)
 Convert a given number of millseconds to a number of operating system ticks. More...
 
void gfxSystemLock (void)
 Lock the operating system to protect a sequence of code. More...
 
void gfxSystemUnlock (void)
 Unlock the operating system previous locked by gfxSystemLock() More...
 
void gfxMutexInit (gfxMutex *pmutex)
 Initialise a mutex to protect a region of code from other threads. More...
 
void gfxMutexDestroy (gfxMutex *pmutex)
 Destroy a Mutex. More...
 
void gfxMutexEnter (gfxMutex *pmutex)
 Enter the critical code region protected by the mutex. More...
 
void gfxMutexExit (gfxMutex *pmutex)
 Exit the critical code region protected by the mutex. More...
 
void gfxSemInit (gfxSem *psem, semcount_t val, semcount_t limit)
 Initialise a Counted Semaphore. More...
 
void gfxSemDestroy (gfxSem *psem)
 Destroy a Counted Semaphore. More...
 
bool_t gfxSemWait (gfxSem *psem, delaytime_t ms)
 Wait on a semaphore. More...
 
bool_t gfxSemWaitI (gfxSem *psem)
 Test if a wait on a semaphore can be satisfied immediately. More...
 
void gfxSemSignal (gfxSem *psem)
 Signal a semaphore. More...
 
void gfxSemSignalI (gfxSem *psem)
 Signal a semaphore. More...
 
gfxThreadHandle gfxThreadCreate (void *stackarea, size_t stacksz, threadpriority_t prio, DECLARE_THREAD_FUNCTION((*fn), p), void *param)
 Start a new thread. More...
 
threadreturn_t gfxThreadWait (gfxThreadHandle thread)
 Wait for a thread to finish. More...
 
gfxThreadHandle gfxThreadMe (void)
 Get the current thread handle. More...
 
void gfxThreadClose (gfxThreadHandle thread)
 Close the thread handle. More...
 

Various integer sizes

Note
Your platform may use slightly different definitions to these
typedef unsigned char bool_t
 
typedef char int8_t
 
typedef unsigned char uint8_t
 
typedef short int16_t
 
typedef unsigned short uint16_t
 
typedef long int32_t
 
typedef unsigned long uint32_t
 

Various platform (and operating system) dependent types

Note
Your platform may use slightly different definitions to these
typedef unsigned long size_t
 
typedef unsigned long delaytime_t
 
typedef unsigned long systemticks_t
 
typedef short semcount_t
 
typedef int threadreturn_t
 
typedef int threadpriority_t
 

Various platform (and operating system) constants

Note
Your platform may use slightly different definitions to these
#define FALSE   0
 
#define TRUE   1
 
#define TIME_IMMEDIATE   0
 
#define TIME_INFINITE   ((delaytime_t)-1)
 
#define MAX_SEMAPHORE_COUNT   ((semcount_t)(((unsigned long)((semcount_t)(-1))) >> 1))
 
#define LOW_PRIORITY   0
 
#define NORMAL_PRIORITY   1
 
#define HIGH_PRIORITY   2
 

The operating system to use. One (and only one) of these must be defined.

#define GFX_USE_OS_CHIBIOS   FALSE
 Use ChibiOS. More...
 
#define GFX_USE_OS_FREERTOS   FALSE
 Use FreeRTOS. More...
 
#define GFX_USE_OS_WIN32   FALSE
 Use Win32. More...
 
#define GFX_USE_OS_LINUX   FALSE
 Use a linux based system running X11. More...
 
#define GFX_USE_OS_OSX   FALSE
 Use a Mac OS-X based system. More...
 
#define GFX_USE_OS_RAW32   FALSE
 Use a Raw 32-bit CPU based system (Bare Metal) More...
 
#define GFX_USE_OS_ECOS   FALSE
 Use a eCos. More...
 
#define GFX_USE_OS_RAWRTOS   FALSE
 Use RAWRTOS. More...
 
#define GFX_USE_OS_ARDUINO   FALSE
 Use Arduino. More...
 
#define GFX_USE_OS_CMSIS   FALSE
 Use CMSIS RTOS compatible OS. More...
 
#define GFX_USE_OS_CMSIS2   FALSE
 Use CMSIS2 RTOS compatible OS. More...
 
#define GFX_USE_OS_KEIL   FALSE
 Use Keil CMSIS 1.x (RTOS, RTX4) More...
 
#define GFX_USE_OS_RTX5   FALSE
 Use Keil RTX5. More...
 
#define GFX_USE_OS_NIOS   FALSE
 Use NIOS-II. More...
 
#define GFX_USE_OS_ZEPHYR   FALSE
 Use Zephyr. More...
 
#define GFX_USE_OS_QT   FALSE
 Use Qt. More...
 

GFX_OS_EXTRA_DEINIT_FUNCTION

A macro that defines a function that uGFX calls as part of gfxDeInit() just before de-initializing the operating system.

Defaults to undefined

Note
If defined the specified function is called just before the operating system is de-initialized by gfxDeInit().
Eg. In your source: void myOSDeInitRoutine(void); In gfxconf.h: #define GFX_OS_EXTRA_DEINIT_FUNCTION myOSDeInitRoutine
#define GFX_OS_NO_INIT   FALSE
 Should uGFX avoid initializing the operating system. More...
 
#define GFX_OS_INIT_NO_WARNING   FALSE
 Turn off warnings about initializing the operating system. More...
 
#define GFX_OS_CALL_UGFXMAIN   FALSE
 Call uGFXMain() after all initialisation. More...
 
#define GFX_OS_UGFXMAIN_STACKSIZE   0
 When uGFXMain() is started as a thread, what stack size should be used. More...
 
#define GFX_FREERTOS_USE_TRACE   FALSE
 Should uGFX stuff be added to the FreeRTOS+Tracer. More...
 
#define GFX_OS_HEAP_SIZE   0
 How much RAM should uGFX use for the heap when using its own internal heap allocator. More...
 
#define GFX_EMULATE_MALLOC   FALSE
 Enable wrappers for malloc() and free() More...
 

Macros

#define DECLARE_THREAD_FUNCTION(fnName, param)   threadreturn_t fnName(void *param)
 Declare a thread function. More...
 
#define DECLARE_THREAD_STACK(name, sz)   uint8_t name[sz];
 Declare a thread stack. More...
 
#define GFX_EMULATE_MALLOC   FALSE
 Use gfxAlloc and gfxFree to implement malloc() and free() More...
 

Typedefs

typedef void * gfxThreadHandle
 A thread handle. More...
 

Function Documentation

void* gfxAlloc ( size_t  sz)

Allocate memory.

Returns
A pointer to the memory allocated or NULL if there is no more memory available
Parameters
[in]szThe size in bytes of the area to allocate
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by gdriverRegister().

void gfxExit ( void  )

Exit the GFX application.

Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxFree ( void *  ptr)

Free memory.

Parameters
[in]ptrThe memory to free
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by gdriverRegister(), and gdriverUnRegister().

void gfxHalt ( const char *  msg)

Halt the GFX application due to an error.

Parameters
[in]msgAn optional debug message to show (Can be NULL)
Function Class:
Normal API, this function can be invoked by regular system threads.
systemticks_t gfxMillisecondsToTicks ( delaytime_t  ms)

Convert a given number of millseconds to a number of operating system ticks.

Returns
The period in system ticks.
Note
A "tick" is an arbitrary period of time that the operating system uses to mark time.
Parameters
[in]msThe number of millseconds
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by gtimerStart().

void gfxMutexDestroy ( gfxMutex pmutex)

Destroy a Mutex.

Parameters
[in]pmutexA pointer to the mutex
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxMutexEnter ( gfxMutex pmutex)

Enter the critical code region protected by the mutex.

Blocks until there is no other thread in the critical region.

Parameters
[in]pmutexA pointer to the mutex
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by geventAttachSource(), geventDetachSource(), geventDetachSourceListeners(), geventEventComplete(), geventGetEventBuffer(), geventGetSourceListener(), geventSendEvent(), gtimerJab(), gtimerStart(), and gtimerStop().

void gfxMutexExit ( gfxMutex pmutex)

Exit the critical code region protected by the mutex.

May cause another thread waiting on the mutex to now be placed into the run queue.

Parameters
[in]pmutexA pointer to the mutex
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by geventAttachSource(), geventDetachSource(), geventDetachSourceListeners(), geventEventComplete(), geventGetEventBuffer(), geventGetSourceListener(), geventSendEvent(), gtimerJab(), gtimerStart(), and gtimerStop().

void gfxMutexInit ( gfxMutex pmutex)

Initialise a mutex to protect a region of code from other threads.

Parameters
[in]pmutexA pointer to the mutex
Note
Whilst a counting semaphore with a limit of 1 can be used for similiar purposes on many operating systems using a seperate mutex structure is more efficient.
Function Class:
Normal API, this function can be invoked by regular system threads.
void* gfxRealloc ( void *  ptr,
size_t  oldsz,
size_t  newsz 
)

Re-allocate memory.

Returns
A pointer to the new memory area or NULL if there is no more memory available
Parameters
[in]ptrThe old memory area to be increased/decreased in size
[in]oldszThe size in bytes of the old memory area
[in]newszThe size in bytes of the new memory area
Note
Some operating systems don't use the oldsz parameter as they implicitly know the size of old memory area. The parameter must always be supplied however for API compatibility.
gfxRealloc() can make the area smaller or larger but may have to return a different pointer. If this occurs the new area contains a copy of the data from the old area. The old memory pointer should not be used after this routine as the original area may have been freed.
If there is insufficient memory to create the new memory region, NULL is returned and the old memory area is left unchanged.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxSemDestroy ( gfxSem psem)

Destroy a Counted Semaphore.

Parameters
[in]psemA pointer to the semaphore
Note
Any threads waiting on the semaphore will be released
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxSemInit ( gfxSem psem,
semcount_t  val,
semcount_t  limit 
)

Initialise a Counted Semaphore.

Parameters
[in]psemA pointer to the semaphore
[in]valThe initial value of the semaphore
[in]limitThe maxmimum value of the semaphore
Note
Operations defined for counted semaphores: Signal: The semaphore counter is increased and if the result is non-positive then a waiting thread is queued for execution. Note that once the thread reaches "limit", further signals are ignored. Wait: The semaphore counter is decreased and if the result becomes negative the thread is queued in the semaphore and suspended.
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by geventListenerInit().

void gfxSemSignal ( gfxSem psem)

Signal a semaphore.

The semaphore counter is increased and if the result is non-positive then a waiting thread is queued for execution. Note that once the thread reaches "limit", further signals are ignored.

Parameters
[in]psemA pointer to the semaphore
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by geventSendEvent(), gtimerJab(), and gtimerStart().

void gfxSemSignalI ( gfxSem psem)

Signal a semaphore.

The semaphore counter is increased and if the result is non-positive then a waiting thread is queued for execution. Note that once the thread reaches "limit", further signals are ignored.

Parameters
[in]psemA pointer to the semaphore
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by gtimerJabI().

bool_t gfxSemWait ( gfxSem psem,
delaytime_t  ms 
)

Wait on a semaphore.

The semaphore counter is decreased and if the result becomes negative the thread waits for it to become non-negative again

Returns
FALSE if the wait timeout occurred otherwise TRUE
Parameters
[in]psemA pointer to the semaphore
[in]msThe maximum time to wait for the semaphore
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by geventEventWait().

bool_t gfxSemWaitI ( gfxSem psem)

Test if a wait on a semaphore can be satisfied immediately.

Equivalent to gfxSemWait(psem, TIME_IMMEDIATE) except it can be called at interrupt level

Returns
FALSE if the wait would occur occurred otherwise TRUE
Parameters
[in]psemA pointer to the semaphore
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxSleepMicroseconds ( delaytime_t  us)

Put the current thread to sleep for the specified period in microseconds.

Parameters
[in]usThe number microseconds to sleep
Note
Specifying TIME_IMMEDIATE will return immediately (no sleeping)
Specifying TIME_INFINITE will sleep forever.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxSleepMilliseconds ( delaytime_t  ms)

Put the current thread to sleep for the specified period in milliseconds.

Parameters
[in]msThe number milliseconds to sleep
Note
Specifying TIME_IMMEDIATE will yield the current thread but return on the next time slice.
Specifying TIME_INFINITE will sleep forever.
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by ginputGetToggleStatus().

void gfxSystemLock ( void  )

Lock the operating system to protect a sequence of code.

Note
Calling this will lock out all other threads from executing even at interrupt level within the GFX system. On hardware this may be implemented as a disabling of interrupts, however in an operating system which hides real interrupt level code it may simply use a mutex lock.
The thread MUST NOT block whilst the system is locked. It must execute in this state for as short a period as possible as this can seriously affect interrupt latency on some platforms.
While locked only interrupt level (iclass) GFX routines may be called.
Function Class:
Normal API, this function can be invoked by regular system threads.
systemticks_t gfxSystemTicks ( void  )

Get the current operating system tick time.

Returns
The current tick time
Note
A "tick" is an arbitrary period of time that the operating system uses to mark time.
The absolute value of this call is relatively meaningless. Its usefulness is in calculating periods between two calls to this function.
As the value from this function can wrap it is important that any periods are calculated as t2 - t1 and then compared to the desired period rather than comparing t1 + period to t2
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by gtimerStart().

void gfxSystemUnlock ( void  )

Unlock the operating system previous locked by gfxSystemLock()

Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxThreadClose ( gfxThreadHandle  thread)

Close the thread handle.

Parameters
[in]threadThe Thread Handle
Note
This does not affect the thread, it just closes our handle to the thread.
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by gtimerStart().

gfxThreadHandle gfxThreadCreate ( void *  stackarea,
size_t  stacksz,
threadpriority_t  prio,
DECLARE_THREAD_FUNCTION((*fn), p)  ,
void *  param 
)

Start a new thread.

Returns
Returns a thread handle if the thread was started, NULL on an error
Parameters
[in]stackareaA pointer to the area for the new threads stack or NULL to dynamically allocate it
[in]stackszThe size of the thread stack. 0 means the default operating system size although this is only valid when stackarea is dynamically allocated.
[in]prioThe priority of the new thread
[in]fnThe function the new thread will run
[in]paramA parameter to pass the thread function.
Function Class:
Normal API, this function can be invoked by regular system threads.

Referenced by gtimerStart().

gfxThreadHandle gfxThreadMe ( void  )

Get the current thread handle.

Returns
A thread handle
Function Class:
Normal API, this function can be invoked by regular system threads.
threadreturn_t gfxThreadWait ( gfxThreadHandle  thread)

Wait for a thread to finish.

Returns
Returns the thread exit code.
Parameters
[in]threadThe Thread Handle
Note
This will also close the thread handle as it is no longer useful once the thread has ended.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfxYield ( void  )

Yield the current thread.

Give up the rest of the current time slice for this thread in order to give other threads a chance to run.

Function Class:
Normal API, this function can be invoked by regular system threads.

Macro Definition Documentation

#define DECLARE_THREAD_FUNCTION (   fnName,
  param 
)    threadreturn_t fnName(void *param)

Declare a thread function.

Parameters
[in]fnNameThe name of the function
[in]paramA custom parameter that is passed to the function

Definition at line 62 of file gos.h.

#define DECLARE_THREAD_STACK (   name,
  sz 
)    uint8_t name[sz];

Declare a thread stack.

Parameters
[in]nameThe name of the stack
[in]szThe size of the stack in bytes
Note
The size provided is just a suggestion to the required stack size. Many platforms will round the size to ensure correct stack alignment. Other platforms may entirely ignore the suggested size.

Definition at line 74 of file gos.h.

#define GFX_EMULATE_MALLOC   FALSE

Use gfxAlloc and gfxFree to implement malloc() and free()

Note
Sometimes your application will include functions that want to internally use malloc() and free(). As the default implementations of these in your C library are almost invariably incorrect for an embedded platform, this option allows you to emulate those calls with gfxAlloc() and gfxFree(). An example is the C library routine rand() which on many implementations internally uses malloc().
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 196 of file gos.h.

#define GFX_EMULATE_MALLOC   FALSE

Enable wrappers for malloc() and free()

Defaults to FALSE

Note
If enabled, malloc() and free() will be implemented as wrappers that call gfxAlloc() and gfxFree() in order to provide portability to libraries using these function.
Enabling this can solve 'unresolved _sbrk' issues
It is strongly recommended to always use gfxAlloc() and gfxFree() directy to ensure portability of uGFX applications across all platforms.

Definition at line 261 of file gos_options.h.

#define GFX_FREERTOS_USE_TRACE   FALSE

Should uGFX stuff be added to the FreeRTOS+Tracer.

Defaults to FALSE

Definition at line 234 of file gos_options.h.

#define GFX_OS_CALL_UGFXMAIN   FALSE

Call uGFXMain() after all initialisation.

Defaults to FALSE

Note
uGFXMain() is a function defined by the user in their project that contains the application main code. This is not expected to return and thus gfxInit() will also never return. This is required for some operating systems whose main thread never returns after starting the scheduler.
Its prototype is:
void uGFXMain(void);

Definition at line 216 of file gos_options.h.

#define GFX_OS_HEAP_SIZE   0

How much RAM should uGFX use for the heap when using its own internal heap allocator.

Defaults to 0.

Note
Only used when the internal ugfx heap allocator is used (GFX_USE_OS_RAW32, GFX_USE_OS_ARDUINO, GFX_US_OS_KEIL, GFX_USE_OS_CMSIS)
If 0 then the standard C runtime malloc(), free() and realloc() are used.
If it is non-zero then this is the number of bytes of RAM to use for the heap (gfxAlloc() and gfxFree()). No C runtime routines will be used and a new routine gfxAddHeapBlock() is added allowing the user to add extra memory blocks to the heap.

Definition at line 249 of file gos_options.h.

#define GFX_OS_INIT_NO_WARNING   FALSE

Turn off warnings about initializing the operating system.

Defaults to FALSE

Note
This is only relevant where GOS cannot initialize the operating system automatically or the operating system initialization has been explicitly turned off.

Definition at line 202 of file gos_options.h.

#define GFX_OS_NO_INIT   FALSE

Should uGFX avoid initializing the operating system.

Defaults to FALSE

Note
This is not relevant to all operating systems eg Win32 never initializes the operating system as uGFX runs as an application outside the boot process.
Operating system initialization is not necessarily implemented for all operating systems yet even when it is relevant. These operating systems will display a compile warning reminding you to initialize the operating system in your application code. Note that on these operating systems the demo applications will not work without modification.

Definition at line 192 of file gos_options.h.

#define GFX_OS_UGFXMAIN_STACKSIZE   0

When uGFXMain() is started as a thread, what stack size should be used.

Defaults to 0

Note
uGFXMain() contains the application main code. Some operating systems will start this as a thread. eg FreeRTOS. When it is started as a thread this defines how many bytes should be used for the thread stack.
0 means to use the operating systems default stack size.

Definition at line 227 of file gos_options.h.

#define GFX_USE_OS_ARDUINO   FALSE

Use Arduino.

Defaults to FALSE

Definition at line 84 of file gos_options.h.

#define GFX_USE_OS_CHIBIOS   FALSE

Use ChibiOS.

Defaults to FALSE

Definition at line 28 of file gos_options.h.

#define GFX_USE_OS_CMSIS   FALSE

Use CMSIS RTOS compatible OS.

Defaults to FALSE

Definition at line 91 of file gos_options.h.

#define GFX_USE_OS_CMSIS2   FALSE

Use CMSIS2 RTOS compatible OS.

Defaults to FALSE

Definition at line 98 of file gos_options.h.

#define GFX_USE_OS_ECOS   FALSE

Use a eCos.

Defaults to FALSE

Definition at line 70 of file gos_options.h.

#define GFX_USE_OS_FREERTOS   FALSE

Use FreeRTOS.

Defaults to FALSE

Definition at line 35 of file gos_options.h.

#define GFX_USE_OS_KEIL   FALSE

Use Keil CMSIS 1.x (RTOS, RTX4)

Defaults to FALSE

Definition at line 105 of file gos_options.h.

#define GFX_USE_OS_LINUX   FALSE

Use a linux based system running X11.

Defaults to FALSE

Definition at line 49 of file gos_options.h.

#define GFX_USE_OS_NIOS   FALSE

Use NIOS-II.

Defaults to FALSE

Definition at line 119 of file gos_options.h.

#define GFX_USE_OS_OSX   FALSE

Use a Mac OS-X based system.

Defaults to FALSE

Definition at line 56 of file gos_options.h.

#define GFX_USE_OS_QT   FALSE

Use Qt.

Defaults to FALSE

Definition at line 133 of file gos_options.h.

#define GFX_USE_OS_RAW32   FALSE

Use a Raw 32-bit CPU based system (Bare Metal)

Defaults to FALSE

Definition at line 63 of file gos_options.h.

#define GFX_USE_OS_RAWRTOS   FALSE

Use RAWRTOS.

Defaults to FALSE

Definition at line 77 of file gos_options.h.

#define GFX_USE_OS_RTX5   FALSE

Use Keil RTX5.

Defaults to FALSE

Definition at line 112 of file gos_options.h.

#define GFX_USE_OS_WIN32   FALSE

Use Win32.

Defaults to FALSE

Definition at line 42 of file gos_options.h.

#define GFX_USE_OS_ZEPHYR   FALSE

Use Zephyr.

Defaults to FALSE

Definition at line 126 of file gos_options.h.

Typedef Documentation

typedef void* gfxThreadHandle

A thread handle.

Note
Your operating system will have a proper definition for this.

Definition at line 117 of file gos.h.