# MCBSP_OSAL_API

## Defines

#define | Mcbsp_osalCreateSem() Osal_mcbspCreateSem()
| The macro is used by the MCBSP driver to create a semaphore for each MCBSP socket opened in blocking mode. Semaphores created should *initially* be created with a count of 0 i.e. unavailable.
#define | Mcbsp_osalDeleteSem(X) Osal_mcbspDeleteSem(X)
| The macro is used by the MCBSP driver to delete a previously created semaphore. This is called when a MCBSP socket opened in blocking mode is being closed.
#define | Mcbsp_osalPendSem(X) Osal_mcbspPendSem(X)
| The macro is used by the MCBSP driver to pend on a semaphore This is called when an application tries to receive data on a blocking socket when there is no data available. Since all semaphores are initially created to be unavailable; this will cause the application to block.
#define | Mcbsp_osalPostSem(X) Osal_mcbspPostSem(X)
| The macro is used by the MCBSP driver to post the semaphore The driver posts the semaphore once data is received on a specific socket.
#define | Mcbsp_osalMalloc(X) Osal_mcbspMalloc(X)
| The macro is used by the MCBSP driver to allocate memory The MCBSP driver uses this macro to allocate memory for its internal driver structures. This is invoked during the driver initialization and startup process.
#define | Mcbsp_osalFree(X, Y) Osal_mcbspFree(X, Y)
| The macro is used by the MCBSP driver to free a previously allocated block of memory.
#define | Mcbsp_osalDataBufferMalloc(X) Osal_mcbspDataBufferMalloc(X)
| The macro is used by the MCBSP driver to allocate memory for the data buffers in Driver Managed Configuration. All data buffers should allocated should be in the global address space. This macro is invoked during the data path.
#define | Mcbsp_osalDataBufferFree(X, Y) Osal_mcbspDataBufferFree(X, Y)
| The macro is used by the MCBSP driver to free a previously allocated block data buffer. This macro is used to clean up previously allocated data buffers and is invoked during the data path.
#define | Mcbsp_osalLog Osal_mcbspLog
| The macro is used by the MCBSP driver to log various messages.
#define | Mcbsp_osalEnterMultipleCoreCriticalSection Osal_mcbspEnterMultipleCoreCriticalSection
| The macro is used by the MCBSP Driver to protect its shared resources access from MULTIPLE CORES. This is required if the MCBSP Driver API's are being invoked from multiple cores. If this is not the case then these macros can be defined to be NOP.
#define | Mcbsp_osalExitMultipleCoreCriticalSection Osal_mcbspExitMultipleCoreCriticalSection
| The macro is used by the MCBSP driver to end the protection of its internal shared "resources" from MULTIPLE CORE access.
#define | Mcbsp_osalEnterSingleCoreCriticalSection Osal_mcbspEnterSingleCoreCriticalSection
| The macro is used by the MCBSP driver to protect its internal shared resources from SINGLE CORE MULTIPLE CONTEXT (thread or ISR) access. If all the MCBSP Driver APIs are being called from threads then this API could use semaphores. However if the MCBSP driver API's are being called from both ISR & Thread context then the critical section here would need to disable/enable interrupts.
#define | Mcbsp_osalExitSingleCoreCriticalSection Osal_mcbspExitSingleCoreCriticalSection
| The macro is used to denote the end of the protection of the internal shared resource from SINGLE CORE MULTIPLE CONTEXT access.
#define | Mcbsp_osalBeginMemAccess Osal_mcbspBeginMemAccess
| The macro is used by the MCBSP driver to indicate that a block of memory is about to be accessed. If the memory block is cached then this indicates that the application would need to ensure that the cache is updated with the data from the actual memory.
#define | Mcbsp_osalEndMemAccess Osal_mcbspEndMemAccess
| The macro is used by the MCBSP driver to indicate that the block of memory has finished being accessed. If the memory block is cached then the application would need to ensure that the contents of the cache are updated immediately to the actual memory.
#define | Mcbsp_osalQueueEmpty Osal_mcbspQueueEmpty
| The macro is used by the MCBSP driver to test for an empty queue.
#define | Mcbsp_osalQueueGet Osal_mcbspQueueGet
| The macro is used by the MCBSP driver to get an element from the front of queue. The function removes the element from the front of queue and returns a pointer to it.
#define | Mcbsp_osalQueuePut Osal_mcbspQueuePut
| The macro is used by the MCBSP driver to put an element at the end of queue.
#define | Mcbsp_osalWaitNBitClocks Osal_mcbspWaitNBitClocks
| The macro is used by the MCBSP driver to wait 'n' bit clocks to ensure proper synchronization internally.

