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_rmBeginMemAccess (void *ptr, uint32_t size);
83 extern void Osal_rmEndMemAccess (void *ptr, uint32_t size);
84 extern void *Osal_rmTaskBlockCreate (void);
85 extern void Osal_rmTaskBlock (void *handle);
86 extern void Osal_rmTaskUnblock (void *handle);
87 extern void Osal_rmTaskBlockDelete (void *handle);
88 extern void Osal_rmLog (char *fmt, ... );
90 /**
91 * @brief The macro is used by RM to allocate memory of specified
92 * size
93 *
94 * <b> Prototype: </b>
95 * The following is the C prototype for the expected OSAL API.
96 *
97 * @verbatim
98 void* Osal_rmMalloc (uint32_t numBytes)
99 @endverbatim
100 *
101 * <b> Parameter </b>
102 * @n Number of bytes to be allocated
103 *
104 * <b> Return Value </b>
105 * @n Pointer to the allocated block size
106 */
107 #define Rm_osalMalloc Osal_rmMalloc
109 /**
110 * @brief The macro is used by RM to free a allocated block of
111 * memory
112 *
113 * <b> Prototype: </b>
114 * The following is the C prototype for the expected OSAL API.
115 *
116 * @verbatim
117 void Osal_rmFree (void *ptr, uint32_t size)
118 @endverbatim
119 *
120 * <b> Parameter </b>
121 * @n Pointer to the block of memory to be cleaned up.
122 * @n Size of the allocated memory which is being freed.
123 *
124 * <b> Return Value </b>
125 * @n Not applicable.
126 */
127 #define Rm_osalFree Osal_rmFree
129 /**
130 * @brief The function is used to enter a critical section.
131 * Function protects against
132 *
133 * access from multiple cores
134 * and
135 * access from multiple threads on single core
136 *
137 * <b> Prototype: </b>
138 * The following is the C prototype for the expected OSAL API.
139 *
140 * @verbatim
141 void *Osal_rmCsEnter (void)
142 @endverbatim
143 *
144 * <b> Parameter </b>
145 * @n Not applicable.
146 *
147 * <b> Return Value </b>
148 * @n Handle used to lock critical section
149 */
150 #define Rm_osalCsEnter Osal_rmCsEnter
152 /**
153 * @brief The function is used to exit a critical section
154 * protected using Osal_rmCsEnter() API.
155 *
156 * <b> Prototype: </b>
157 * The following is the C prototype for the expected OSAL API.
158 *
159 * @verbatim
160 void Osal_rmCsExit (void *CsHandle)
161 @endverbatim
162 *
163 * <b> Parameter </b>
164 * @n Handle for unlocking critical section.
165 *
166 * <b> Return Value </b>
167 * @n Not applicable.
168 */
169 #define Rm_osalCsExit Osal_rmCsExit
171 /**
172 * @brief The function is used to indicate that a block of memory is
173 * about to be accessed. If the memory block is cached then this
174 * indicates that the application would need to ensure that the
175 * cache is updated with the data from the actual memory.
176 *
177 * <b> Prototype: </b>
178 * The following is the C prototype for the expected OSAL API.
179 *
180 * @verbatim
181 void Osal_rmBeginMemAccess (void *ptr, uint32_t size)
182 @endverbatim
183 *
184 * <b> Parameter </b>
185 * @n Address of memory block
186 * @n Size of memory block
187 *
188 * <b> Return Value </b>
189 * @n Not applicable.
190 */
191 #define Rm_osalBeginMemAccess Osal_rmBeginMemAccess
193 /**
194 * @brief The function is used to indicate that the block of memory has
195 * finished being accessed. If the memory block is cached then the
196 * application would need to ensure that the contents of the cache
197 * are updated immediately to the actual memory.
198 *
199 * <b> Prototype: </b>
200 * The following is the C prototype for the expected OSAL API.
201 *
202 * @verbatim
203 void Osal_rmEndMemAccess (void *ptr, uint32_t size)
204 @endverbatim
205 *
206 * <b> Parameter </b>
207 * @n Address of memory block
208 * @n Size of memory block
209 *
210 * <b> Return Value </b>
211 * @n Not applicable.
212 */
213 #define Rm_osalEndMemAccess Osal_rmEndMemAccess
215 /**
216 * @brief The macro is used by RM to create a task blocking
217 * mechanism allowing a RM instance to block when it
218 * has not been provided a service callback function
219 * and it must send a packet to remote RM instance
220 * to complete a service.
221 *
222 * <b> Prototype: </b>
223 * The following is the C prototype for the expected OSAL API.
224 *
225 * @verbatim
226 void *Osal_rmTaskBlockCreate (void)
227 @endverbatim
228 *
229 * <b> Parameter </b>
230 * @n Not applicable.
231 *
232 * <b> Return Value </b>
233 * @n Task blocking mechanism handle cast as a void pointer
234 */
235 #define Rm_osalTaskBlockCreate Osal_rmTaskBlockCreate
237 /**
238 * @brief The macro is used by a RM instance to block when it
239 * has not been provided a service callback function
240 * and it must send a packet to remote RM instance
241 * to complete a service. The blocking operation
242 * should block the current RM instance's task/thread
243 * from executing until a task/thread from which the
244 * RM receive code runs unblocks the RM instance
245 *
246 * <b> Prototype: </b>
247 * The following is the C prototype for the expected OSAL API.
248 *
249 * @verbatim
250 void Osal_rmTaskBlock (void *handle)
251 @endverbatim
252 *
253 * <b> Parameter </b>
254 * @n Task blocking mechanism handle cast as a void pointer
255 *
256 * <b> Return Value </b>
257 * @n Not applicable.
258 */
259 #define Rm_osalTaskBlock Osal_rmTaskBlock
261 /**
262 * @brief The macro is used by a RM instance to unblock from
263 * a previous block operation.
264 *
265 * <b> Prototype: </b>
266 * The following is the C prototype for the expected OSAL API.
267 *
268 * @verbatim
269 void Osal_rmTaskUnblock (void *handle)
270 @endverbatim
271 *
272 * <b> Parameter </b>
273 * @n Task blocking mechanism handle cast as a void pointer
274 *
275 * <b> Return Value </b>
276 * @n Not applicable.
277 */
278 #define Rm_osalTaskUnblock Osal_rmTaskUnblock
280 /**
281 * @brief The macro is used by a RM instance to delete its
282 * task blocking mechanism.
283 *
284 * <b> Prototype: </b>
285 * The following is the C prototype for the expected OSAL API.
286 *
287 * @verbatim
288 void Osal_rmTaskBlockDelete (void *handle)
289 @endverbatim
290 *
291 * <b> Parameter </b>
292 * @n Task blocking mechanism handle cast as a void pointer
293 *
294 * <b> Return Value </b>
295 * @n Not applicable.
296 */
297 #define Rm_osalTaskBlockDelete Osal_rmTaskBlockDelete
299 /**
300 * @brief The macro is used by RM to log various
301 * messages.
302 *
303 * <b> Prototype: </b>
304 * The following is the C prototype for the expected OSAL API.
305 *
306 * @verbatim
307 void Osal_rmLog( char *fmt, ... )
308 @endverbatim
309 *
310 * <b> Parameter </b>
311 * @n printf-style format string
312 *
313 * <b> Return Value </b>
314 * @n Not applicable.
315 */
316 #define Rm_osalLog Osal_rmLog
318 /**
319 @}
320 */
322 #endif /* RM_OSAL_H_ */