PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
Functions
PDL API Reference » IPC (Inter Process Communication) » IPC semaphores layer (IPC_SEMA)

## 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.

Either this function or Cy_IPC_Sema_InitExt must be called from each core that will use IPC semaphores.

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.

If semaphores will be used from within a secure processing environment, the secure processing environment must call either this function or Cy_IPC_Sema_InitExt with non-0 / NULL arguments, and it must do so before launching any other processing environment.

On cores that support DCache, user needs to make sure that the memPtr pointer passed to the Cy_IPC_Sema_Init function points to 32 byte aligned array of words that contain the semaphore data. User can use CY_ALIGN(32) macro for 32 byte alignment.

If semaphores will be used from within a secure processing environment, the secure processing environment must Cy_IPC_Sema_InitExt with non-0 / NULL arguments. This must be done even if this function or Cy_IPC_Sema_InitExt was previously called from another (non-secure) processing environment.

Parameters

  ipcChannel | The IPC channel number used for semaphores
  count | The maximum number of semaphores to be supported (multiple of 32).
  memPtr | This points to the array of (count/32) words that contain the semaphore data. This must be located in memory which is accessible to all processing environments which will interact with semaphores

Returns
  Status of the operation

Return values

  CY_IPC_SEMA_SUCCESS | Successfully initialized
  CY_IPC_SEMA_BAD_PARAM | Memory pointer is NULL and count is not zero, or count not multiple of 32
  CY_IPC_SEMA_ERROR_LOCKED | Could not acquire semaphores IPC channel

Function Usage
  /* Scenario: set up a single semaphore channel for use in communicating between two cores */
  #ifndef MY_IPC_CHAN_INDEX
  #define MY_IPC_CHAN_INDEX (8UL) /* Example of IPC channel index */
  #endif /* MY_IPC_CHAN_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, another core (usually CM4, CM7_0 or CM7_1) 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_SUCCESS
  @ CY_IPC_SEMA_SUCCESS
  No error has occurred.
  Definition: cy_ipc_sema.h:100
  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.
  Definition: cy_ipc_sema.c:104

## ◆ 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.

Either this function or Cy_IPC_Sema_Init must be called from each core that will use IPC semaphores.

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.

If semaphores will be used from within a secure processing environment, the secure processing environment must this function with non-0 / NULL arguments. This must be done even if this function or Cy_IPC_Sema_Init was previously called from another (non-secure) processing environment.

Parameters

  ipcChannel | The IPC channel number used for semaphores
  ipcSema | This is configuration structure of the IPC semaphore. This struct must be located in memory which is accessible to all processing environments which will interact with semaphores. See cy_stc_ipc_sema_t.

Returns
  Status of the operation

Return values

  CY_IPC_SEMA_SUCCESS | Successfully initialized
  CY_IPC_SEMA_BAD_PARAM | Memory pointer is NULL and count is not zero, or count not multiple of 32
  CY_IPC_SEMA_ERROR_LOCKED | Could 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

  semaNumber | The semaphore number to acquire.

Note
  There are two shared memories. One is a secure memory area which is accessible from secure domains only. Another memory area which is accessible from both secure and non-secure domains. To use secure area for semaphore, user has to use CY_IPC_SEMA_SEC macro to create a secure semaphore.

