# SEM Functions
[Semaphore]

## Functions
CSL_IDEF_INLINE void | CSL_semSetEoi (Uint8 eoiVal)
CSL_IDEF_INLINE Uint8 | CSL_semAcquireDirect (Uint8 semNum)
CSL_IDEF_INLINE void | CSL_semAcquireIndirect (Uint8 semNum)
CSL_IDEF_INLINE Uint8 | CSL_semAcquireCombined (Uint8 semNum)
CSL_IDEF_INLINE void | CSL_semReleaseSemaphore (Uint8 semNum)
CSL_IDEF_INLINE Bool | CSL_semIsFree (Uint8 semNum)
CSL_IDEF_INLINE Uint8 | CSL_semGetResourceOwner (Uint8 semNum)
CSL_IDEF_INLINE Uint32 | CSL_semGetFlags (Uint8 masterId)
CSL_IDEF_INLINE void | CSL_semClearFlags (Uint8 masterId, Uint32 semFlags)
CSL_IDEF_INLINE Uint8 | CSL_semGetErrorCode (void)
CSL_IDEF_INLINE Uint8 | CSL_semGetErrorSemaphoreNumber (void)
CSL_IDEF_INLINE Uint8 | CSL_semGetErrorFaultID (void)
CSL_IDEF_INLINE void | CSL_semClearError (void)

## Function Documentation

CSL_IDEF_INLINE Uint8 CSL_semAcquireCombined | ( | Uint8 | semNum | ) |

============================================================================
CSL_semAcquireCombined

Description
This function acquires a semaphore for combined access.

Arguments

              semNum      Semaphore which is to be acquired.

Return Value
None

Pre Condition
None

Post Condition
Semaphore is acquired immediately if free else it is placed into the request queue to be acquired.

Reads
SEM_ISEM_FREE

Example

            Uint8 status;

            // Acquire the semaphore number 2.
            status = CSL_semAcquireCombined (2);

=============================================================================

CSL_IDEF_INLINE Uint8 CSL_semAcquireDirect | ( | Uint8 | semNum | ) |

============================================================================
CSL_semAcquireDirect

Description
This function acquires a semaphore for direct access.

Arguments

              semNum      Semaphore which is to be acquired.

Return Value
1 - Resource was available and has been allocated to the Master
0 - Resource was NOT available and has NOT been allocated to the Master

Pre Condition
None

Post Condition
Semaphore is allocated to the Master on Success.

Reads
SEM_SEM_FREE

Example

            Uint8 status;

            // Acquire the semaphore number 2.
            status = CSL_semAcquireDirect (2);

=============================================================================

CSL_IDEF_INLINE void CSL_semAcquireIndirect | ( | Uint8 | semNum | ) |

============================================================================
CSL_semAcquireIndirect

Description
This function acquires a semaphore for indirect access.

Arguments

              semNum      Semaphore which is to be acquired.

Return Value
None

Pre Condition
None

Post Condition
Semaphore is placed into the request queue to be acquired.

Writes
SEM_SEM_FREE=0

Example

            // Acquire the semaphore number 2.
            CSL_semAcquireIndirect (2);

=============================================================================

CSL_IDEF_INLINE void CSL_semClearError | ( | void |  | ) |

============================================================================
CSL_semClearError

Description
This function is used to clear the semaphore module error.

Arguments
None

Return Value
None

Pre Condition
None

Post Condition
None

Writes
SEM_SEMERR_CLEAR_CLRERR=1

Example

            Uint8  errCode;
            Uint8  semNumber;
            Uint8  faultId;

            // Check if there is an error which has been reported.
            errCode = CSL_semGetErrorCode();
            if (errCode != 0)
            {
                // Semaphore Module has reported an error; get the semaphore number.
                semNumber = CSL_semGetErrorSemaphoreNumber();

                // Get the fault id.
                faultId = CSL_semGetErrorFaultID();
                ...

                // Clear the error.
                CSL_semClearError ();
            }

=============================================================================

CSL_IDEF_INLINE void CSL_semClearFlags | ( | Uint8 | masterId,
|  | Uint32 | semFlags |
| ) |  |  |

============================================================================
CSL_semClearFlags

Description
This function is used by the host by the host to inform the SEM Module that the resource which had been marked as FREE has been processed by the host.

Arguments

              masterId      Master ID for which the SEMFLAG register is read.
              semFlags      Semaphore Flags retreived through the CSL_semGetFlags API.

Return Value
None

Pre Condition
None

Post Condition
None

Writes
SEM_SEMFLAGL_CLEAR

Affects
SEM_SEMFLAGL_CLEAR

Example

            Uint32  semFlags;

            // Read the bits of the semaphore flag register for master 0.
            semFlags = CSL_semGetFlags(0);
            ...
            // Clear the bits of the semaphore flag register for master 0.
            CSL_semClearFlags (0, semFlags);

=============================================================================

CSL_IDEF_INLINE Uint8 CSL_semGetErrorCode | ( | void |  | ) |

============================================================================
CSL_semGetErrorCode

Description
This function is used to get the Error code.

Arguments
None

Return Value
Error Code

Pre Condition
None

Post Condition
None

Reads
SEM_SEMERR_ERR