## Define Documentation

#define Mcbsp_osalBeginMemAccess Osal_mcbspBeginMemAccess

The macro is used by the MCBSP driver to indicate that a block of memory is about to be accessed. If the memory block is cached then this indicates that the application would need to ensure that the cache is updated with the data from the actual memory.

Prototype: The following is the C prototype for the expected OSAL API.

           void  Osal_mcbspBeginMemAccess(void* ptr, uint32_t size)

Parameter
ptr - Pointer to the memory
size - Size of the memory being accessed.

Return Value
None

#define Mcbsp_osalCreateSem | ( |  | ) | Osal_mcbspCreateSem()

The macro is used by the MCBSP driver to create a semaphore for each MCBSP socket opened in blocking mode. Semaphores created should *initially* be created with a count of 0 i.e. unavailable.

Prototype: The following is the C prototype for the expected OSAL API.

           void* Osal_mcbspCreateSem(void);

Parameter
Not Applicable

Return Value
Semaphore Handle

#define Mcbsp_osalDataBufferFree | ( | X,
|  | Y |  | ) | Osal_mcbspDataBufferFree(X, Y)

The macro is used by the MCBSP driver to free a previously allocated block data buffer. This macro is used to clean up previously allocated data buffers and is invoked during the data path.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspDataBufferFree(void* ptr, uint32_t numBytes)

Parameter
Pointer to the block of memory to be cleaned up.
Size of the allocated memory which is being freed.

Return Value
Not applicable.

#define Mcbsp_osalDataBufferMalloc | ( | X |  | ) | Osal_mcbspDataBufferMalloc(X)

The macro is used by the MCBSP driver to allocate memory for the data buffers in Driver Managed Configuration. All data buffers should allocated should be in the global address space. This macro is invoked during the data path.

Prototype: The following is the C prototype for the expected OSAL API.

           void* Osal_mcbspDataBufferMalloc(uint32_t numBytes)

Parameter
Number of bytes to be allocated

Return Value
Pointer to the allocated block size

#define Mcbsp_osalDeleteSem | ( | X |  | ) | Osal_mcbspDeleteSem(X)

The macro is used by the MCBSP driver to delete a previously created semaphore. This is called when a MCBSP socket opened in blocking mode is being closed.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspDeleteSem(void* semHandle)

Parameter
Semaphore Handle returned by the create semaphore

Return Value
Not Applicable

#define Mcbsp_osalEndMemAccess Osal_mcbspEndMemAccess

The macro is used by the MCBSP driver to indicate that the block of memory has finished being accessed. If the memory block is cached then the application would need to ensure that the contents of the cache are updated immediately to the actual memory.

Prototype: The following is the C prototype for the expected OSAL API.

           void  Osal_mcbspEndMemAccess(void* ptr, uint32_t size)

Parameter
ptr - Pointer to the memory
size - Size of the memory

Return Value
None

#define Mcbsp_osalEnterMultipleCoreCriticalSection Osal_mcbspEnterMultipleCoreCriticalSection

The macro is used by the MCBSP Driver to protect its shared resources access from MULTIPLE CORES. This is required if the MCBSP Driver API's are being invoked from multiple cores. If this is not the case then these macros can be defined to be NOP.

Prototype: The following is the C prototype for the expected OSAL API.

           void* Osal_mcbspEnterMultipleCoreCriticalSection(void)

Parameter
None

Return Value
Opaque Handle used for holding critical section locking information

#define Mcbsp_osalEnterSingleCoreCriticalSection Osal_mcbspEnterSingleCoreCriticalSection

The macro is used by the MCBSP driver to protect its internal shared resources from SINGLE CORE MULTIPLE CONTEXT (thread or ISR) access. If all the MCBSP Driver APIs are being called from threads then this API could use semaphores. However if the MCBSP driver API's are being called from both ISR & Thread context then the critical section here would need to disable/enable interrupts.

Prototype: The following is the C prototype for the expected OSAL API.

           void* Osal_mcbspEnterSingleCoreCriticalSection()

Parameter
None

Return Value
Opaque Handle used for holding critical section locking information

