cy_syslib_8h¶

Provides an API declaration of the SysLib driver.

Version: 2.90

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Copyright: Copyright 2016-2021 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_CPU_CORTEX_M0P¶

CM0+ core CPU Code.

note

This macro is available for devices having M4CPUSS IP.

CY_CPU_CORTEX_M4¶

CM4 core CPU Code.

note

This macro is available for devices having M4CPUSS IP.

CY_ARM_FAULT_DEBUG_DISABLED¶

The macro to disable the Fault Handler.

note

This macro is available for devices having M4CPUSS IP.

CY_ARM_FAULT_DEBUG_ENABLED¶

The macro to enable the Fault Handler.

note

This macro is available for devices having M4CPUSS IP.

CY_ARM_FAULT_DEBUG¶

The macro defines if the Fault Handler is enabled.

note

This macro is available for devices having M4CPUSS IP. Enabled by default.

CY_PDL_DRV_ID(id)¶: Get the software PDL module ID.

CY_SYSLIB_ID¶: SYSLIB PDL ID.

CY_SYSLIB_DRV_VERSION_MAJOR¶: The driver major version.

CY_SYSLIB_DRV_VERSION_MINOR¶: The driver minor version.

CY_SECTION_RAMFUNC_BEGIN¶: Define start of the function placed to the SRAM area by the linker.

CY_SECTION_RAMFUNC_END¶: Define end of the function placed to the SRAM area by the linker.

CY_SECTION_SHAREDMEM¶: Define variable to be placed to the shared SRAM area by the linker.

CY_MAX_FILE_NAME_SIZE¶: The max size of the file name which stores the ASSERT location.

CY_R0_Pos¶: The position of the R0 content in a fault structure.

CY_R1_Pos¶: The position of the R1 content in a fault structure.

CY_R2_Pos¶: The position of the R2 content in a fault structure.

CY_R3_Pos¶: The position of the R3 content in a fault structure.

CY_R12_Pos¶: The position of the R12 content in a fault structure.

CY_LR_Pos¶: The position of the LR content in a fault structure.

CY_PC_Pos¶: The position of the PC content in a fault structure.

CY_PSR_Pos¶: The position of the PSR content in a fault structure.

CY_ASSERT_CLASS_1¶: Class 1 - The highest class, safety-critical functions which rely on parameters that could be changed between different PSoC devices.

CY_ASSERT_CLASS_2¶: Class 2 - Functions that have fixed limits such as counter periods (16-bits/32-bits etc.)

CY_ASSERT_CLASS_3¶: Class 3 - Functions that accept enums as constant parameters.

CY_ASSERT_LEVEL¶: The user-definable assert level from compiler command-line argument (similarly to DEBUG / NDEBUG)

CY_ASSERT_L1(x)¶: Assert Level 1.

CY_ASSERT_L2(x)¶: Assert Level 2.

CY_ASSERT_L3(x)¶: Assert Level 3.

CY_DELAY_MS_OVERFLOW¶: Defines a 32-kHz clock delay.

CY_SYSLIB_RESET_HWWDT¶: A basic WatchDog Timer (WDT) reset has occurred since the last power cycle.

CY_SYSLIB_RESET_ACT_FAULT¶: The fault logging system requested a reset from its Active logic.

CY_SYSLIB_RESET_DPSLP_FAULT¶: The fault logging system requested a reset from its Deep-Sleep logic.

CY_SYSLIB_RESET_SOFT¶

The CPU requested a system reset through it’s SYSRESETREQ.

This can be done via a debugger probe or in firmware.

CY_SYSLIB_RESET_SWWDT0¶: The Multi-Counter Watchdog timer #0 reset has occurred since the last power cycle.

CY_SYSLIB_RESET_SWWDT1¶: The Multi-Counter Watchdog timer #1 reset has occurred since the last power cycle.

CY_SYSLIB_RESET_SWWDT2¶: The Multi-Counter Watchdog timer #2 reset has occurred since the last power cycle.

CY_SYSLIB_RESET_SWWDT3¶: The Multi-Counter Watchdog timer #3 reset has occurred since the last power cycle.

CY_SYSLIB_RESET_CSV_LOSS_WAKEUP¶: The reset has occured on a loss of high-frequency clock.

CY_SYSLIB_RESET_CSV_ERROR_WAKEUP¶: The reset has occured due to frequency error of high-frequency clock.

CY_SYSLIB_RESET_HIB_WAKEUP¶: The reset has occurred on a wakeup from Hibernate power mode.

CY_IPC_DATA_FOR_CM4_SOFT_RESET¶

Bit[31:24] Opcode = 0x1B (SoftReset) Bit[7:1] Type = 1 (Only CM4 reset)

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_YEAR_Pos¶

The position of the DIE_YEAR field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_MINOR_Pos¶

The position of the DIE_MINOR field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_SORT_Pos¶

The position of the DIE_SORT field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_Y_Pos¶

The position of the DIE_Y field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_X_Pos¶

The position of the DIE_X field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_WAFER_Pos¶

The position of the DIE_WAFER field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_LOT_2_Pos¶

The position of the DIE_LOT_2 field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_LOT_1_Pos¶

The position of the DIE_LOT_1 field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

CY_UNIQUE_ID_DIE_LOT_0_Pos¶

The position of the DIE_LOT_0 field in the silicon Unique ID.

note

This macro is available for devices having M4CPUSS IP.

Typedefs

typedef void (*cy_israddress)(void)¶: Type of ISR callbacks.

typedef char char_t¶: Specific-length typedef for the basic numerical types of char.

typedef float float32_t¶: Specific-length typedef for the basic numerical types of float.

typedef double float64_t¶: Specific-length typedef for the basic numerical types of double.

