PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
Functions
PDL API Reference » SysLib (System Library)

## General Description

## Functions
void | Cy_SysLib_Delay (uint32_t milliseconds)
| The function delays by the specified number of milliseconds. More...
void | Cy_SysLib_DelayUs (uint16_t microseconds)
| The function delays by the specified number of microseconds. More...
void | Cy_SysLib_Rtos_Delay (uint32_t milliseconds)
| The function is same as Cy_SysLib_Delay. More...
void | Cy_SysLib_Rtos_DelayUs (uint16_t microseconds)
| The function is same as Cy_SysLib_DelayUs. More...
void | Cy_SysLib_DelayCycles (uint32_t cycles)
| Delays for the specified number of cycles. More...
void | Cy_SysLib_Halt (uint32_t reason)
| This function halts the CPU but only the CPU which calls the function. More...
void | Cy_SysLib_AssertFailed (const char_t *file, uint32_t line)
| This function stores the ASSERT location of the file name (including path to file) and line number in a non-zero init area for debugging. More...
uint64_t | Cy_SysLib_GetUniqueId (void)
| This function returns the silicon unique ID. More...
cy_en_syslib_status_t | Cy_SysLib_ResetBackupDomain (void)
| This function resets the backup domain power to avoid the ILO glitch. More...
uint32_t | Cy_SysLib_GetResetReason (void)
| The function returns the cause for the latest reset(s) that occurred in the system. More...
void | Cy_SysLib_ClearResetReason (void)
| This function clears the values of RES_CAUSE_EXTEND, RES_CAUSE and RES_CAUSE2. More...
CY_SECTION_INIT_CODECOPY_BEGIN __STATIC_INLINE cy_en_syslib_status_t | Cy_SysLib_GetResetStatus (void)
| This function returns the BACKUP->RESET bit value. More...
CY_SECTION_INIT_CODECOPY_END void | Cy_SysLib_FaultHandler (uint32_t const *faultStackAddr)
| This function stores the ARM Cortex registers into a non-zero init area for debugging. More...
void | Cy_SysLib_ProcessingFault (void)
| This function determines how to process the current fault state. More...
void | Cy_SysLib_SetWaitStates (bool ulpMode, uint32_t clkHfMHz)
| Sets the number of clock cycles the cache will wait for, before it samples data coming back from ROM, SRAM, and Flash. More...
uint32_t | Cy_SysLib_EnterCriticalSection (void)
| Cy_SysLib_EnterCriticalSection disables interrupts and returns a value indicating whether the interrupts were previously enabled. More...
void | Cy_SysLib_ExitCriticalSection (uint32_t savedIntrStatus)
| Re-enables the interrupts if they were enabled before Cy_SysLib_EnterCriticalSection() was called. More...
uint8_t | Cy_SysLib_GetDeviceRevision (void)
| This function returns a device Revision ID. More...
uint16_t | Cy_SysLib_GetDevice (void)
| This function returns a device Family ID. More...
cy_en_syslib_lcs_mode_t | Cy_SysLib_GetDeviceLCS (cy_syslib_lcs_data_t *base)
| This function returns LCS of Device. More...
void | Cy_Syslib_SetWarmBootEntryPoint (uint32_t *entryPoint, bool enable)
| This function will set Warm boot entry point address to a location read by BootROM. More...
bool | Cy_SysLib_IsDSRAMWarmBootEntry (void)
| This function will return true if the system woke up(From DS-RAM) through Warm boot, else it will return false. More...
void | Cy_SysLib_ClearDSRAMWarmBootEntryStatus (void)
| This function clears the Warm Boot entry Status flag.
bool | Cy_Syslib_IsMemCacheable (MPU_Type *mpu, uint32_t addr, uint32_t size)
| This function checks if the memory address and the size passed falls in the non-cacheable region or not. More...

## Function Documentation

## ◆ Cy_SysLib_Delay()

void Cy_SysLib_Delay | ( | uint32_t | milliseconds | ) |

The function delays by the specified number of milliseconds.

By default, the number of cycles to delay is calculated based on the SystemCoreClock.

Parameters

  milliseconds | The number of milliseconds to delay.

