PSoC 6 Peripheral Driver Library

General Description

Functions are used in the driver.

Functions

cy_en_ipcsema_status_t Cy_IPC_Sema_Init (uint32_t ipcChannel, uint32_t count, uint32_t memPtr[])
 This function initializes the semaphores subsystem. More...
 
cy_en_ipcsema_status_t Cy_IPC_Sema_InitExt (uint32_t ipcChannel, cy_stc_ipc_sema_t *ipcSema)
 This function initializes the semaphores subsystem. More...
 
cy_en_ipcsema_status_t Cy_IPC_Sema_Set (uint32_t semaNumber, bool preemptable)
 This function tries to acquire a semaphore. More...
 
cy_en_ipcsema_status_t Cy_IPC_Sema_Clear (uint32_t semaNumber, bool preemptable)
 This functions tries to releases a semaphore. More...
 
cy_en_ipcsema_status_t Cy_IPC_Sema_Status (uint32_t semaNumber)
 This function returns the status of the semaphore. More...
 
uint32_t Cy_IPC_Sema_GetMaxSems (void)
 This function returns the number of semaphores in the semaphores subsystem. More...
 

Function Documentation

◆ Cy_IPC_Sema_Init()

cy_en_ipcsema_status_t Cy_IPC_Sema_Init ( uint32_t  ipcChannel,
uint32_t  count,
uint32_t  memPtr[] 
)

This function initializes the semaphores subsystem.

The user must create an array of unsigned 32-bit words to hold the semaphore bits. The number of semaphores will be the size of the array * 32. The total semaphores count will always be a multiple of 32.

Note
In a multi-CPU system this init function should be called with all initialized parameters on one CPU only to provide a pointer to SRAM that can be shared between all the CPUs in the system that will use semaphores. On other CPUs user must specify the IPC semaphores channel and pass 0 / NULL to count and memPtr parameters correspondingly.
Parameters
ipcChannelThe IPC channel number used for semaphores
countThe maximum number of semaphores to be supported (multiple of 32).
memPtrThis points to the array of (count/32) words that contain the semaphore data.
Returns
Status of the operation
Return values
CY_IPC_SEMA_SUCCESSSuccessfully initialized
CY_IPC_SEMA_BAD_PARAMMemory pointer is NULL and count is not zero, or count not multiple of 32
CY_IPC_SEMA_ERROR_LOCKEDCould not acquire semaphores IPC channel
Function Usage
/* Scenario: set up a single semaphore channel for use in communicating between two cores */
#define MY_IPC_CHAN_INDEX (8UL) /* Example of IPC channel index */
#if (CY_CPU_CORTEX_M0P)
/* The semaphore data is usually allocated in CM0+ memory space */
uint32_t mySemaData; /* So there are 32 semaphores */
if (CY_IPC_SEMA_SUCCESS != Cy_IPC_Sema_Init(MY_IPC_CHAN_INDEX, 32UL, &mySemaData))
{
/* Handle possible errors */
}
#else
/* Therefore, enother core (usually CM4) initializes semaphore subsystem without data pointer */
if (CY_IPC_SEMA_SUCCESS != Cy_IPC_Sema_Init(MY_IPC_CHAN_INDEX, 0UL, NULL))
{
/* Handle possible errors */
}
#endif /* (CY_CPU_CORTEX_M0P) */

◆ Cy_IPC_Sema_InitExt()

cy_en_ipcsema_status_t Cy_IPC_Sema_InitExt ( uint32_t  ipcChannel,
cy_stc_ipc_sema_t ipcSema 
)

This function initializes the semaphores subsystem.

The user must create an array of unsigned 32-bit words to hold the semaphore bits. The number of semaphores will be the size of the array * 32. The total semaphores count will always be a multiple of 32.

Note
In a multi-CPU system this init function should be called with all initialized parameters on one CPU only to provide a pointer to SRAM that can be shared between all the CPUs in the system that will use semaphores. On other CPUs user must specify the IPC semaphores channel and pass 0 / NULL to count and memPtr parameters correspondingly.
Parameters
ipcChannelThe IPC channel number used for semaphores
ipcSemaThis is configuration structure of the IPC semaphore. See cy_stc_ipc_sema_t.
Returns
Status of the operation
Return values
CY_IPC_SEMA_SUCCESSSuccessfully initialized
CY_IPC_SEMA_BAD_PARAMMemory pointer is NULL and count is not zero, or count not multiple of 32
CY_IPC_SEMA_ERROR_LOCKEDCould not acquire semaphores IPC channel

◆ Cy_IPC_Sema_Set()

cy_en_ipcsema_status_t Cy_IPC_Sema_Set ( uint32_t  semaNumber,
bool  preemptable 
)

