2 * Copyright (c) 2015-2016, Texas Instruments Incorporated
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
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.
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.
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.
32 /** ============================================================================
35 * @brief Semaphore module for the RTOS Porting Interface
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).
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
53 * ============================================================================
56 #ifndef ti_dpl_SemaphoreP__include
57 #define ti_dpl_SemaphoreP__include
68 * @brief Status codes for SemaphoreP APIs
70 typedef enum SemaphoreP_Status {
71 /*! API completed successfully */
74 SemaphoreP_FAILURE = -1,
75 /*! API failed because of a timeout */
76 SemaphoreP_TIMEOUT = -2
80 * @brief Wait forever define
82 #define SemaphoreP_WAIT_FOREVER ~(0)
85 * @brief No wait define
87 #define SemaphoreP_NO_WAIT (0)
90 * @brief Opaque client reference to an instance of a SemaphoreP
92 * A SemaphoreP_Handle returned from the ::SemaphoreP_create represents that
93 * instance and is used in the other instance based functions (e.g.
94 * ::SemaphoreP_post or ::SemaphoreP_pend, etc.).
96 typedef void *SemaphoreP_Handle;
99 * @brief Mode of the semaphore
101 typedef enum SemaphoreP_Mode {
102 SemaphoreP_Mode_COUNTING = 0x0,
103 SemaphoreP_Mode_BINARY = 0x1
107 * @brief Basic SemaphoreP Parameters
109 * Structure that contains the parameters are passed into ::SemaphoreP_create
110 * when creating a SemaphoreP instance. The ::SemaphoreP_Params_init function
111 * should be used to initialize the fields to default values before the
112 * application sets the fields manually. The SemaphoreP default parameters are
113 * noted in SemaphoreP_Params_init.
115 typedef struct SemaphoreP_Params {
116 char *name; /*!< Name of the semaphore instance. Memory must
117 persist for the life of the semaphore instance */
118 SemaphoreP_Mode mode; /*!< Mode for the semaphore */
119 uint32_t maxCount; /*!< The max count allowed for counting semaphore */
120 void (*callback)(void); /*!< Callback while pending for semaphore post */
124 * @brief Function to create a semaphore.
126 * @param count Initial count of the semaphore. For binary semaphores,
127 * only values of 0 or 1 are valid.
129 * @param params Pointer to the instance configuration parameters. NULL
130 * denotes to use the default parameters (SemaphoreP default
131 * parameters as noted in ::SemaphoreP_Params_init.
133 * @return A SemaphoreP_Handle on success or a NULL on an error
135 extern SemaphoreP_Handle SemaphoreP_create(unsigned int count,
136 SemaphoreP_Params *params);
139 * @brief Function to delete a semaphore.
141 * @param handle A SemaphoreP_Handle returned from ::SemaphoreP_create
143 * @return Status of the functions
144 * - SemaphoreP_OK: Deleted the semaphore instance
145 * - SemaphoreP_FAILED: Failed to delete the semaphore instance
147 extern SemaphoreP_Status SemaphoreP_delete(SemaphoreP_Handle handle);
150 * @brief Initialize params structure to default values.
152 * The default parameters are:
153 * - mode: SemaphoreP_Mode_COUNTING
156 * @param params Pointer to the instance configuration parameters.
158 extern void SemaphoreP_Params_init(SemaphoreP_Params *params);
161 * @brief Function to pend (wait) on a semaphore.
163 * @param handle A SemaphoreP_Handle returned from ::SemaphoreP_create
165 * @param timeout Timeout (in milliseconds) to wait for the semaphore to
166 * be posted (signalled).
168 * @return Status of the functions
169 * - SemaphoreP_OK: Obtain the semaphore
170 * - SemaphoreP_TIMEOUT: Timed out. Semaphore was not obtained.
171 * - SemaphoreP_FAILED: Non-time out failure.
173 extern SemaphoreP_Status SemaphoreP_pend(SemaphoreP_Handle handle,
177 * @brief Function to post (signal) a semaphore from task of ISR context.
179 * @param handle A SemaphoreP_Handle returned from ::SemaphoreP_create
181 * @return Status of the functions
182 * - SemaphoreP_OK: Released the semaphore
183 * - SemaphoreP_FAILED: Failed to post the semaphore
185 extern SemaphoreP_Status SemaphoreP_post(SemaphoreP_Handle handle);
188 * @brief Function to post (signal) a semaphore from an ClockP function.
190 * @param handle A SemaphoreP_Handle returned from ::SemaphoreP_create
192 * @return Status of the functions
193 * - SemaphoreP_OK: Released the semaphore
194 * - SemaphoreP_FAILED: Failed to post the semaphore
196 extern SemaphoreP_Status SemaphoreP_postFromClock(SemaphoreP_Handle handle);
202 #endif /* ti_dpl_SemaphoreP__include */