Note
  The function calls Cy_SysLib_DelayCycles() API to generate a delay. If the function parameter (milliseconds) is bigger than CY_DELAY_MS_OVERFLOW constant, then an additional loop runs to prevent an overflow in parameter passed to Cy_SysLib_DelayCycles() API.
  The Calibration factor is to correct the delay in cases where CPU's use branch prediction, currently applicable for only devices with a CM7 processor.
  The accuracy of the delay functions depends on the value of the global variable SystemCoreClock. If the system clock configuration is changed at runtime or if the project does not call cycfg_config_init() then you must call SystemCoreClockUpdate to refresh the SystemCoreClock variable. Failing to do so may result in incorrect delay durations.

## ◆ Cy_SysLib_DelayUs()

void Cy_SysLib_DelayUs | ( | uint16_t | microseconds | ) |

The function delays by the specified number of microseconds.

By default, the number of cycles to delay is calculated based on the SystemCoreClock.

Parameters

  microseconds | The number of microseconds to delay.

Note
  If the CPU frequency is a small non-integer number, the actual delay can be up to twice as long as the nominal value. The actual delay cannot be shorter than the nominal one.
  The Calibration factor is to correct the delay in cases where CPU's use branch prediction, currently applicable for only devices with a CM7 processor.
  The accuracy of the delay functions depends on the value of the global variable SystemCoreClock. If the system clock configuration is changed at runtime or if the project does not call cycfg_config_init() then you must call SystemCoreClockUpdate to refresh the SystemCoreClock variable. Failing to do so may result in incorrect delay durations.

## ◆ Cy_SysLib_Rtos_Delay()

void Cy_SysLib_Rtos_Delay | ( | uint32_t | milliseconds | ) |

The function is same as Cy_SysLib_Delay.

However, this API is declared WEAK providing option for user to overwrite the implementation based on target RTOS.

Parameters

  milliseconds | The number of milliseconds to delay.

## ◆ Cy_SysLib_Rtos_DelayUs()

void Cy_SysLib_Rtos_DelayUs | ( | uint16_t | microseconds | ) |

The function is same as Cy_SysLib_DelayUs.

However, this API is declared WEAK providing option for user to overwrite the implementation based on target RTOS.

Parameters

  microseconds | The number of microseconds to delay.

## ◆ Cy_SysLib_DelayCycles()

void Cy_SysLib_DelayCycles | ( | uint32_t | cycles | ) |

Delays for the specified number of cycles.

The function is implemented in the assembler for each supported compiler.

Parameters

  cycles | The number of cycles to delay.

Note
  While using for devices with a CM7 CPU, where the CPU supports branch prediction, this API needs to be called as below Cy_SysLib_DelayCycles(cycles * CY_SYSLIB_DELAY_CALIBRATION_FACTOR); For Example:- CY_SYSLIB_DELAY_CALIBRATION_FACTOR = 1 for CM0P, CM33 and CM4. CY_SYSLIB_DELAY_CALIBRATION_FACTOR = 2 for CM7_0 and CM7_1.
  The accuracy of the delay functions depends on the value of the global variable SystemCoreClock. If the system clock configuration is changed at runtime or if the project does not call cycfg_config_init() then you must call SystemCoreClockUpdate to refresh the SystemCoreClock variable. Failing to do so may result in incorrect delay durations.

## ◆ Cy_SysLib_Halt()

void Cy_SysLib_Halt | ( | uint32_t | reason | ) |

This function halts the CPU but only the CPU which calls the function.

It doesn't affect other CPUs.

Parameters

  reason | The value to be used during debugging.

Note
  The function executes the BKPT instruction for halting CPU and is intended to be used for the debug purpose. A regular use case requires Debugger attachment before the function call. The BKPT instruction causes the CPU to enter the Debug state. Debug tools can use this to investigate the system state, when the instruction at a particular address is reached.
  Execution of a BKPT instruction without a debugger attached produces a fault. The fault results in the HardFault exception being taken or causes a Lockup state if it occurs in the NMI or HardFault handler. The default HardFault handler make a software reset if the build option is the release mode (NDEBUG). If the build option is the debug mode, the system will stay in the infinite loop of the Cy_SysLib_ProcessingFault() function.

