1 /**
2 * @file rm_osal.h
3 *
4 * @brief
5 * This is the sample OS Adaptation layer which is used by the Resource
6 * Manager. The OSAL layer can be ported in either of the following
7 * manners to a native OS:
8 *
9 * <b> Approach 1: </b>
10 * @n Use Prebuilt Libraries
11 * - Ensure that the provide an implementation of all
12 * Osal_XXX API for their native OS.
13 * - Link the prebuilt libraries with their application.
14 * - Refer to the "example" directory for an example of this
15 * @n <b> Pros: </b>
16 * - Customers can reuse prebuilt TI provided libraries
17 * @n <b> Cons: </b>
18 * - Level of indirection in the API to get to the actual OS call
19 *
20 * <b> Approach 2: </b>
21 * @n Rebuilt Library
22 * - Create a copy of this file and modify it to directly
23 * inline the native OS calls
24 * - Rebuild the RM low level drivver library; ensure that the Include
25 * path points to the directory where the copy of this file
26 * has been provided.
27 * - Please refer to the "test" directory for an example of this
28 * @n <b> Pros: </b>
29 * - Optimizations can be done to remove the level of indirection
30 * @n <b> Cons: </b>
31 * - RM LLD Libraries need to be rebuilt by the customer.
32 *
33 * \par
34 * NOTE:
35 * (C) Copyright 2012-2013 Texas Instruments, Inc.
36 *
37 * Redistribution and use in source and binary forms, with or without
38 * modification, are permitted provided that the following conditions
39 * are met:
40 *
41 * Redistributions of source code must retain the above copyright
42 * notice, this list of conditions and the following disclaimer.
43 *
44 * Redistributions in binary form must reproduce the above copyright
45 * notice, this list of conditions and the following disclaimer in the
46 * documentation and/or other materials provided with the
47 * distribution.
48 *
49 * Neither the name of Texas Instruments Incorporated nor the names of
50 * its contributors may be used to endorse or promote products derived
51 * from this software without specific prior written permission.
52 *
53 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
54 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
55 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
56 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
57 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
58 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
59 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
60 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
61 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
62 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
63 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
64 *
65 * \par
66 */
67 #ifndef RM_OSAL_H_
68 #define RM_OSAL_H_
70 /** @addtogroup RM_OSAL_API
71 @{
72 */
74 /**********************************************************************
75 ************************* Extern Declarations ************************
76 **********************************************************************/
78 extern void *Osal_rmMalloc (uint32_t num_bytes);
79 extern void Osal_rmFree (void *ptr, uint32_t size);
80 extern void *Osal_rmCsEnter (void);
81 extern void Osal_rmCsExit (void *CsHandle);
82 extern void *Osal_rmMtCsEnter (void *mtSemObj);
83 extern void Osal_rmMtCsExit (void *mtSemObj, void *CsHandle);
84 extern void Osal_rmBeginMemAccess (void *ptr, uint32_t size);
85 extern void Osal_rmEndMemAccess (void *ptr, uint32_t size);
86 extern void *Osal_rmTaskBlockCreate (void);
87 extern void Osal_rmTaskBlock (void *handle);
88 extern void Osal_rmTaskUnblock (void *handle);
89 extern void Osal_rmTaskBlockDelete (void *handle);
90 extern void Osal_rmLog (char *fmt, ... );
92 /**
93 * @brief The macro is used by RM to allocate memory of specified
94 * size
95 *
96 * <b> Prototype: </b>
97 * The following is the C prototype for the expected OSAL API.
98 *
99 * @verbatim
100 void* Osal_rmMalloc (uint32_t numBytes)
101 @endverbatim
102 *
103 * <b> Parameter </b>
104 * @n Number of bytes to be allocated
105 *
106 * <b> Return Value </b>
107 * @n Pointer to the allocated block size
108 */
109 #define Rm_osalMalloc Osal_rmMalloc
111 /**
112 * @brief The macro is used by RM to free a allocated block of
113 * memory
114 *
115 * <b> Prototype: </b>
116 * The following is the C prototype for the expected OSAL API.
117 *
118 * @verbatim
119 void Osal_rmFree (void *ptr, uint32_t size)
120 @endverbatim
121 *
122 * <b> Parameter </b>
123 * @n Pointer to the block of memory to be cleaned up.
124 * @n Size of the allocated memory which is being freed.
125 *
126 * <b> Return Value </b>
127 * @n Not applicable.
128 */
129 #define Rm_osalFree Osal_rmFree
131 /**
132 * @brief The function is used to enter a critical section.
133 * Function protects against
134 *
135 * access from multiple cores
136 * and
137 * access from multiple threads on single core
138 *
139 * <b> Prototype: </b>
140 * The following is the C prototype for the expected OSAL API.
141 *
142 * @verbatim
143 void *Osal_rmCsEnter (void)
144 @endverbatim
145 *
146 * <b> Parameter </b>
147 * @n Not applicable.
148 *
149 * <b> Return Value </b>
150 * @n Handle used to lock critical section
151 */
152 #define Rm_osalCsEnter Osal_rmCsEnter
154 /**
155 * @brief The function is used to exit a critical section
156 * protected using Osal_rmCsEnter() API.
157 *
158 * <b> Prototype: </b>
159 * The following is the C prototype for the expected OSAL API.
160 *
161 * @verbatim
162 void Osal_rmCsExit (void *CsHandle)
163 @endverbatim
164 *
165 * <b> Parameter </b>
166 * @n Handle for unlocking critical section.
167 *
168 * <b> Return Value </b>
169 * @n Not applicable.
170 */
171 #define Rm_osalCsExit Osal_rmCsExit
173 /**
174 * @brief The function is used to enter a multi-threaded critical
175 * section. Function protects against
176 *
177 * access from multiple threads on single core
178 *
179 * <b> Prototype: </b>
180 * The following is the C prototype for the expected OSAL API.
181 *
182 * @verbatim
183 void *Osal_rmMtCsEnter (void *mtSemObj)
184 @endverbatim
185 *
186 * <b> Parameter </b>
187 * @n Multi-threaded critical section object handle.
188 *
189 * <b> Return Value </b>
190 * @n Handle used to lock the multi-threaded critical section
191 */
192 #define Rm_osalMtCsEnter Osal_rmMtCsEnter
194 /**
195 * @brief The function is used to exit a multi-threaded critical
196 * section protected using Osal_rmMtCsEnter() API.
197 *
198 * <b> Prototype: </b>
199 * The following is the C prototype for the expected OSAL API.
200 *
201 * @verbatim
202 void Osal_rmMtCsExit (void *mtSemObj, void *CsHandle)
203 @endverbatim
204 *
205 * <b> Parameter </b>
206 * @n Multi-threaded critical section object handle.
207 *
208 * <b> Parameter </b>
209 * @n Handle for unlocking multi-threaded critical section.
210 *
211 * <b> Return Value </b>
212 * @n Not applicable.
213 */
214 #define Rm_osalMtCsExit Osal_rmMtCsExit
216 /**
217 * @brief The function is used to indicate that a block of memory is
218 * about to be accessed. If the memory block is cached then this
219 * indicates that the application would need to ensure that the
220 * cache is updated with the data from the actual memory.
221 *
222 * <b> Prototype: </b>
223 * The following is the C prototype for the expected OSAL API.
224 *
225 * @verbatim
226 void Osal_rmBeginMemAccess (void *ptr, uint32_t size)
227 @endverbatim
228 *
229 * <b> Parameter </b>
230 * @n Address of memory block
231 * @n Size of memory block
232 *
233 * <b> Return Value </b>
234 * @n Not applicable.
235 */
236 #define Rm_osalBeginMemAccess Osal_rmBeginMemAccess
238 /**
239 * @brief The function is used to indicate that the block of memory has
240 * finished being accessed. If the memory block is cached then the
241 * application would need to ensure that the contents of the cache
242 * are updated immediately to the actual memory.
243 *
244 * <b> Prototype: </b>
245 * The following is the C prototype for the expected OSAL API.
246 *
247 * @verbatim
248 void Osal_rmEndMemAccess (void *ptr, uint32_t size)
249 @endverbatim
250 *
251 * <b> Parameter </b>
252 * @n Address of memory block
253 * @n Size of memory block
254 *
255 * <b> Return Value </b>
256 * @n Not applicable.
257 */
258 #define Rm_osalEndMemAccess Osal_rmEndMemAccess
260 /**
261 * @brief The macro is used by RM to create a task blocking
262 * mechanism allowing a RM instance to block when it
263 * has not been provided a service callback function
264 * and it must send a packet to remote RM instance
265 * to complete a service.
266 *
267 * <b> Prototype: </b>
268 * The following is the C prototype for the expected OSAL API.
269 *
270 * @verbatim
271 void *Osal_rmTaskBlockCreate (void)
272 @endverbatim
273 *
274 * <b> Parameter </b>
275 * @n Not applicable.
276 *
277 * <b> Return Value </b>
278 * @n Task blocking mechanism handle cast as a void pointer
279 */
280 #define Rm_osalTaskBlockCreate Osal_rmTaskBlockCreate
282 /**
283 * @brief The macro is used by a RM instance to block when it
284 * has not been provided a service callback function
285 * and it must send a packet to remote RM instance
286 * to complete a service. The blocking operation
287 * should block the current RM instance's task/thread
288 * from executing until a task/thread from which the
289 * RM receive code runs unblocks the RM instance
290 *
291 * <b> Prototype: </b>
292 * The following is the C prototype for the expected OSAL API.
293 *
294 * @verbatim
295 void Osal_rmTaskBlock (void *handle)
296 @endverbatim
297 *
298 * <b> Parameter </b>
299 * @n Task blocking mechanism handle cast as a void pointer
300 *
301 * <b> Return Value </b>
302 * @n Not applicable.
303 */
304 #define Rm_osalTaskBlock Osal_rmTaskBlock
306 /**
307 * @brief The macro is used by a RM instance to unblock from
308 * a previous block operation.
309 *
310 * <b> Prototype: </b>
311 * The following is the C prototype for the expected OSAL API.
312 *
313 * @verbatim
314 void Osal_rmTaskUnblock (void *handle)
315 @endverbatim
316 *
317 * <b> Parameter </b>
318 * @n Task blocking mechanism handle cast as a void pointer
319 *
320 * <b> Return Value </b>
321 * @n Not applicable.
322 */
323 #define Rm_osalTaskUnblock Osal_rmTaskUnblock
325 /**
326 * @brief The macro is used by a RM instance to delete its
327 * task blocking mechanism.
328 *
329 * <b> Prototype: </b>
330 * The following is the C prototype for the expected OSAL API.
331 *
332 * @verbatim
333 void Osal_rmTaskBlockDelete (void *handle)
334 @endverbatim
335 *
336 * <b> Parameter </b>
337 * @n Task blocking mechanism handle cast as a void pointer
338 *
339 * <b> Return Value </b>
340 * @n Not applicable.
341 */
342 #define Rm_osalTaskBlockDelete Osal_rmTaskBlockDelete
344 /**
345 * @brief The macro is used by RM to log various
346 * messages.
347 *
348 * <b> Prototype: </b>
349 * The following is the C prototype for the expected OSAL API.
350 *
351 * @verbatim
352 void Osal_rmLog( char *fmt, ... )
353 @endverbatim
354 *
355 * <b> Parameter </b>
356 * @n printf-style format string
357 *
358 * <b> Return Value </b>
359 * @n Not applicable.
360 */
361 #define Rm_osalLog Osal_rmLog
363 /**
364 @}
365 */
367 #endif /* RM_OSAL_H_ */