Parameters

  preemptable | When 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_SUCCESS | The semaphore was set successfully
  CY_IPC_SEMA_LOCKED | The semaphore channel is busy or locked by another process
  CY_IPC_SEMA_NOT_ACQUIRED | Semaphore was already set
  CY_IPC_SEMA_OUT_OF_RANGE | The 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))
  {
  case CY_IPC_SEMA_SUCCESS:
  /* The semaphore is set successfully */
  break;
  case CY_IPC_SEMA_LOCKED:
  /* The semaphore channel is busy or locked by another process */
  break;
  case CY_IPC_SEMA_NOT_ACQUIRED:
  /* Semaphore is already set */
  break;
  case CY_IPC_SEMA_OUT_OF_RANGE:
  /* The semaphore number is not valid */
  break;
  default: break;
  }
  CY_IPC_SEMA_OUT_OF_RANGE
  @ CY_IPC_SEMA_OUT_OF_RANGE
  Semaphore API return when semaphore number is out of the range.
  Definition: cy_ipc_sema.h:108
  CY_IPC_SEMA_NOT_ACQUIRED
  @ CY_IPC_SEMA_NOT_ACQUIRED
  Semaphore API return when IPC channel was not acquired.
  Definition: cy_ipc_sema.h:111
  CY_IPC_SEMA_LOCKED
  @ CY_IPC_SEMA_LOCKED
  Semaphore API return status when semaphore channel is busy or locked by another process.
  Definition: cy_ipc_sema.h:114
  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.
  Definition: cy_ipc_sema.c:336

## ◆ 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

  semaNumber | The index of the semaphore to release.

Note
  There are two shared memories. One is a secure memory area which is accessible from secure domains only. Another memory area which is accessible from both secure and non-secure domains. To use secure area for semaphore, user has to use CY_IPC_SEMA_SEC macro to create a secure semaphore.

Parameters

  preemptable | When 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_SUCCESS | The semaphore was cleared successfully
  CY_IPC_SEMA_NOT_ACQUIRED | The semaphore was already cleared
  CY_IPC_SEMA_LOCKED | The semaphore channel was semaphored or busy
  CY_IPC_SEMA_OUT_OF_RANGE | The 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))
  {
  case CY_IPC_SEMA_SUCCESS:
  /* The semaphore is cleared successfully */
  break;
  case CY_IPC_SEMA_LOCKED:
  /* The semaphore channel is busy or locked by another process */
  break;
  case CY_IPC_SEMA_NOT_ACQUIRED:
  /*Semaphore is already cleared */
  break;
  case CY_IPC_SEMA_OUT_OF_RANGE:
  /* 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.
  Definition: cy_ipc_sema.c:455

## ◆ 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

  semaNumber | The index of the semaphore to return status.

Note
  There are two shared memories. One is a secure memory area which is accessible from secure domains only. Another memory area which is accessible from both secure and non-secure domains. To use secure area for semaphore, user has to use CY_IPC_SEMA_SEC macro to create a secure semaphore.

Returns
  Status of the operation

Return values

  CY_IPC_SEMA_STATUS_LOCKED | The semaphore is in the set state.
  CY_IPC_SEMA_STATUS_UNLOCKED | The semaphore is in the cleared state.
  CY_IPC_SEMA_OUT_OF_RANGE | The 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))
  {
  case CY_IPC_SEMA_STATUS_LOCKED:
  /* The semaphore is in the set state */
  break;
  case CY_IPC_SEMA_STATUS_UNLOCKED:
  /* The semaphore is in the cleared state */
  break;
  case CY_IPC_SEMA_OUT_OF_RANGE:
  /* The semaphore number is not valid */
  break;
  default: break;
  }
  CY_IPC_SEMA_STATUS_LOCKED
  @ CY_IPC_SEMA_STATUS_LOCKED
  Semaphore status return that the semaphore is set.
  Definition: cy_ipc_sema.h:116
  CY_IPC_SEMA_STATUS_UNLOCKED
  @ CY_IPC_SEMA_STATUS_UNLOCKED
  Semaphore status return that the semaphore is cleared.
  Definition: cy_ipc_sema.h:118
  Cy_IPC_Sema_Status
  cy_en_ipcsema_status_t Cy_IPC_Sema_Status(uint32_t semaNumber)
  This function returns the status of the semaphore.
  Definition: cy_ipc_sema.c:558

## ◆ 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 */
  }
  Cy_IPC_Sema_GetMaxSems
  uint32_t Cy_IPC_Sema_GetMaxSems(void)
  This function returns the number of semaphores in the semaphores subsystem.
  Definition: cy_ipc_sema.c:629