## ◆ Cy_SysLib_AssertFailed()

void Cy_SysLib_AssertFailed | ( | const char_t * | file,
|  | uint32_t | line
| ) |  |

This function stores the ASSERT location of the file name (including path to file) and line number in a non-zero init area for debugging.

Also it calls the Cy_SysLib_Halt() function to halt the processor.

Parameters

  file | The file name of the ASSERT location.
  line | The line number of the ASSERT location.

Note
  A stored file name and line number could be accessed by cy_assertFileName and cy_assertLine global variables.
  This function has the WEAK option, so the user can redefine the function for a custom processing.

## ◆ Cy_SysLib_GetUniqueId()

uint64_t Cy_SysLib_GetUniqueId | ( | void |  | ) |

This function returns the silicon unique ID.

The ID includes Die lot[3]#, Die Wafer#, Die X, Die Y, Die Sort#, Die Minor and Die Year.

Returns
  A combined 64-bit unique ID. [63:57] - DIE_YEAR [56:56] - DIE_MINOR [55:48] - DIE_SORT [47:40] - DIE_Y [39:32] - DIE_X [31:24] - DIE_WAFER [23:16] - DIE_LOT[2] [15: 8] - DIE_LOT[1] [ 7: 0] - DIE_LOT[0]

Note
  This API is available for devices having M4CPUSS, CY_IP_M33SYSCPUSS and CY_IP_M55APPCPUSS IP.
  For CY_IP_M33SYSCPUSS IP, EFUSE must be in enabled state before calling this API.
  For Cores with Security extention, Trust Zone configuration should be done before calling this API.

## ◆ Cy_SysLib_ResetBackupDomain()

cy_en_syslib_status_t Cy_SysLib_ResetBackupDomain | ( | void |  | ) |

This function resets the backup domain power to avoid the ILO glitch.

The glitch can occur when the device is reset due to POR/BOD/XRES while the backup voltage is supplied into the system.

Note
  Writing 1 to BACKUP->RESET resets the backup logic. Hardware clears it when the reset is complete. After setting the register, this function reads the register immediately for returning the result of the backup domain reset state. The reading register is important because the Read itself takes multiple AHB clock cycles, and the reset is actually finishing during that time. Use Cy_SysLib_GetResetStatus to check the BACKUP->RESET before any other BACKUP register write.
  This function also resets the WCO trimming value - use the Cy_SysLib_GetWcoTrim and Cy_SysLib_SetWcoTrim to store/restore the WCO trimming value.

Returns
  CY_SYSLIB_SUCCESS, if BACKUP->RESET read-back is 0. Otherwise returns CY_SYSLIB_INVALID_STATE.

Function Usage
  /* Scenario: there is a need to reset backup domain and WCO is used */
  uint32_t wcoTrim = Cy_SysLib_GetWcoTrim(); /* Store the WCO trim value */
  if (CY_SYSLIB_SUCCESS != Cy_SysLib_ResetBackupDomain())
  {
  Cy_SysLib_DelayUs(1U); /* 1 us delay should be enough */
  if (CY_SYSLIB_SUCCESS != Cy_SysLib_GetResetStatus())
  {
  /* Reset bit is not cleared too long - check the CLK_BAK */
  }
  }
  Cy_SysLib_SetWcoTrim(wcoTrim); /* Restore the WCO trim value */
  CY_SYSLIB_SUCCESS
  @ CY_SYSLIB_SUCCESS
  The success status code.
  Definition: cy_syslib.h:239
  Cy_SysLib_DelayUs
  void Cy_SysLib_DelayUs(uint16_t microseconds)
  The function delays by the specified number of microseconds.
  Definition: cy_syslib.c:119
  Cy_SysLib_GetResetStatus
  CY_SECTION_INIT_CODECOPY_BEGIN __STATIC_INLINE cy_en_syslib_status_t Cy_SysLib_GetResetStatus(void)
  This function returns the BACKUP->RESET bit value.
  Definition: cy_syslib.h:1157
  Cy_SysLib_ResetBackupDomain
  cy_en_syslib_status_t Cy_SysLib_ResetBackupDomain(void)
  This function resets the backup domain power to avoid the ILO glitch.
  Definition: cy_syslib.c:181

