1 /* 2 * Copyright (c) 2015-2019, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 /** ============================================================================ 33 * @file SemaphoreP.h 34 * 35 * @brief Semaphore module for the RTOS Porting Interface 36 * 37 * Semaphores can be counting semaphores or binary semaphores. Counting 38 * semaphores keep track of the number of times the semaphore has been posted 39 * with post functions. This is useful, for example, if you have a group of 40 * resources that are shared between tasks. Such tasks might call pend() to see 41 * if a resource is available before using one. A count of zero for a counting 42 * semaphore denotes that it is not available. A positive count denotes 43 * how many times a SemaphoreP_pend can be called before it is blocked (or 44 * returns SemaphoreP_TIMEOUT). 45 * 46 * Binary semaphores can have only two states: available (count = 1) and 47 * unavailable (count = 0). They can be used to share a single resource 48 * between tasks. They can also be used for a basic signalling mechanism, where 49 * the semaphore can be posted multiple times. Binary semaphores do not keep 50 * track of the count; they simply track whether the semaphore has been posted 51 * or not. 52 * 53 * ============================================================================ 54 */ 55 56 #ifndef ti_dpl_SemaphoreP__include 57 #define ti_dpl_SemaphoreP__include 58 59 #include <stdint.h> 60 #include <stdbool.h> 61 #include <stddef.h> 62 63 #ifdef __cplusplus 64 extern "C" { 65 #endif 66 67 /*! 68 * @brief Number of bytes greater than or equal to the size of any RTOS 69 * SemaphoreP object. 70 * 71 * nortos: 16 72 * SysBIOS: 28 73 */ 74 #define SemaphoreP_STRUCT_SIZE (28) 75 76 /*! 77 * @brief SemaphoreP structure. 78 * 79 * Opaque structure that should be large enough to hold any of the 80 * RTOS specific SemaphoreP objects. 81 */ 82 typedef union SemaphoreP_Struct { 83 uint32_t dummy; /*!< Align object */ 84 char data[SemaphoreP_STRUCT_SIZE]; 85 } SemaphoreP_Struct; 86 87 /*! 88 * @brief Wait forever define 89 */ 90 #define SemaphoreP_WAIT_FOREVER ~(0) 91 92 /*! 93 * @brief No wait define 94 */ 95 #define SemaphoreP_NO_WAIT (0) 96 97 /*! 98 * @brief Status codes for SemaphoreP APIs (for backwards compatibility) 99 */ 100 typedef enum { 101 /*! API completed successfully */ 102 SemaphoreP_OK = 0, 103 /*! API failed because of a timeout */ 104 SemaphoreP_TIMEOUT = -1 105 } SemaphoreP_Status; 106 107 /*! 108 * @brief Opaque client reference to an instance of a SemaphoreP 109 * 110 * A SemaphoreP_Handle returned from the ::SemaphoreP_create represents that 111 * instance and is used in the other instance based functions (e.g. 112 * ::SemaphoreP_post or ::SemaphoreP_pend, etc.). 113 */ 114 typedef void *SemaphoreP_Handle; 115 116 /*! 117 * @brief Mode of the semaphore 118 */ 119 typedef enum { 120 SemaphoreP_Mode_COUNTING = 0x0, 121 SemaphoreP_Mode_BINARY = 0x1 122 } SemaphoreP_Mode; 123 124 /*! 125 * @brief Basic SemaphoreP Parameters 126 * 127 * Structure that contains the parameters are passed into ::SemaphoreP_create 128 * when creating a SemaphoreP instance. The ::SemaphoreP_Params_init function 129 * should be used to initialize the fields to default values before the 130 * application sets the fields manually. The SemaphoreP default parameters are 131 * noted in SemaphoreP_Params_init. 132 */ 133 typedef struct { 134 SemaphoreP_Mode mode; /*!< Mode for the semaphore */ 135 void (*callback)(void); /*!< Callback while pending for semaphore post */ 136 } SemaphoreP_Params; 137 138 /*! 139 * @brief Default SemaphoreP instance parameters 140 * 141 * SemaphoreP_defaultParams represents the default parameters that are 142 * used when creating or constructing a SemaphoreP instance. 143 * SemaphoreP_Params_init() will use the contents of this structure for 144 * initializing the SemaphoreP_Params instance. 145 * 146 * SemaphoreP_defaultParams is exposed to the application for the purpose 147 * of allowing the application to change the default parameters for all 148 * SemaphoreP instances created thereafter. The main intent for allowing 149 * the default parameters to be changed is for setting a semaphore's 150 * callback function to Power_idleFunc(), so that the SOC can enter low 151 * power mode when pending on a semaphore. 152 */ 153 extern SemaphoreP_Params SemaphoreP_defaultParams; 154 155 156 /* 157 * SemaphoreP construct APIs can only be used if one of the OS's 158 * is defined. For FreeRTOS, configSUPPORT_STATIC_ALLOCATION also 159 * has to be set to 1 in FreeRTOSConfig.h. 160 */ 161 extern SemaphoreP_Handle SemaphoreP_construct(SemaphoreP_Struct *handle, 162 unsigned int count, SemaphoreP_Params *params); 163 164 extern SemaphoreP_Handle SemaphoreP_constructBinary(SemaphoreP_Struct *handle, 165 unsigned int count); 166 167 extern void SemaphoreP_destruct(SemaphoreP_Struct *semP); 168 169 /*! 170 * @brief Function to create a semaphore. 171 * 172 * @param count Initial count of the semaphore. For binary semaphores, 173 * only values of 0 or 1 are valid. 174 * 175 * @param params Pointer to the instance configuration parameters. NULL 176 * denotes to use the default parameters (SemaphoreP default 177 * parameters as noted in ::SemaphoreP_Params_init. 178 * 179 * @return A SemaphoreP_Handle on success or a NULL on an error 180 */ 181 extern SemaphoreP_Handle SemaphoreP_create(unsigned int count, 182 SemaphoreP_Params *params); 183 184 /*! 185 * @brief Function to create a binary semaphore. 186 * 187 * This can be used instead of SemaphoreP_create() to create a binary 188 * semaphore. 189 * 190 * @param count Initial count of the binary semaphore. Only values 191 * of 0 or 1 are valid. 192 * 193 * @return A SemaphoreP_Handle on success or a NULL on an error 194 */ 195 extern SemaphoreP_Handle SemaphoreP_createBinary(unsigned int count); 196 197 /*! 198 * @brief Function to create a binary semaphore. 199 * 200 * This can be used instead of SemaphoreP_create() to create a binary 201 * semaphore. 202 * 203 * @param count Initial count of the binary semaphore. Only values 204 * of 0 or 1 are valid. 205 * 206 * @return A SemaphoreP_Handle on success or a NULL on an error 207 */ 208 extern SemaphoreP_Handle SemaphoreP_createBinaryCallback(unsigned int count, 209 void (*callback)(void)); 210 211 /*! 212 * @brief Function to delete a semaphore. 213 * 214 * @param handle A SemaphoreP_Handle returned from ::SemaphoreP_create 215 */ 216 extern void SemaphoreP_delete(SemaphoreP_Handle handle); 217 218 /*! 219 * @brief Initialize params structure to default values. 220 * 221 * The default parameters are: 222 * - mode: SemaphoreP_Mode_COUNTING 223 * - name: NULL 224 * 225 * @param params Pointer to the instance configuration parameters. 226 */ 227 extern void SemaphoreP_Params_init(SemaphoreP_Params *params); 228 229 /*! 230 * @brief Function to pend (wait) on a semaphore. 231 * 232 * @param handle A SemaphoreP_Handle returned from ::SemaphoreP_create 233 * 234 * @param timeout Timeout (in ClockP ticks) to wait for the semaphore to 235 * be posted (signalled). 236 * 237 * @return Status of the functions 238 * - SemaphoreP_OK: Obtained the semaphore 239 * - SemaphoreP_TIMEOUT: Timed out. Semaphore was not obtained. 240 */ 241 extern SemaphoreP_Status SemaphoreP_pend(SemaphoreP_Handle handle, 242 uint32_t timeout); 243 244 /*! 245 * @brief Function to post (signal) a semaphore from task of ISR context. 246 * 247 * @param handle A SemaphoreP_Handle returned from ::SemaphoreP_create 248 */ 249 extern void SemaphoreP_post(SemaphoreP_Handle handle); 250 251 #ifdef __cplusplus 252 } 253 #endif 254 255 #endif /* ti_dpl_SemaphoreP__include */ 256
