diff options
author | inmarket <andrewh@inmarket.com.au> | 2013-05-25 01:26:52 +1000 |
---|---|---|
committer | inmarket <andrewh@inmarket.com.au> | 2013-05-25 01:26:52 +1000 |
commit | 7fbfde42aabbcd30cffba2fba35158236c0a6c6c (patch) | |
tree | e85c90a4f21974b706315d64209021e0b2bde764 /include/gos/gos.h | |
parent | 42006a67b5ccfd86f30d8a91cc474681c437eaf6 (diff) | |
download | uGFX-7fbfde42aabbcd30cffba2fba35158236c0a6c6c.tar.gz uGFX-7fbfde42aabbcd30cffba2fba35158236c0a6c6c.tar.bz2 uGFX-7fbfde42aabbcd30cffba2fba35158236c0a6c6c.zip |
GOS module, for operating system independance
GMISC fast floating point trig
GMISC fast fixed point trig
Diffstat (limited to 'include/gos/gos.h')
-rw-r--r-- | include/gos/gos.h | 483 |
1 files changed, 483 insertions, 0 deletions
diff --git a/include/gos/gos.h b/include/gos/gos.h new file mode 100644 index 00000000..04799540 --- /dev/null +++ b/include/gos/gos.h @@ -0,0 +1,483 @@ +/* + ChibiOS/GFX - Copyright (C) 2012, 2013 + Joel Bodenmann aka Tectu <joel@unormal.org> + + This file is part of ChibiOS/GFX. + + ChibiOS/GFX is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/GFX is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. +*/ +/** + * @file include/gos/gos.h + * @brief GOS - Operating System Support header file. + * + * @addtogroup GOS + * @brief GOS provides the operating system interface with the GFX library. + * @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 */ + /*===========================================================================*/ + + /** + * @brief A function for a new thread to execute. + */ + typedef threadreturn_t (*gfxThreadFunction)(void *param); + + /** + * @brief 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; + /** + * @} + * + * @brief 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 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)-1) + #define LOW_PRIORITY 0 + #define NORMAL_PRIORITY 1 + #define HIGH_PRIORITY 2 + #define DECLARESTACK(name, sz) uint8_t name[sz]; + /* @} */ + + /** + * @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 queue + * @note Your operating system will have a proper definition for this structure + */ + typedef struct {} gfxQueue; + + /** + * @brief A queue item + * @note Your operating system will have a proper definition for this structure + */ + typedef struct {} gfxQueueItem; + + /*===========================================================================*/ + /* 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 Free memory + * + * @param[in] ptr The memory to free + * + * @api + */ + void gfxFree(void *ptr); + + /** + * @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] ms 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 ms); + + /** + * @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 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 maxmimum time to wait for the semaphore + * + * @api + */ + bool_t gfxSemWait(gfxSem *psem, delaytime_t ms); + + /** + * @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 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 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 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 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 queue. + * + * @param[in] pqueue A pointer to the queue + * + * @note Whilst queues are normally FIFO, a GFX queue also supports push and pop operations. + * A pop operation is the same as normal get from the queue but a push places the item + * at the head of the queue instead of the tail (as a put would). + * + * @api + */ + void gfxQueueInit(gfxQueue *pqueue); + + /** + * @brief Get an item from the head of the queue. + * @return NULL if the timeout expires before an item is available + * + * @param[in] pqueue A pointer to the queue + * @param[in] ms The maxmimum time to wait for an item + * + * @api + */ + gfxQueueItem * gfxQueueGet(gfxQueue *pqueue, delaytime_t ms); + + /** + * @brief Put an item on the end of the queue. + * @return FALSE on timeout, otherwise TRUE + * + * @param[in] pqueue A pointer to the queue + * @param[in] pitem A pointer to the queue item + * @param[in] ms The maxmimum time to wait for an item to be removed from the queue + * + * @note Use a delay time of TIME_IMMEDIATE if you don't want to wait until the + * item is removed from the queue + * + * @api + */ + bool_t gfxQueuePut(gfxQueue *pqueue, gfxQueueItem *pitem, delaytime_t ms); + + /** + * @brief Pop an item from the head of the queue. + * @return NULL if there are no more items on the queue + * + * @param[in] pqueue A pointer to the queue + * + * @api + */ + #define gfxQueuePop(pqueue, ms) gfxQueueGet(pqueue, ms) + + /** + * @brief Push an item into the start of the queue. + * @return FALSE on timeout, otherwise TRUE + * + * @param[in] pqueue A pointer to the queue + * @param[in] pitem A pointer to the queue item + * @param[in] ms The maxmimum time to wait for an item to be popped + * + * @note Use a delay time of TIME_IMMEDIATE if you don't want to wait until the + * item is removed from the queue + * + * @api + */ + bool_t gfxQueuePush(gfxQueue *pqueue, gfxQueueItem *pitem, delaytime_t ms); + + /** + * @brief Remove an item from the queue. + * @note Removes the specified item from the queue whereever it is in the queue + * + * @param[in] pqueue A pointer to the queue + * @param[in] pitem A pointer to the queue item + * + * @note If the item isn't in the queue the routine just returns. + * + * @api + */ + void gfxQueueRemove(gfxQueue *pqueue, gfxQueueItem *pitem); + + /** + * @brief Is the queue empty? + * @return TRUE if the queue is empty + * + * @param[in] pqueue A pointer to the queue + * + * @api + */ + bool_t gfxQueueIsEmpty(gfxQueue *pqueue); + + /** + * @brief Is an item in the queue? + * @return TRUE if the item is in the queue? + * + * @param[in] pqueue A pointer to the queue + * @param[in] pitem A pointer to the queue item + * + * @note This operation may be expensive. + * + * @api + */ + bool_t gfxQueueIsIn(gfxQueue *pqueue, gfxQueueItem *pitem); + + /** + * @brief Start a new thread. + * @return Return TRUE if the thread was started, FALSE 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 + */ + bool_t gfxCreateThread(void *stackarea, size_t stacksz, threadpriority_t prio, gfxThreadFunction fn, void *param); + + #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_CHIBIOS + #include "gos/chibios.h" +#elif GFX_USE_OS_WIN32 + #include "gos/win32.h" +#elif GFX_USE_OS_POSIX + #include "gos/posix.h" +#else + #error "Your operating system is not supported yet" +#endif + +#endif /* _GOS_H */ +/** @} */ |