## ◆ Cy_SysLib_GetResetReason()

uint32_t Cy_SysLib_GetResetReason | ( | void |  | ) |

The function returns the cause for the latest reset(s) that occurred in the system.

The reset causes include system faults and device reset on a wakeup from Hibernate mode. For M33SYSCPUSS IP, the reset causes also include an HFCLK error. The return results are consolidated reset causes from reading RES_CAUSE, RES_CAUSE2 and PWR_HIBERNATE token registers.

Returns
  The cause of a system reset. Return values to be checked as per the CPUSS IP of the device.

Name in M4CPUSS IP | Name in M33SYSCPUSS IP | Name in M7CPUSS IP | Value
--- | --- | --- | ---
CY_SYSLIB_RESET_HWWDT | CY_SYSLIB_RESET_HWWDT | CY_SYSLIB_RESET_HWWDT | 0x00001 (bit0)
CY_SYSLIB_RESET_ACT_FAULT | CY_SYSLIB_RESET_ACT_FAULT | CY_SYSLIB_RESET_ACT_FAULT | 0x00002 (bit1)
CY_SYSLIB_RESET_DPSLP_FAULT | CY_SYSLIB_RESET_DPSLP_FAULT | CY_SYSLIB_RESET_DPSLP_FAULT | 0x00004 (bit2)
CY_SYSLIB_RESET_TC_DBGRESET | CY_SYSLIB_RESET_CSV_WCO_LOSS | CY_SYSLIB_RESET_TC_DBGRESET | 0x00008 (bit3)
CY_SYSLIB_RESET_SOFT | CY_SYSLIB_RESET_SOFT | CY_SYSLIB_RESET_SOFT | 0x00010 (bit4)
CY_SYSLIB_RESET_SWWDT0 | CY_SYSLIB_RESET_SWWDT0 | CY_SYSLIB_RESET_SWWDT0 | 0x00020 (bit5)
CY_SYSLIB_RESET_SWWDT1 | CY_SYSLIB_RESET_SWWDT1 | CY_SYSLIB_RESET_SWWDT1 | 0x00040 (bit6)
CY_SYSLIB_RESET_SWWDT2 | CY_SYSLIB_RESET_SWWDT2 | CY_SYSLIB_RESET_SWWDT2 | 0x00080 (bit7)
CY_SYSLIB_RESET_SWWDT3 | CY_SYSLIB_RESET_SWWDT3 | CY_SYSLIB_RESET_SWWDT3 | 0x00100 (bit8)
|  |  | 0x00200 (bit9)
|  |  | 0x00400 (bit10)
|  |  | 0x00800 (bit11)
|  |  | 0x01000 (bit12)
|  |  | 0x02000 (bit13)
|  |  | 0x04000 (bit14)
|  |  | 0x08000 (bit15)
| CY_SYSLIB_RESET_HFCLK_LOSS | CY_SYSLIB_RESET_XRES | 0x10000 (bit16)
| CY_SYSLIB_RESET_HFCLK_ERR | CY_SYSLIB_RESET_BODVDDD | 0x20000 (bit17)
|  | CY_SYSLIB_RESET_BODVDDA | 0x40000 (bit18)
|  | CY_SYSLIB_RESET_BODVCCD | 0x80000 (bit19)
|  | CY_SYSLIB_RESET_OVDVDDD | 0x100000 (bit20)
|  | CY_SYSLIB_RESET_OVDVDDA | 0x200000 (bit21)
|  | CY_SYSLIB_RESET_OVDVCCD | 0x400000 (bit22)
|  | CY_SYSLIB_RESET_OCD_ACT_LINREG | 0x800000 (bit23)
|  | CY_SYSLIB_RESET_OCD_DPSLP_LINREG | 0x1000000 (bit24)
|  | CY_SYSLIB_RESET_OCD_REGHC | 0x2000000 (bit25)
|  | CY_SYSLIB_RESET_PMIC | 0x4000000 (bit26)
|  |  | 0x8000000 (bit27)
|  | CY_SYSLIB_RESET_PXRES | 0x10000000 (bit28)
|  | CY_SYSLIB_RESET_STRUCT_XRES | 0x20000000 (bit29)
|  | CY_SYSLIB_RESET_PORVDDD | 0x40000000 (bit30)
CY_SYSLIB_RESET_HIB_WAKEUP | CY_SYSLIB_RESET_HIB_WAKEUP | CY_SYSLIB_RESET_HIB_WAKEUP | 0x80000000 (bit31)

