aboutsummaryrefslogtreecommitdiffstats
path: root/src/gos/gos.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/gos/gos.h')
-rw-r--r--src/gos/gos.h470
1 files changed, 470 insertions, 0 deletions
diff --git a/src/gos/gos.h b/src/gos/gos.h
new file mode 100644
index 00000000..f1def55a
--- /dev/null
+++ b/src/gos/gos.h
@@ -0,0 +1,470 @@
+/*
+ * This file is subject to the terms of the GFX License. If a copy of
+ * the license was not distributed with this file, you can obtain one at:
+ *
+ * http://ugfx.org/license.html
+ */
+
+/**
+ * @file src/gos/gos.h
+ * @brief GOS - Operating System Support header file
+ *
+ * @addtogroup GOS
+ *
+ * @brief 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.
+ * @{
+ */
+
+#ifndef _GOS_H
+#define _GOS_H
+
+#if defined(__DOXYGEN__)
+ /*===========================================================================*/
+ /* Type definitions */
+ /*===========================================================================*/
+
+ /**
+ * @name 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;
+ /** @} */
+
+ /**
+ * @name 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;
+ /** @} */
+
+ /**
+ * @brief Declare a thread function
+ *
+ * @param[in] fnName The name of the function
+ * @param[in] param A custom parameter that is passed to the function
+ */
+ #define DECLARE_THREAD_FUNCTION(fnName, param) threadreturn_t fnName(void *param)
+
+ /**
+ * @brief Declare a thread stack
+ *
+ * @param[in] name The name of the stack
+ * @param[in] sz The size of the stack
+ */
+ #define DECLARE_THREAD_STACK(name, sz) uint8_t name[sz];
+
+ /**
+ * @name 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
+ /** @} */
+
+ /**
+ * @brief A semaphore
+ * @note Your operating system will have a proper definition for this structure
+ */
+ typedef struct {} gfxSem;
+
+ /**
+ * @brief A mutex
+ * @note Your operating system will have a proper definition for this structure
+ */
+ typedef struct {} gfxMutex;
+
+ /**
+ * @brief A thread handle
+ * @note Your operating system will have a proper definition for this.
+ */
+ typedef void * gfxThreadHandle;
+
+ /*===========================================================================*/
+ /* Function declarations. */
+ /*===========================================================================*/
+
+ #ifdef __cplusplus
+ extern "C" {
+ #endif
+
+ /**
+ * @brief Halt the GFX application due to an error.
+ *
+ * @param[in] msg An optional debug message to show (Can be NULL)
+ *
+ * @api
+ */
+ void gfxHalt(const char *msg);
+
+ /**
+ * @brief Exit the GFX application.
+ *
+ * @api
+ */
+ void gfxExit(void);
+
+ /**
+ * @brief Allocate memory
+ * @return A pointer to the memory allocated or NULL if there is no more memory available
+ *
+ * @param[in] sz The size in bytes of the area to allocate
+ *
+ * @api
+ */
+ void *gfxAlloc(size_t sz);
+
+ /**
+ * @brief Re-allocate memory
+ * @return A pointer to the new memory area or NULL if there is no more memory available
+ *
+ * @param[in] ptr The old memory area to be increased/decreased in size
+ * @param[in] oldsz The size in bytes of the old memory area
+ * @param[in] newsz The 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.
+ * @note 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.
+ * @note If there is insufficient memory to create the new memory region, NULL is returned and the
+ * old memory area is left unchanged.
+ *
+ * @api
+ */
+ void *gfxRealloc(void *ptr, size_t oldsz, size_t newsz);
+
+ /**
+ * @brief Free memory
+ *
+ * @param[in] ptr The memory to free
+ *
+ * @api
+ */
+ void gfxFree(void *ptr);
+
+ /**
+ * @brief Yield the current thread
+ * @details Give up the rest of the current time slice for this thread in order to give other threads
+ * a chance to run.
+ *
+ * @api
+ */
+ void gfxYield(void);
+
+ /**
+ * @brief Put the current thread to sleep for the specified period in milliseconds
+ *
+ * @param[in] ms The number milliseconds to sleep
+ *
+ * @note Specifying TIME_IMMEDIATE will yield the current thread but return
+ * on the next time slice.
+ * @note Specifying TIME_INFINITE will sleep forever.
+ *
+ * @api
+ */
+ void gfxSleepMilliseconds(delaytime_t ms);
+
+ /**
+ * @brief Put the current thread to sleep for the specified period in microseconds
+ *
+ * @param[in] us The number microseconds to sleep
+ *
+ * @note Specifying TIME_IMMEDIATE will return immediately (no sleeping)
+ * @note Specifying TIME_INFINITE will sleep forever.
+ *
+ * @api
+ */
+ void gfxSleepMicroseconds(delaytime_t us);
+
+ /**
+ * @brief Get the current operating system tick time
+ * @return The current tick time
+ *
+ * @note A "tick" is an arbitrary period of time that the operating
+ * system uses to mark time.
+ * @note The absolute value of this call is relatively meaningless. Its usefulness
+ * is in calculating periods between two calls to this function.
+ * @note 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
+ *
+ * @api
+ */
+ systemticks_t gfxSystemTicks(void);
+
+ /**
+ * @brief Convert a given number of millseconds to a number of operating system ticks
+ * @return The period in system ticks.
+ *
+ * @note A "tick" is an arbitrary period of time that the operating
+ * system uses to mark time.
+ *
+ * @param[in] ms The number of millseconds
+ *
+ * @api
+ */
+ systemticks_t gfxMillisecondsToTicks(delaytime_t ms);
+
+ /**
+ * @brief 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.
+ * @note 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.
+ * @note While locked only interrupt level (iclass) GFX routines may be called.
+ *
+ * @api
+ */
+ void gfxSystemLock(void);
+
+ /**
+ * @brief Unlock the operating system previous locked by gfxSystemLock()
+ *
+ * @api
+ */
+ void gfxSystemUnlock(void);
+
+ /**
+ * @brief Initialise a mutex to protect a region of code from other threads.
+ *
+ * @param[in] pmutex A 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.
+ *
+ * @api
+ */
+ void gfxMutexInit(gfxMutex *pmutex);
+
+ /**
+ * @brief Destroy a Mutex.
+ *
+ * @param[in] pmutex A pointer to the mutex
+ *
+ * @api
+ */
+ void gfxMutexDestroy(gfxMutex *pmutex);
+
+ /**
+ * @brief Enter the critical code region protected by the mutex.
+ * @details Blocks until there is no other thread in the critical region.
+ *
+ * @param[in] pmutex A pointer to the mutex
+ *
+ * @api
+ */
+ void gfxMutexEnter(gfxMutex *pmutex);
+
+ /**
+ * @brief Exit the critical code region protected by the mutex.
+ * @details May cause another thread waiting on the mutex to now be placed into the run queue.
+ *
+ * @param[in] pmutex A pointer to the mutex
+ *
+ * @api
+ */
+ void gfxMutexExit(gfxMutex *pmutex);
+
+ /**
+ * @brief Initialise a Counted Semaphore
+ *
+ * @param[in] psem A pointer to the semaphore
+ * @param[in] val The initial value of the semaphore
+ * @param[in] limit The 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.
+ *
+ * @api
+ */
+ void gfxSemInit(gfxSem *psem, semcount_t val, semcount_t limit);
+
+ /**
+ * @brief Destroy a Counted Semaphore
+ *
+ * @param[in] psem A pointer to the semaphore
+ *
+ * @note Any threads waiting on the semaphore will be released
+ *
+ * @api
+ */
+ void gfxSemDestroy(gfxSem *psem);
+
+ /**
+ * @brief Wait on a semaphore
+ * @details The semaphore counter is decreased and if the result becomes negative the thread waits for it to become
+ * non-negative again
+ * @return FALSE if the wait timeout occurred otherwise TRUE
+ *
+ * @param[in] psem A pointer to the semaphore
+ * @param[in] ms The maximum time to wait for the semaphore
+ *
+ * @api
+ */
+ bool_t gfxSemWait(gfxSem *psem, delaytime_t ms);
+
+ /**
+ * @brief Test if a wait on a semaphore can be satisfied immediately
+ * @details Equivalent to @p gfxSemWait(psem, TIME_IMMEDIATE) except it can be called at interrupt level
+ * @return FALSE if the wait would occur occurred otherwise TRUE
+ *
+ * @param[in] psem A pointer to the semaphore
+ *
+ * @iclass
+ * @api
+ */
+ bool_t gfxSemWaitI(gfxSem *psem);
+
+ /**
+ * @brief Signal a semaphore
+ * @details 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.
+ *
+ * @param[in] psem A pointer to the semaphore
+ *
+ * @api
+ */
+ void gfxSemSignal(gfxSem *psem);
+
+ /**
+ * @brief Signal a semaphore
+ * @details 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.
+ *
+ * @param[in] psem A pointer to the semaphore
+ *
+ * @iclass
+ * @api
+ */
+ void gfxSemSignalI(gfxSem *psem);
+
+ /**
+ * @brief Get the current semaphore count
+ * @return The current semaphore count
+ *
+ * @param[in] psem A pointer to the semaphore
+ *
+ * @api
+ */
+ semcount_t gfxSemCounter(gfxSem *psem);
+
+ /**
+ * @brief Get the current semaphore count
+ * @return The current semaphore count
+ *
+ * @param[in] psem A pointer to the semaphore
+ *
+ * @iclass
+ * @api
+ */
+ semcount_t gfxSemCounterI(gfxSem *psem);
+
+ /**
+ * @brief Start a new thread.
+ * @return Returns a thread handle if the thread was started, NULL on an error
+ *
+ * @param[in] stackarea A pointer to the area for the new threads stack or NULL to dynamically allocate it
+ * @param[in] stacksz The size of the thread stack. 0 means the default operating system size although this
+ * is only valid when stackarea is dynamically allocated.
+ * @param[in] prio The priority of the new thread
+ * @param[in] fn The function the new thread will run
+ * @param[in] param A parameter to pass the thread function.
+ *
+ * @api
+ */
+ gfxThreadHandle gfxThreadCreate(void *stackarea, size_t stacksz, threadpriority_t prio, DECLARE_THREAD_FUNCTION((*fn),p), void *param);
+
+ /**
+ * @brief Wait for a thread to finish.
+ * @return Returns the thread exit code.
+ *
+ * @param[in] thread The Thread Handle
+ *
+ * @note This will also close the thread handle as it is no longer useful
+ * once the thread has ended.
+ * @api
+ */
+ threadreturn_t gfxThreadWait(gfxThreadHandle thread);
+
+ /**
+ * @brief Get the current thread handle.
+ * @return A thread handle
+ *
+ * @api
+ */
+ gfxThreadHandle gfxThreadMe(void);
+
+ /**
+ * @brief Close the thread handle.
+ *
+ * @param[in] thread The Thread Handle
+ *
+ * @note This does not affect the thread, it just closes our handle to the thread.
+ *
+ * @api
+ */
+ void gfxThreadClose(gfxThreadHandle thread);
+
+ #ifdef __cplusplus
+ }
+ #endif
+
+/**
+ * All the above was just for the doxygen documentation. All the implementation of the above
+ * (without any of the documentation overheads) is in the files below.
+ */
+#elif GFX_USE_OS_RAWRTOS
+ #include "src/gos/gos_rawrtos.h"
+#elif GFX_USE_OS_CHIBIOS
+ #include "src/gos/gos_chibios.h"
+#elif GFX_USE_OS_FREERTOS
+ #include "src/gos/gos_freertos.h"
+#elif GFX_USE_OS_WIN32
+ #include "src/gos/gos_win32.h"
+#elif GFX_USE_OS_LINUX
+ #include "src/gos/gos_linux.h"
+#elif GFX_USE_OS_OSX
+ #include "src/gos/gos_osx.h"
+#elif GFX_USE_OS_RAW32
+ #include "src/gos/gos_raw32.h"
+#elif GFX_USE_OS_ECOS
+ #include "src/gos/gos_ecos.h"
+#else
+ #error "Your operating system is not supported yet"
+#endif
+
+#endif /* _GOS_H */
+/** @} */