#define Mcbsp_osalExitMultipleCoreCriticalSection Osal_mcbspExitMultipleCoreCriticalSection

The macro is used by the MCBSP driver to end the protection of its internal shared "resources" from MULTIPLE CORE access.

Prototype: The following is the C prototype for the expected OSAL API.

           void  Osal_mcbspExitMultipleCoreCriticalSection(void* critSectHandle)

Parameter
Opaque Handle used for holding critical section locking information

Return Value
None

#define Mcbsp_osalExitSingleCoreCriticalSection Osal_mcbspExitSingleCoreCriticalSection

The macro is used to denote the end of the protection of the internal shared resource from SINGLE CORE MULTIPLE CONTEXT access.

Prototype: The following is the C prototype for the expected OSAL API.

           void  Osal_mcbspExitSingleCoreCriticalSection(void* critSectHandle)

Parameter
critSectHandle - Opaque Handle used for holding critical section locking information

Return Value
None

#define Mcbsp_osalFree | ( | X,
|  | Y |  | ) | Osal_mcbspFree(X, Y)

The macro is used by the MCBSP driver to free a previously allocated block of memory.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspFree(void* ptr, uint32_t numBytes)

Parameter
Pointer to the block of memory to be cleaned up.
Size of the allocated memory which is being freed.

Return Value
Not applicable.

#define Mcbsp_osalLog Osal_mcbspLog

The macro is used by the MCBSP driver to log various messages.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspLog( char* fmt, ... )

Parameter
printf-style format string

Return Value
Not applicable.

#define Mcbsp_osalMalloc | ( | X |  | ) | Osal_mcbspMalloc(X)

The macro is used by the MCBSP driver to allocate memory The MCBSP driver uses this macro to allocate memory for its internal driver structures. This is invoked during the driver initialization and startup process.

Prototype: The following is the C prototype for the expected OSAL API.

           void* Osal_mcbspMalloc(uint32_t numBytes)

Parameter
Number of bytes to be allocated

Return Value
Pointer to the allocated block size

See also:
  Mcbsp_osalDataBufferMalloc

#define Mcbsp_osalPendSem | ( | X |  | ) | Osal_mcbspPendSem(X)

The macro is used by the MCBSP driver to pend on a semaphore This is called when an application tries to receive data on a blocking socket when there is no data available. Since all semaphores are initially created to be unavailable; this will cause the application to block.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspPendSem(void* semHandle)

Parameter
Semaphore Handle

Return Value
Not Applicable

#define Mcbsp_osalPostSem | ( | X |  | ) | Osal_mcbspPostSem(X)

The macro is used by the MCBSP driver to post the semaphore The driver posts the semaphore once data is received on a specific socket.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspPostSem(void* semHandle)

Parameter
Semaphore Handle

Return Value
Not Applicable

#define Mcbsp_osalQueueEmpty Osal_mcbspQueueEmpty

The macro is used by the MCBSP driver to test for an empty queue.

Prototype: The following is the C prototype for the expected OSAL API.

           void  Osal_mcbspQueueEmpty(void* handle)

Parameter
handle - Handle of a previously created Queue instance object

Return Value
TRUE - If the queue is empty

#define Mcbsp_osalQueueGet Osal_mcbspQueueGet

The macro is used by the MCBSP driver to get an element from the front of queue. The function removes the element from the front of queue and returns a pointer to it.

Prototype: The following is the C prototype for the expected OSAL API.

           void*  Osal_mcbspQueueGet(void* handle)

Parameter
handle - Handle of a previously created Queue instance object

Return Value
Handle (pointer) to former first element

#define Mcbsp_osalQueuePut Osal_mcbspQueuePut

The macro is used by the MCBSP driver to put an element at the end of queue.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspQueuePut(void* handle, Mcbsp_QueueElem* elem)

Parameter
handle - Handle of a previously created Queue instance object
elem - Pointer to new queue element

Return Value
None

#define Mcbsp_osalWaitNBitClocks Osal_mcbspWaitNBitClocks

The macro is used by the MCBSP driver to wait 'n' bit clocks to ensure proper synchronization internally.

Prototype: The following is the C prototype for the expected OSAL API.

           void Osal_mcbspWaitNBitClocks(uint32_t nticks)

Parameter
nticks - Number of bit clocks to wait

Return Value
None

Copyright 2012, Texas Instruments Incorporated