Note
  This not is available for devices having M33SYSCPUSS IP CY_SYSLIB_RESET_CSV_WCO_LOSS, CY_SYSLIB_RESET_HFCLK_LOSS and CY_SYSLIB_RESET_HFCLK_ERR causes of a system reset available only if WCO CSV present in the device.

## ◆ Cy_SysLib_ClearResetReason()

void Cy_SysLib_ClearResetReason | ( | void |  | ) |

This function clears the values of RES_CAUSE_EXTEND, RES_CAUSE and RES_CAUSE2.

Also it clears PWR_HIBERNATE token, which indicates reset event on waking up from HIBERNATE.

## ◆ Cy_SysLib_GetResetStatus()

CY_SECTION_INIT_CODECOPY_BEGIN __STATIC_INLINE cy_en_syslib_status_t Cy_SysLib_GetResetStatus | ( | void |  | ) |

This function returns the BACKUP->RESET bit value.

It is reused by the Cy_SysLib_ResetBackupDomain itself and also intended to check for CY_SYSLIB_SUCCESS in loop after the Cy_SysLib_ResetBackupDomain call.

Note
  Writing 1 to BACKUP->RESET resets the backup logic. Hardware clears it when the reset is complete. After setting the register, this function reads the register immediately for returning the result of the backup domain reset state. The reading register is important because the Read itself takes multiple AHB clock cycles, and the reset is actually finishing during that time.

Returns
  CY_SYSLIB_SUCCESS, if BACKUP->RESET read-back is 0. Otherwise returns CY_SYSLIB_INVALID_STATE.

Function Usage
  if (CY_SYSLIB_SUCCESS != Cy_SysLib_ResetBackupDomain())
  {
  Cy_SysLib_DelayUs(1U); /* 1 us delay should be enough */
  if (CY_SYSLIB_SUCCESS != Cy_SysLib_GetResetStatus())
  {
  /* Reset bit is not cleared too long - check the CLK_BAK */
  }
  }

## ◆ Cy_SysLib_FaultHandler()

CY_SECTION_INIT_CODECOPY_END void Cy_SysLib_FaultHandler | ( | uint32_t const * | faultStackAddr | ) |

This function stores the ARM Cortex registers into a non-zero init area for debugging.

This function calls Cy_SysLib_ProcessingFault() after storing all information.

Parameters

  faultStackAddr | The address of the stack pointer, indicates the lowest address in the fault stack frame to be stored.

Note
  This function stores the fault stack frame only for the first occurred fault.
  The PDL doesn't provide an API to analyze the stored register values. The user has to add additional functions for the analysis, if necessary.
  The CY_ARM_FAULT_DEBUG macro defines if the Fault Handler is enabled. By default it is set to CY_ARM_FAULT_DEBUG_ENABLED and enables the Fault Handler. If there is a necessity to save memory or have some specific custom handler, etc. then CY_ARM_FAULT_DEBUG should be redefined as CY_ARM_FAULT_DEBUG_DISABLED. To do this, the following definition should be added to the compiler Command Line (through the project Build Settings): "-D CY_ARM_FAULT_DEBUG=0".

## ◆ Cy_SysLib_ProcessingFault()

void Cy_SysLib_ProcessingFault | ( | void |  | ) |

This function determines how to process the current fault state.

By default in case of exception the system will stay in the infinite loop of this function.

Note
  This function has the WEAK option, so the user can redefine the function behavior for a custom processing. For example, the function redefinition could be constructed from fault stack processing and NVIC_SystemReset() function call.

## ◆ Cy_SysLib_SetWaitStates()

void Cy_SysLib_SetWaitStates | ( | bool | ulpMode,
|  | uint32_t | clkHfMHz
| ) |  |

Sets the number of clock cycles the cache will wait for, before it samples data coming back from ROM, SRAM, and Flash.