Enums

enum cy_en_syslib_status_t¶

cy_en_syslib_status_t: The SysLib status code structure.

Values:

enumerator CY_SYSLIB_SUCCESS¶: The success status code.

enumerator CY_SYSLIB_BAD_PARAM¶: The bad parameter status code.

enumerator CY_SYSLIB_TIMEOUT¶: The time out status code.

enumerator CY_SYSLIB_INVALID_STATE¶: The invalid state status code.

enumerator CY_SYSLIB_UNKNOWN¶: Unknown status code.

Functions

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.

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.

Parameters: milliseconds – The number of milliseconds to delay.

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.

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.

Parameters: microseconds – The number of microseconds to 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.

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 imlementation based on target RTOS.

Parameters: microseconds – The number of microseconds to delay.

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.

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.

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.

note

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.

Parameters: reason – The value to be used during debugging.

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.

note

A stored file name and line number could be accessed by cy_assertFileName and cy_assertLine global variables.

note

This function has the WEAK option, so the user can redefine the function for a custom processing.

Parameters

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

void Cy_SysLib_ClearFlashCacheAndBuffer(void)

This function invalidates the flash cache and buffer.

It ensures the valid data is read from flash instead of using outdated data from the cache. The caches’ LRU structure is also reset to their default state.

note

The operation takes a maximum of three clock cycles on the slowest of the clk_slow and clk_fast clocks.

note

This API is available for devices having M4CPUSS IP.

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.

note

This API is available for devices having M4CPUSS IP.

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]

void Cy_SysLib_SoftResetCM4(void)¶

This function performs a CM4 Core software reset using the CM4_PWR_CTL register.

The register is accessed by CM0 Core by using a command transferred to SROM API through the IPC channel. When the command is sent, the API waits for the IPC channel release.

note

This function should be called only when the CM4 core is in Deep Sleep mode.

note

This function will not reset CM0+ Core.

note

This function waits for an IPC channel release state.

note

This API is available for devices having M4CPUSS IP.

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.

note

This function also resets the WCO trimming value - use the Cy_SysLib_GetWcoTrim and Cy_SysLib_SetWcoTrim to store/restore the WCO trimming value.

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 */

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

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.

Name in M4CPUSS IP	Name in M33SYSCPUSS IP	Value
CY_SYSLIB_RESET_HWWDT	CY_SYSLIB_RESET_HWWDT	0x00001 (bit0)
CY_SYSLIB_RESET_ACT_FAULT	CY_SYSLIB_RESET_ACT_FAULT	0x00002 (bit1)
CY_SYSLIB_RESET_DPSLP_FAULT	CY_SYSLIB_RESET_DPSLP_FAULT	0x00004 (bit2)
CY_SYSLIB_RESET_TC_DBGRESET	CY_SYSLIB_RESET_CSV_WCO_LOSS	0x00008 (bit3)
CY_SYSLIB_RESET_SOFT	CY_SYSLIB_RESET_SOFT	0x00010 (bit4)
CY_SYSLIB_RESET_SWWDT0	CY_SYSLIB_RESET_SWWDT0	0x00020 (bit5)
CY_SYSLIB_RESET_SWWDT1	CY_SYSLIB_RESET_SWWDT1	0x00040 (bit6)
CY_SYSLIB_RESET_SWWDT2	CY_SYSLIB_RESET_SWWDT2	0x00080 (bit7)
CY_SYSLIB_RESET_SWWDT3	CY_SYSLIB_RESET_SWWDT3	0x00100 (bit8)
	CY_SYSLIB_RESET_HFCLK_LOSS	0x10000 (bit16)
	CY_SYSLIB_RESET_HFCLK_ERR	0x20000 (bit17)
CY_SYSLIB_RESET_HIB_WAKEUP	CY_SYSLIB_RESET_HIB_WAKEUP	0x40000 (bit18)

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.

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

void Cy_SysLib_ClearResetReason(void)

This function clears the values of RES_CAUSE and RES_CAUSE2.

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

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

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 */
        }
    }

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

__STATIC_INLINE uint32_t Cy_SysLib_GetWcoTrim (void)

This function returns the BACKUP->TRIM bitfield value.

It is intended to store the WCO trimming value before the Cy_SysLib_ResetBackupDomain usage.

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 */

Returns: The WCO trimming value.

__STATIC_INLINE void Cy_SysLib_SetWcoTrim (uint32_t wcoTrim)

This function writes the value into the BACKUP->TRIM bitfield.

It is intended to restore the WCO trimming value after the Cy_SysLib_ResetBackupDomain usage.

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 */

Parameters: wcoTrim – The WCO trimming value.

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.

note

This function stores the fault stack frame only for the first occurred fault.

note

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.

note

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

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

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.

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.

note

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

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).
clkHfMHz – The HFClk0 clock frequency in MHz. Specifying a frequency above the supported maximum will set the wait states as for the maximum frequency.

uint32_t Cy_SysLib_EnterCriticalSection(void)¶

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

note

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

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

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().

Variables

char_t cy_assertFileName[CY_MAX_FILE_NAME_SIZE]: The assert buffer.

uint32_t cy_assertLine: The assert line value.

cy_stc_fault_frame_t cy_faultFrame: Fault frame structure.

struct cy_stc_fault_frame_t¶

#include <>

The fault configuration structure.

Public Members

uint32_t r0¶: R0 register content.

uint32_t r1¶: R1 register content.

uint32_t r2¶: R2 register content.

uint32_t r3¶: R3 register content.

uint32_t r12¶: R12 register content.

uint32_t lr¶: LR register content.

uint32_t pc¶: PC register content.

uint32_t psr¶: PSR register content.