equeue_platform.h

00001 
00002 /** \addtogroup events */
00003 /** @{*/
00004 /*
00005  * System specific implementation
00006  *
00007  * Copyright (c) 2016 Christopher Haster
00008  *
00009  * Licensed under the Apache License, Version 2.0 (the "License");
00010  * you may not use this file except in compliance with the License.
00011  * You may obtain a copy of the License at
00012  *
00013  *     http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  * Unless required by applicable law or agreed to in writing, software
00016  * distributed under the License is distributed on an "AS IS" BASIS,
00017  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  * See the License for the specific language governing permissions and
00019  * limitations under the License.
00020  */
00021 #ifndef EQUEUE_PLATFORM_H
00022 #define EQUEUE_PLATFORM_H
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 #include <stdbool.h>
00029 
00030 // Currently supported platforms
00031 //
00032 // Uncomment to select a supported platform or reimplement this file
00033 // for a specific target.
00034 //#define EQUEUE_PLATFORM_POSIX
00035 //#define EQUEUE_PLATFORM_MBED
00036 
00037 // Try to infer a platform if none was manually selected
00038 #if !defined(EQUEUE_PLATFORM_POSIX)     \
00039  && !defined(EQUEUE_PLATFORM_MBED)
00040 #if defined(__unix__)
00041 #define EQUEUE_PLATFORM_POSIX
00042 #elif defined(__MBED__)
00043 #define EQUEUE_PLATFORM_MBED
00044 #else
00045 #warning "Unknown platform! Please update equeue_platform.h"
00046 #endif
00047 #endif
00048 
00049 // Platform includes
00050 #if defined(EQUEUE_PLATFORM_POSIX)
00051 #include <pthread.h>
00052 #endif
00053 
00054 
00055 // Platform millisecond counter
00056 //
00057 // Return a tick that represents the number of milliseconds that have passed
00058 // since an arbitrary point in time. The granularity does not need to be at
00059 // the millisecond level, however the accuracy of the equeue library is
00060 // limited by the accuracy of this tick.
00061 //
00062 // Must intentionally overflow to 0 after 2^32-1
00063 unsigned equeue_tick(void);
00064 
00065 
00066 // Platform mutex type
00067 //
00068 // The equeue library requires at minimum a non-recursive mutex that is
00069 // safe in interrupt contexts. The mutex section is help for a bounded
00070 // amount of time, so simply disabling interrupts is acceptable
00071 //
00072 // If irq safety is not required, a regular blocking mutex can be used.
00073 #if defined(EQUEUE_PLATFORM_POSIX)
00074 typedef pthread_mutex_t equeue_mutex_t;
00075 #elif defined(EQUEUE_PLATFORM_WINDOWS)
00076 typedef CRITICAL_SECTION equeue_mutex_t;
00077 #elif defined(EQUEUE_PLATFORM_MBED)
00078 typedef unsigned equeue_mutex_t;
00079 #elif defined(EQUEUE_PLATFORM_FREERTOS)
00080 typedef UBaseType_t equeue_mutex_t;
00081 #endif
00082 
00083 // Platform mutex operations
00084 //
00085 // The equeue_mutex_create and equeue_mutex_destroy manage the lifetime
00086 // of the mutex. On error, equeue_mutex_create should return a negative
00087 // error code.
00088 //
00089 // The equeue_mutex_lock and equeue_mutex_unlock lock and unlock the
00090 // underlying mutex.
00091 int equeue_mutex_create(equeue_mutex_t *mutex);
00092 void equeue_mutex_destroy(equeue_mutex_t *mutex);
00093 void equeue_mutex_lock(equeue_mutex_t *mutex);
00094 void equeue_mutex_unlock(equeue_mutex_t *mutex);
00095 
00096 
00097 // Platform semaphore type
00098 //
00099 // The equeue library requires a binary semaphore type that can be safely
00100 // signaled from interrupt contexts and from inside a equeue_mutex section.
00101 //
00102 // The equeue_signal_wait is relied upon by the equeue library to sleep the
00103 // processor between events. Spurious wakeups have no negative-effects.
00104 //
00105 // A counting semaphore will also work, however may cause the event queue
00106 // dispatch loop to run unnecessarily. For that matter, equeue_signal_wait
00107 // may even be implemented as a single return statement.
00108 #if defined(EQUEUE_PLATFORM_POSIX)
00109 typedef struct equeue_sema {
00110     pthread_mutex_t mutex;
00111     pthread_cond_t cond;
00112     bool signal;
00113 } equeue_sema_t;
00114 #elif defined(EQUEUE_PLATFORM_MBED) && defined(MBED_CONF_RTOS_PRESENT)
00115 typedef unsigned equeue_sema_t[8];
00116 #elif defined(EQUEUE_PLATFORM_MBED)
00117 typedef volatile int equeue_sema_t;
00118 #endif
00119 
00120 // Platform semaphore operations
00121 //
00122 // The equeue_sema_create and equeue_sema_destroy manage the lifetime
00123 // of the semaphore. On error, equeue_sema_create should return a negative
00124 // error code.
00125 //
00126 // The equeue_sema_signal marks a semaphore as signalled such that the next
00127 // equeue_sema_wait will return true.
00128 //
00129 // The equeue_sema_wait waits for a semaphore to be signalled or returns
00130 // immediately if equeue_sema_signal had been called since the last
00131 // equeue_sema_wait. The equeue_sema_wait returns true if it detected that
00132 // equeue_sema_signal had been called.
00133 int equeue_sema_create(equeue_sema_t *sema);
00134 void equeue_sema_destroy(equeue_sema_t *sema);
00135 void equeue_sema_signal(equeue_sema_t *sema);
00136 bool equeue_sema_wait(equeue_sema_t *sema, int ms);
00137 
00138 
00139 #ifdef __cplusplus
00140 }
00141 #endif
00142 
00143 #endif
00144 
00145 /** @}*/