1 /**
2 * @file rm_osal.h
3 *
4 * @brief
5 * This is the sample OS Adaptation layer which is used by the RM low level
6 * driver. 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 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_LLD_OSAL
71 @{ */
73 /**********************************************************************
74 ************************* Extern Declarations ************************
75 **********************************************************************/
77 /* #include <string.h> is here because there used to be
78 * memcpy/memset prototypes here. This #include prevents warnings in
79 * other code that unintentionally worked because of these prototypes
80 */
81 #include <string.h>
83 extern void* Osal_rmMalloc (uint32_t num_bytes, bool shared);
84 extern void Osal_rmFree (void *ptr, uint32_t size, bool shared);
85 extern void* Osal_rmLocalCsEnter (void);
86 extern void Osal_rmLocalCsExit (void *CsHandle);
87 extern void* Osal_rmCsEnter (void);
88 extern void Osal_rmCsExit (void *CsHandle);
89 extern void* Osal_rmMtCsEnter (void);
90 extern void Osal_rmMtCsExit (void *CsHandle);
91 extern void Osal_rmLog (char *fmt, ... );
92 extern void Osal_rmBeginMemAccess (void *ptr, uint32_t size);
93 extern void Osal_rmEndMemAccess (void *ptr, uint32_t size);
95 /**
96 * @brief The macro is used by the RM LLD to allocate memory of specified
97 * size
98 *
99 * <b> Prototype: </b>
100 * The following is the C prototype for the expected OSAL API.
101 *
102 * @verbatim
103 void* Osal_rmMalloc (uint32_t numBytes)
104 @endverbatim
105 *
106 * <b> Parameter </b>
107 * @n Number of bytes to be allocated
108 *
109 * <b> Parameter </b>
110 * @n If true the memory should could from shared memory
111 *
112 * <b> Return Value </b>
113 * @n Pointer to the allocated block size
114 */
116 #define Rm_osalMalloc Osal_rmMalloc
118 /**
119 * @brief The macro is used by the RM LLD to free a allocated block of
120 * memory
121 *
122 * <b> Prototype: </b>
123 * The following is the C prototype for the expected OSAL API.
124 *
125 * @verbatim
126 void Osal_rmFree (void *ptr, uint32_t size)
127 @endverbatim
128 *
129 * <b> Parameter </b>
130 * @n Pointer to the block of memory to be cleaned up.
131 * @n Size of the allocated memory which is being freed.
132 *
133 * <b> Return Value </b>
134 * @n Not applicable.
135 */
137 #define Rm_osalFree Osal_rmFree
139 /**
140 * @brief The macro is used by the RM LLD to provide critical sections to
141 * protect shared variables from access from multiple RM instances
142 * on a single core
143 *
144 * <b> Prototype: </b>
145 * The following is the C prototype for the expected OSAL API.
146 *
147 * @verbatim
148 void* Osal_rmLocalCsEnter (void)
149 @endverbatim
150 *
151 * <b> Parameter </b>
152 * @n None.
153 *
154 * <b> Return Value </b>
155 * @n Handle used to lock critical section.
156 */
157 #define Rm_osalLocalCsEnter Osal_rmLocalCsEnter
159 /**
160 * @brief The macro is used by the RM LLD to exit a critical section
161 * protected using Osal_rmLocalCsEnter() API.
162 *
163 * <b> Prototype: </b>
164 * The following is the C prototype for the expected OSAL API.
165 *
166 * @verbatim
167 void Osal_rmLocalCsExit (void *CsHandle)
168 @endverbatim
169 *
170 * <b> Parameter </b>
171 * @n Handle for unlocking critical section.
172 *
173 * <b> Return Value </b>
174 * @n Not applicable.
175 */
176 #define Rm_osalLocalCsExit Osal_rmLocalCsExit
178 /**
179 * @brief The macro is used by the RM LLD to provide critical sections to
180 * protect global and shared variables from
181 *
182 * access from multiple cores
183 * and
184 * access from multiple threads on single core
185 *
186 * <b> Prototype: </b>
187 * The following is the C prototype for the expected OSAL API.
188 *
189 * @verbatim
190 void* Osal_rmCsEnter (void)
191 @endverbatim
192 *
193 * <b> Parameter </b>
194 * @n None.
195 *
196 * <b> Return Value </b>
197 * @n Handle used to lock critical section.
198 */
199 #define Rm_osalCsEnter Osal_rmCsEnter
201 /**
202 * @brief The macro is used by the RM LLD to exit a critical section
203 * protected using Osal_rmCsEnter() API.
204 *
205 * <b> Prototype: </b>
206 * The following is the C prototype for the expected OSAL API.
207 *
208 * @verbatim
209 void Osal_rmCsExit (void *CsHandle)
210 @endverbatim
211 *
212 * <b> Parameter </b>
213 * @n Handle for unlocking critical section.
214 *
215 * <b> Return Value </b>
216 * @n Not applicable.
217 */
218 #define Rm_osalCsExit Osal_rmCsExit
220 /**
221 * @brief The macro is used by the RM LLD to provide critical sections to
222 * protect global and shared variables from
223 *
224 * access from multiple threads on single core
225 *
226 * <b> Prototype: </b>
227 * The following is the C prototype for the expected OSAL API.
228 *
229 * @verbatim
230 void* Osal_rmMtCsEnter (void)
231 @endverbatim
232 *
233 * <b> Parameter </b>
234 * @n None.
235 *
236 * <b> Return Value </b>
237 * @n Handle used to lock critical section.
238 */
239 #define Rm_osalMtCsEnter Osal_rmMtCsEnter
241 /**
242 * @brief The macro is used by the RM LLD to exit a critical section
243 * protected using Osal_rmMtCsEnter() API.
244 *
245 * <b> Prototype: </b>
246 * The following is the C prototype for the expected OSAL API.
247 *
248 * @verbatim
249 void Osal_rmMtCsExit (void *CsHandle)
250 @endverbatim
251 *
252 * <b> Parameter </b>
253 * @n Handle for unlocking critical section.
254 *
255 * <b> Return Value </b>
256 * @n Not applicable.
257 */
258 #define Rm_osalMtCsExit Osal_rmMtCsExit
260 /**
261 * @brief The macro is used by the RM LLD to log various
262 * messages.
263 *
264 * <b> Prototype: </b>
265 * The following is the C prototype for the expected OSAL API.
266 *
267 * @verbatim
268 void Osal_rmLog( char *fmt, ... )
269 @endverbatim
270 *
271 * <b> Parameter </b>
272 * @n printf-style format string
273 *
274 * <b> Return Value </b>
275 * @n Not applicable.
276 */
277 #define Rm_osalLog Osal_rmLog
279 /**
280 * @brief The macro is used by the RM LLD to indicate that a block
281 * of memory is about to be accessed. If the memory block is cached then
282 * this indicates that the application would need to ensure that the cache
283 * is updated with the data from the actual memory.
284 *
285 * <b> Prototype: </b>
286 * The following is the C prototype for the expected OSAL API.
287 *
288 * @verbatim
289 void Osal_rmBeginMemAccess (void *ptr, uint32_t size)
290 @endverbatim
291 *
292 * <b> Parameter </b>
293 * @n Address of memory block.
294 * @n Size of memory block.
295 *
296 * <b> Return Value </b>
297 * @n Not applicable.
298 */
299 #define Rm_osalBeginMemAccess Osal_rmBeginMemAccess
301 /**
302 * @brief The macro is used by the RM LLD to indicate that the block of
303 * memory has finished being accessed. If the memory block is cached then the
304 * application would need to ensure that the contents of the cache are updated
305 * immediately to the actual memory.
306 *
307 * <b> Prototype: </b>
308 * The following is the C prototype for the expected OSAL API.
309 *
310 * @verbatim
311 void Osal_rmEndMemAccess (void *ptr, uint32_t size)
312 @endverbatim
313 *
314 * <b> Parameter </b>
315 * @n Address of memory block.
316 * @n Size of memory block.
317 *
318 * <b> Return Value </b>
319 * @n Not applicable.
320 */
321 #define Rm_osalEndMemAccess Osal_rmEndMemAccess
323 /**
324 @}
325 */
326 #endif /* __RM_OSAL_H__ */