1 /**
2 * @file mcbsp_osal.h
3 *
4 * @brief
5 * This is the sample OS Adaptation layer which is used by the MCBSP
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 MCBSP Driver 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 * - MCBSP 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 __MCBSP_OSAL_H__
68 #define __MCBSP_OSAL_H__
70 #include <string.h>
71 #include <ti/drv/mcbsp/mcbsp_drv.h>
73 /** @addtogroup MCBSP_OSAL_API
74 @{ */
76 /**********************************************************************
77 ************************* Extern Declarations ************************
78 **********************************************************************/
80 extern void* Osal_mcbspMalloc(uint32_t numBytes);
81 extern void Osal_mcbspFree (void* ptr, uint32_t size);
82 extern void* Osal_mcbspDataBufferMalloc(uint32_t numBytes);
83 extern void Osal_mcbspDataBufferFree(void* ptr, uint32_t numBytes);
84 extern void Osal_mcbspLog(char* fmt, ... );
85 extern void* Osal_mcbspCreateSem(void);
86 extern void Osal_mcbspDeleteSem(void* semHandle);
87 extern void Osal_mcbspPendSem(void* semHandle);
88 extern void Osal_mcbspPostSem(void* semHandle);
89 extern void* Osal_mcbspEnterMultipleCoreCriticalSection(void);
90 extern void Osal_mcbspExitMultipleCoreCriticalSection(void* critSectHandle);
91 extern void* Osal_mcbspEnterSingleCoreCriticalSection();
92 extern void Osal_mcbspExitSingleCoreCriticalSection(void* critSectHandle);
93 extern void Osal_mcbspBeginMemAccess(void* ptr, uint32_t size);
94 extern void Osal_mcbspEndMemAccess(void* ptr, uint32_t size);
96 extern Bool Osal_mcbspQueueEmpty(void* handle);
97 extern void* Osal_mcbspQueueGet(void* handle);
98 extern void Osal_mcbspQueuePut(void* handle, Mcbsp_QueueElem* elem);
99 extern void Osal_mcbspWaitNBitClocks(uint32_t nticks);
100 extern void *Osal_local2Global (void *addr);
101 /**
102 * @brief The macro is used by the MCBSP driver to create a semaphore for
103 * each MCBSP socket opened in blocking mode. Semaphores created should
104 * *initially* be created with a count of 0 i.e. unavailable.
105 *
106 * <b> Prototype: </b>
107 * The following is the C prototype for the expected OSAL API.
108 *
109 * @verbatim
110 void* Osal_mcbspCreateSem(void);
111 @endverbatim
112 *
113 * <b> Parameter </b>
114 * @n Not Applicable
115 *
116 * <b> Return Value </b>
117 * @n Semaphore Handle
118 */
119 #define Mcbsp_osalCreateSem() Osal_mcbspCreateSem()
121 /**
122 * @brief The macro is used by the MCBSP driver to delete a previously
123 * created semaphore. This is called when a MCBSP socket opened in blocking mode
124 * is being closed.
125 *
126 * <b> Prototype: </b>
127 * The following is the C prototype for the expected OSAL API.
128 *
129 * @verbatim
130 void Osal_mcbspDeleteSem(void* semHandle)
131 @endverbatim
133 * <b> Parameter </b>
134 * @n Semaphore Handle returned by the create semaphore
135 *
136 * <b> Return Value </b>
137 * @n Not Applicable
138 */
139 #define Mcbsp_osalDeleteSem(X) Osal_mcbspDeleteSem(X)
141 /**
142 * @brief The macro is used by the MCBSP driver to pend on a semaphore
143 * This is called when an application tries to receive data on a blocking
144 * socket when there is no data available. Since all semaphores are initially
145 * created to be unavailable; this will cause the application to block.
146 *
147 * <b> Prototype: </b>
148 * The following is the C prototype for the expected OSAL API.
149 *
150 * @verbatim
151 void Osal_mcbspPendSem(void* semHandle)
152 @endverbatim
153 *
154 * <b> Parameter </b>
155 * @n Semaphore Handle
156 *
157 * <b> Return Value </b>
158 * @n Not Applicable
159 */
160 #define Mcbsp_osalPendSem(X) Osal_mcbspPendSem(X)
162 /**
163 * @brief The macro is used by the MCBSP driver to post the semaphore
164 * The driver posts the semaphore once data is received on a specific
165 * socket.
166 *
167 * <b> Prototype: </b>
168 * The following is the C prototype for the expected OSAL API.
169 *
170 * @verbatim
171 void Osal_mcbspPostSem(void* semHandle)
172 @endverbatim
173 *
174 * <b> Parameter </b>
175 * @n Semaphore Handle
176 *
177 * <b> Return Value </b>
178 * @n Not Applicable
179 */
180 #define Mcbsp_osalPostSem(X) Osal_mcbspPostSem(X)
182 /**
183 * @brief The macro is used by the MCBSP driver to allocate memory
184 * The MCBSP driver uses this macro to allocate memory for its internal
185 * driver structures. This is invoked during the driver initialization
186 * and startup process.
187 *
188 * <b> Prototype: </b>
189 * The following is the C prototype for the expected OSAL API.
190 *
191 * @verbatim
192 void* Osal_mcbspMalloc(uint32_t numBytes)
193 @endverbatim
194 *
195 * <b> Parameter </b>
196 * @n Number of bytes to be allocated
197 *
198 * <b> Return Value </b>
199 * @n Pointer to the allocated block size
200 *
201 * @sa
202 * Mcbsp_osalDataBufferMalloc
203 */
204 #define Mcbsp_osalMalloc(X) Osal_mcbspMalloc(X)
206 /**
207 * @brief The macro is used by the MCBSP driver to free a previously
208 * allocated block of memory
209 *
210 * <b> Prototype: </b>
211 * The following is the C prototype for the expected OSAL API.
212 *
213 * @verbatim
214 void Osal_mcbspFree(void* ptr, uint32_t numBytes)
215 @endverbatim
216 *
217 * <b> Parameter </b>
218 * @n Pointer to the block of memory to be cleaned up.
219 * @n Size of the allocated memory which is being freed.
220 *
221 * <b> Return Value </b>
222 * @n Not applicable.
223 */
224 #define Mcbsp_osalFree(X, Y) Osal_mcbspFree(X, Y)
226 /**
227 * @brief The macro is used by the MCBSP driver to allocate memory
228 * for the data buffers in Driver Managed Configuration. All data
229 * buffers should allocated should be in the global address space.
230 * This macro is invoked during the data path.
231 *
232 * <b> Prototype: </b>
233 * The following is the C prototype for the expected OSAL API.
234 *
235 * @verbatim
236 void* Osal_mcbspDataBufferMalloc(uint32_t numBytes)
237 @endverbatim
238 *
239 * <b> Parameter </b>
240 * @n Number of bytes to be allocated
241 *
242 * <b> Return Value </b>
243 * @n Pointer to the allocated block size
244 */
245 #define Mcbsp_osalDataBufferMalloc(X) Osal_mcbspDataBufferMalloc(X)
247 /**
248 * @brief The macro is used by the MCBSP driver to convert local address
249 * to Global address space
250 *
251 * <b> Prototype: </b>
252 * The following is the C prototype for the expected OSAL API.
253 *
254 * @verbatim
255 void *Osal_local2Global (void *addr)
256 @endverbatim
257 *
258 * <b> Parameter </b>
259 * @n Local address pointer
260 *
261 * <b> Return Value </b>
262 * @n Global address pointer
263 */
265 #define Mcbsp_osalLocal2Global(X) Osal_local2Global(X)
266 /**
267 * @brief The macro is used by the MCBSP driver to free a previously
268 * allocated block data buffer. This macro is used to clean up previously
269 * allocated data buffers and is invoked during the data path.
270 *
271 * <b> Prototype: </b>
272 * The following is the C prototype for the expected OSAL API.
273 *
274 * @verbatim
275 void Osal_mcbspDataBufferFree(void* ptr, uint32_t numBytes)
276 @endverbatim
277 *
278 * <b> Parameter </b>
279 * @n Pointer to the block of memory to be cleaned up.
280 * @n Size of the allocated memory which is being freed.
281 *
282 * <b> Return Value </b>
283 * @n Not applicable.
284 */
285 #define Mcbsp_osalDataBufferFree(X, Y) Osal_mcbspDataBufferFree(X, Y)
287 /**
288 * @brief The macro is used by the MCBSP driver to log various
289 * messages.
290 *
291 * <b> Prototype: </b>
292 * The following is the C prototype for the expected OSAL API.
293 *
294 * @verbatim
295 void Osal_mcbspLog( char* fmt, ... )
296 @endverbatim
297 *
298 * <b> Parameter </b>
299 * @n printf-style format string
300 *
301 * <b> Return Value </b>
302 * @n Not applicable.
303 */
304 #define Mcbsp_osalLog Osal_mcbspLog
306 /**
307 * @brief The macro is used by the MCBSP Driver to protect its shared resources
308 * access from MULTIPLE CORES. This is required if the MCBSP Driver API's are being
309 * invoked from multiple cores. If this is not the case then these macros can be
310 * defined to be NOP.
311 *
312 * <b> Prototype: </b>
313 * The following is the C prototype for the expected OSAL API.
314 *
315 * @verbatim
316 void* Osal_mcbspEnterMultipleCoreCriticalSection(void)
317 @endverbatim
318 *
319 * <b> Parameter </b>
320 * @n None
321 *
322 * <b> Return Value </b>
323 * @n Opaque Handle used for holding critical section locking information
324 */
325 #define Mcbsp_osalEnterMultipleCoreCriticalSection Osal_mcbspEnterMultipleCoreCriticalSection
327 /**
328 * @brief The macro is used by the MCBSP driver to end the protection of its
329 * internal shared "resources" from MULTIPLE CORE access.
330 *
331 * <b> Prototype: </b>
332 * The following is the C prototype for the expected OSAL API.
333 *
334 * @verbatim
335 void Osal_mcbspExitMultipleCoreCriticalSection(void* critSectHandle)
336 @endverbatim
337 *
338 * <b> Parameter </b>
339 * @n Opaque Handle used for holding critical section locking information
340 *
341 * <b> Return Value </b>
342 * @n None
343 */
344 #define Mcbsp_osalExitMultipleCoreCriticalSection Osal_mcbspExitMultipleCoreCriticalSection
346 /**
347 * @brief The macro is used by the MCBSP driver to protect its internal shared
348 * resources from SINGLE CORE MULTIPLE CONTEXT (thread or ISR) access. If all
349 * the MCBSP Driver APIs are being called from threads then this API could
350 * use semaphores. However if the MCBSP driver API's are being called from
351 * both ISR & Thread context then the critical section here would need to
352 * disable/enable interrupts.
353 *
354 * <b> Prototype: </b>
355 * The following is the C prototype for the expected OSAL API.
356 *
357 * @verbatim
358 void* Osal_mcbspEnterSingleCoreCriticalSection()
359 @endverbatim
360 *
361 * <b> Parameter </b>
362 * @n None
363 *
364 * <b> Return Value </b>
365 * @n Opaque Handle used for holding critical section locking information
366 */
367 #define Mcbsp_osalEnterSingleCoreCriticalSection Osal_mcbspEnterSingleCoreCriticalSection
369 /**
370 * @brief The macro is used to denote the end of the protection of the internal
371 * shared resource from SINGLE CORE MULTIPLE CONTEXT access.
372 *
373 * <b> Prototype: </b>
374 * The following is the C prototype for the expected OSAL API.
375 *
376 * @verbatim
377 void Osal_mcbspExitSingleCoreCriticalSection(void* critSectHandle)
378 @endverbatim
379 *
380 * <b> Parameter </b>
381 * @n critSectHandle - Opaque Handle used for holding critical section locking information
382 *
383 * <b> Return Value </b>
384 * @n None
385 */
386 #define Mcbsp_osalExitSingleCoreCriticalSection Osal_mcbspExitSingleCoreCriticalSection
388 /**
389 * @brief The macro is used by the MCBSP driver to indicate that a block
390 * of memory is about to be accessed. If the memory block is cached then
391 * this indicates that the application would need to ensure that the cache
392 * is updated with the data from the actual memory.
393 *
394 * <b> Prototype: </b>
395 * The following is the C prototype for the expected OSAL API.
396 *
397 * @verbatim
398 void Osal_mcbspBeginMemAccess(void* ptr, uint32_t size)
399 @endverbatim
400 *
401 * <b> Parameter </b>
402 * @n ptr - Pointer to the memory
403 * @n size - Size of the memory being accessed.
404 *
405 * <b> Return Value </b>
406 * @n None
407 */
408 #define Mcbsp_osalBeginMemAccess Osal_mcbspBeginMemAccess
410 /**
411 * @brief The macro is used by the MCBSP driver to indicate that the block of
412 * memory has finished being accessed. If the memory block is cached then the
413 * application would need to ensure that the contents of the cache are updated
414 * immediately to the actual memory.
415 *
416 * <b> Prototype: </b>
417 * The following is the C prototype for the expected OSAL API.
418 *
419 * @verbatim
420 void Osal_mcbspEndMemAccess(void* ptr, uint32_t size)
421 @endverbatim
422 *
423 * <b> Parameter </b>
424 * @n ptr - Pointer to the memory
425 * @n size - Size of the memory
426 *
427 * <b> Return Value </b>
428 * @n None
429 */
430 #define Mcbsp_osalEndMemAccess Osal_mcbspEndMemAccess
432 /**
433 * @brief The macro is used by the MCBSP driver to test for an
434 * empty queue.
435 *
436 * <b> Prototype: </b>
437 * The following is the C prototype for the expected OSAL API.
438 *
439 * @verbatim
440 void Osal_mcbspQueueEmpty(void* handle)
441 @endverbatim
442 *
443 * <b> Parameter </b>
444 * @n handle - Handle of a previously created Queue instance object
445 *
446 * <b> Return Value </b>
447 * @n TRUE - If the queue is empty
448 */
449 #define Mcbsp_osalQueueEmpty Osal_mcbspQueueEmpty
451 /**
452 * @brief The macro is used by the MCBSP driver to get an
453 * element from the front of queue. The function
454 * removes the element from the front of queue and
455 * returns a pointer to it.
456 *
457 * <b> Prototype: </b>
458 * The following is the C prototype for the expected OSAL API.
459 *
460 * @verbatim
461 void* Osal_mcbspQueueGet(void* handle)
462 @endverbatim
463 *
464 * <b> Parameter </b>
465 * @n handle - Handle of a previously created Queue instance object
466 *
467 * <b> Return Value </b>
468 * @n Handle (pointer) to former first element
469 */
470 #define Mcbsp_osalQueueGet Osal_mcbspQueueGet
472 /**
473 * @brief The macro is used by the MCBSP driver to put an
474 * element at the end of queue.
475 *
476 * <b> Prototype: </b>
477 * The following is the C prototype for the expected OSAL API.
478 *
479 * @verbatim
480 void Osal_mcbspQueuePut(void* handle, Mcbsp_QueueElem* elem)
481 @endverbatim
482 *
483 * <b> Parameter </b>
484 * @n handle - Handle of a previously created Queue instance object
485 * @n elem - Pointer to new queue element
486 *
487 * <b> Return Value </b>
488 * @n None
489 */
490 #define Mcbsp_osalQueuePut Osal_mcbspQueuePut
492 /**
493 * @brief The macro is used by the MCBSP driver to wait 'n'
494 * bit clocks to ensure proper synchronization internally.
495 *
496 * <b> Prototype: </b>
497 * The following is the C prototype for the expected OSAL API.
498 *
499 * @verbatim
500 void Osal_mcbspWaitNBitClocks(uint32_t nticks)
501 @endverbatim
502 *
503 * <b> Parameter </b>
504 * @n nticks - Number of bit clocks to wait
505 *
506 * <b> Return Value </b>
507 * @n None
508 */
509 #define Mcbsp_osalWaitNBitClocks Osal_mcbspWaitNBitClocks
510 /**
511 @}
512 */
514 #endif /* __MCBSP_OSAL_H__ */