equeue_platform.h

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