Call this function before increasing the HFClk0 High Frequency clock. Call this function optionally after lowering the HFClk0 High Frequency clock in order to improve the CPU performance.

Also, call this function before switching the core supply regulator voltage (LDO or SIMO Buck) from 1.1V to 0.9V. Call this function optionally after switching the core supply regulator voltage from 0.9V to 1.1V in order to improve the CPU performance.

Parameters

  ulpMode | The device power mode. true if the device should be switched to the ULP mode (nominal voltage of the core supply regulator should be switched to 0.9V); false if the device should be switched to the LP mode (nominal voltage of the core supply regulator should be switched to 1.1V).

Note
  Refer to the device TRM for the low power modes description.

Parameters

  clkHfMHz | The HFClk0 clock frequency in MHz. Specifying a frequency above the supported maximum will set the wait states as for the maximum frequency.

Warning
  Delay functions have no effect if called from non-secure code. The CPU frequency cannot be changed in non-secure code.

## ◆ Cy_SysLib_EnterCriticalSection()

uint32_t Cy_SysLib_EnterCriticalSection | ( | void |  | ) |

Cy_SysLib_EnterCriticalSection disables interrupts and returns a value indicating whether the interrupts were previously enabled.

Returns
  Returns the current interrupt status. Returns 0 if the interrupts were previously enabled or 1 if the interrupts were previously disabled.

Note
  Implementation of Cy_SysLib_EnterCriticalSection manipulates the IRQ enable bit with interrupts still enabled.

## ◆ Cy_SysLib_ExitCriticalSection()

void Cy_SysLib_ExitCriticalSection | ( | uint32_t | savedIntrStatus | ) |

Re-enables the interrupts if they were enabled before Cy_SysLib_EnterCriticalSection() was called.

The argument should be the value returned from Cy_SysLib_EnterCriticalSection().

Parameters

  savedIntrStatus | Puts the saved interrupts status returned by the Cy_SysLib_EnterCriticalSection().

## ◆ Cy_SysLib_GetDeviceRevision()

uint8_t Cy_SysLib_GetDeviceRevision | ( | void |  | ) |

This function returns a device Revision ID.

Returns
  A device Revision ID.

## ◆ Cy_SysLib_GetDevice()

uint16_t Cy_SysLib_GetDevice | ( | void |  | ) |

This function returns a device Family ID.

Returns
  A device Family ID.

## ◆ Cy_SysLib_GetDeviceLCS()

cy_en_syslib_lcs_mode_t Cy_SysLib_GetDeviceLCS | ( | cy_syslib_lcs_data_t * | base | ) |

This function returns LCS of Device.

Parameters

  base | The pointer to the SRSS instance.

Returns
  cy_en_syslib_lcs_mode_t

## ◆ Cy_Syslib_SetWarmBootEntryPoint()

void Cy_Syslib_SetWarmBootEntryPoint | ( | uint32_t * | entryPoint,
|  | bool | enable
| ) |  |

This function will set Warm boot entry point address to a location read by BootROM.

This function is used only before entering DeepSleep-RAM and not effective in any other sleep mode. Before entering CY_SYSPM_MODE_DEEPSLEEP_RAM, user needs to set entry point to a function located in RAM Image using Cy_Syslib_SetWarmBootEntryPoint(), refer Cy_SysPm_SetDeepSleepMode().

Parameters

  entryPoint | Address of the function that needs to be entered after WARM boot.
  enable | Enables/Disables debugging control after DS-RAM wakeup i.e. warmboot

## ◆ Cy_SysLib_IsDSRAMWarmBootEntry()

bool Cy_SysLib_IsDSRAMWarmBootEntry | ( | void |  | ) |

This function will return true if the system woke up(From DS-RAM) through Warm boot, else it will return false.

Returns
  Warm Boot Status.

## ◆ Cy_Syslib_IsMemCacheable()

bool Cy_Syslib_IsMemCacheable | ( | MPU_Type * | mpu,
|  | uint32_t | addr,
|  | uint32_t | size
| ) |  |

This function checks if the memory address and the size passed falls in the non-cacheable region or not.

Parameters

  mpu | Address of the MPU
  addr | Address of the memory to be checked
  size | Size of the memory to be checked

Note
  This API is available for CM55 core devices.