This function tries to acquire a semaphore.

If the semaphore is not available, this function returns immediately with CY_IPC_SEMA_LOCKED.

It first acquires the IPC channel that is used for all the semaphores, sets the semaphore if it is cleared, then releases the IPC channel used for the semaphore.

Parameters
semaNumberThe semaphore number to acquire.
preemptableWhen this parameter is enabled the function can be preempted by another task or other forms of context switching in an RTOS environment.
Note
If preemptable is enabled (true), the user must ensure that there are no deadlocks in the system, which can be caused by an interrupt that occurs after the IPC channel is locked. Unless the user is ready to handle IPC channel locks correctly at the application level, set preemptable to false.
Returns
Status of the operation
Return values
CY_IPC_SEMA_SUCCESSThe semaphore was set successfully
CY_IPC_SEMA_LOCKEDThe semaphore channel is busy or locked by another process
CY_IPC_SEMA_NOT_ACQUIREDSemaphore was already set
CY_IPC_SEMA_OUT_OF_RANGEThe semaphore number is not valid
Function Usage
/* Scenario: set semaphore #MY_SEMA_NUM to inform the other core
* of the intention to perform some action.
*/
#define MY_SEMA_NUM (3UL)
switch (Cy_IPC_Sema_Set(MY_SEMA_NUM, false))
{
/* The semaphore is set successfully */
break;
/* The semaphore channel is busy or locked by another process */
break;
/* Semaphore is already set */
break;
/* The semaphore number is not valid */
break;
default: break;
}

◆ Cy_IPC_Sema_Clear()

cy_en_ipcsema_status_t Cy_IPC_Sema_Clear ( uint32_t  semaNumber,
bool  preemptable 
)

This functions tries to releases a semaphore.

It first acquires the IPC channel that is used for all the semaphores, clears the semaphore if it is set, then releases the IPC channel used for the semaphores.

Parameters
semaNumberThe index of the semaphore to release.
preemptableWhen this parameter is enabled the function can be preempted by another task or other forms of context switching in an RTOS environment.
Note
If preemptable is enabled (true), the user must ensure that there are no deadlocks in the system, which can be caused by an interrupt that occurs after the IPC channel is locked. Unless the user is ready to handle IPC channel locks correctly at the application level, set preemptable to false.
Returns
Status of the operation
Return values
CY_IPC_SEMA_SUCCESSThe semaphore was cleared successfully
CY_IPC_SEMA_NOT_ACQUIREDThe semaphore was already cleared
CY_IPC_SEMA_LOCKEDThe semaphore channel was semaphored or busy
CY_IPC_SEMA_OUT_OF_RANGEThe semaphore number is not valid
Function Usage
/* Scenario: action is completed. Clear the semaphore #MY_SEMA_NUM to inform
* the other core that the action is already completed.
*/
#define MY_SEMA_NUM (3UL)
switch (Cy_IPC_Sema_Clear(MY_SEMA_NUM, false))
{
/* The semaphore is cleared successfully */
break;
/* The semaphore channel is busy or locked by another process */
break;
/*Semaphore is already cleared */
break;
/* The semaphore number is not valid */
break;
default: break;
}

◆ Cy_IPC_Sema_Status()

cy_en_ipcsema_status_t Cy_IPC_Sema_Status ( uint32_t  semaNumber)

This function returns the status of the semaphore.

Parameters
semaNumberThe index of the semaphore to return status.
Returns
Status of the operation
Return values
CY_IPC_SEMA_STATUS_LOCKEDThe semaphore is in the set state.
CY_IPC_SEMA_STATUS_UNLOCKEDThe semaphore is in the cleared state.
CY_IPC_SEMA_OUT_OF_RANGEThe semaphore number is not valid
Function Usage
/* Scenario: check the state of semaphore #3. */
#define MY_SEMA_NUM (3UL)
switch (Cy_IPC_Sema_Status(MY_SEMA_NUM))
{
/* The semaphore is in the set state */
break;
/* The semaphore is in the cleared state */
break;
/* The semaphore number is not valid */
break;
default: break;
}

◆ Cy_IPC_Sema_GetMaxSems()

uint32_t Cy_IPC_Sema_GetMaxSems ( void  )

This function returns the number of semaphores in the semaphores subsystem.

Returns
Returns the semaphores quantity.
Function Usage
/* Scenario: get the maximum number of configured semaphores
* and check if the MY_SEMA_NUM is valid.
*/
#define MY_SEMA_NUM (3UL)
if (MY_SEMA_NUM < Cy_IPC_Sema_GetMaxSems())
{
/* The MY_SEMA_NUM is valid */
}