Example

            Uint8  errCode;

            // Check if there is an error which has been reported.
            errCode = CSL_semGetErrorCode();
            if (errCode != 0)
            {
                // Semaphore Module has reported an Error.
            }

=============================================================================

CSL_IDEF_INLINE Uint8 CSL_semGetErrorFaultID | ( | void |  | ) |

============================================================================
CSL_semGetErrorFaultID

Description
This function is used to get the resource owner which caused the error.

Arguments
None

Return Value
Resource Number which caused the error.

Pre Condition
None

Post Condition
None

Reads
SEM_SEMERR_FAULTID

Example

            Uint8  errCode;
            Uint8  semNumber;
            Uint8  faultId;

            // Check if there is an error which has been reported.
            errCode = CSL_semGetErrorCode();
            if (errCode != 0)
            {
                // Semaphore Module has reported an error; get the semaphore number.
                semNumber = CSL_semGetErrorSemaphoreNumber();

                // Get the fault id.
                faultId = CSL_semGetErrorFaultID();
                ...
            }

=============================================================================

CSL_IDEF_INLINE Uint8 CSL_semGetErrorSemaphoreNumber | ( | void |  | ) |

============================================================================
CSL_semGetErrorSemaphoreNumber

Description
This function is used to get the semaphore number which is in error.

Arguments
None

Return Value
Semaphore Number which caused the error.

Pre Condition
None

Post Condition
None

Reads
SEM_SEMERR_SEMNUM

Example

            Uint8  errCode;
            Uint8  semNumber;

            // Check if there is an error which has been reported.
            errCode = CSL_semGetErrorCode();
            if (errCode != 0)
            {
                // Semaphore Module has reported an error; get the semaphore number.
                semNumber = CSL_semGetErrorSemaphoreNumber();
                ...
            }

=============================================================================

CSL_IDEF_INLINE Uint32 CSL_semGetFlags | ( | Uint8 | masterId | ) |

============================================================================
CSL_semGetFlags

Description
This function returns the contents of the SEMFLAG register for a specific master. This is used in the indirect or combined access method to determine if a resource has been acquired. The corresponding bit indicates that the specific resource number which had been requested is now available.

Arguments

              masterId      Master ID for which the SEMFLAG register is read.

Return Value
Uint32

Pre Condition
None

Post Condition
None

Reads
SEM_SEMFLAGL_CLEAR

Example

            Uint32  semFlags;

            // Read the bits of the semaphore flag register for master 0.
            semFlags = CSL_semGetFlags(0);

=============================================================================

CSL_IDEF_INLINE Uint8 CSL_semGetResourceOwner | ( | Uint8 | semNum | ) |

============================================================================
CSL_semGetResourceOwner

Description
This function returns the resource owner for the specific semaphore.

Arguments

              semNum      Semaphore Number whose resource owner is to be retreived.

Return Value
Semaphore Resource Owner.

Pre Condition
None

Post Condition
None

Reads
SEM_QSEM_OWNER

Example

            Bool    isFree;
            Uint8   owner;

            // Check if Semaphore is available.
            isFree = CSL_semIsFree (2);
            if (isFree == FALSE)
            {
                // Resource is acquired. Get the owner
                owner = CSL_semGetResourceOwner(2);
            }

=============================================================================

CSL_IDEF_INLINE Bool CSL_semIsFree | ( | Uint8 | semNum | ) |

============================================================================
CSL_semIsFree

Description
This function checks if the specified semaphore is acquired or not?

Arguments

              semNum      Semaphore which is to be queried.

Return Value
TRUE - Semaphore is Free
FALSE - Semaphore is Available

Pre Condition
None

Post Condition
None

Reads
SEM_QSEM_FREE

Example

            Bool isFree;

            // Check if Semaphore is available.
            isFree = CSL_semIsFree (2);

=============================================================================

CSL_IDEF_INLINE void CSL_semReleaseSemaphore | ( | Uint8 | semNum | ) |

============================================================================
CSL_semReleaseSemaphore

Description
This function is used to release a sempahore which had been acquired previously.

Arguments

              semNum      Semaphore which is to be released.

Return Value
None

Pre Condition
CSL_semAcquireDirect() or CSL_semAcquireCombined() CSL_semAcquireIndirect() must be called.

Post Condition
Semaphore resource is freed up

Writes
SEM_SEM_FREE=1

Example

            // Acquire the semaphore using the direct method.
            CSL_semAcquireDirect (2);
            ...
            // Release the semaphore.
            CSL_semReleaseSemaphore (2);

=============================================================================

CSL_IDEF_INLINE void CSL_semSetEoi | ( | Uint8 | eoiVal | ) |

============================================================================
CSL_semSetEoi

Description
This function sets the SEM Module EOI Register to rearm the interrupt line after processing an existing interrupt.

Arguments

              eoiVal   Value to be written to the EOI register.

Return Value
None

Pre Condition
None

Writes
SEM_SEM_EOI_SELECT_INTERRUPT_REARM

Post Condition
Semaphore interrupts to the specific Master are reenabled.

Example

            // Reenable Semaphore interrupts for CPU Core 0.
            CSL_semSetEoi (semHandle, CSL_SEM_REARM_SEMINT0);

=============================================================================

Copyright 2012, Texas Instruments Incorporated