SysLib (System Library)

group group_syslib

The system libraries provide APIs that can be called in the user application to handle the timing, logical checking or register.

The functions and other declarations used in this driver are in cy_syslib.h. You can include cy_pdl.h to get access to all functions and declarations in the PDL.

The SysLib driver contains a set of different system functions. These functions can be called in the application routine. Major features of the system library:

  • Delay functions

  • The register Read/Write macro

  • Assert and Halt

  • Assert Classes and Levels

  • A software reset

  • Reading the reset cause

  • An API to invalidate the flash cache and buffer

  • Data manipulation macro

  • A variable type definition from MISRA-C which specifies signedness

  • Cross compiler compatible attributes

  • Getting a silicon-unique ID API

  • Setting wait states API

  • Resetting the backup domain API

  • APIs to serve Fault handler

Configuration Considerations

Assertion Usage

Use the CY_ASSERT() macro to check expressions that must be true if the program is running correctly. It is a convenient way to insert sanity checks. The CY_ASSERT() macro is defined in the cy_utils.h file, which is part of the

Cypress Core Library (core-lib). The macro behavior is as follows: if the expression passed to the macro is false, the CPU is halted.

Starting from the driver version 2.50, the CY_ASSERT macro was moved to the Cypress Core Library (core-lib). Also, the CY_ASSERT implementation was changed not to call

Cy_SysLib_AssertFailed() function, so user application that relied on that should take this change into account.

The PDL source code uses this assert mechanism extensively. It is recommended that you enable asserts when debugging firmware. Assertion Classes and Levels

The

Cypress Core Library defines three assert classes, which correspond to different kinds of parameters. There is a corresponding assert “level” for each class.

Class Macro

Level Macro

Type of check

CY_ASSERT_CLASS_1

CY_ASSERT_L1

A parameter that could change between different PSoC devices (e.g. the number of clock paths)

CY_ASSERT_CLASS_2

CY_ASSERT_L2

A parameter that has fixed limits such as a counter period

CY_ASSERT_CLASS_3

CY_ASSERT_L3

A parameter that is an enum constant

Firmware defines which ASSERT class is enabled by defining CY_ASSERT_LEVEL. This is a compiler command line argument, similar to how the DEBUG / NDEBUG macro is passed.

Enabling any class also enables any lower-numbered class. CY_ASSERT_CLASS_3 is the default level, and it enables asserts for all three classes. The following example shows the command-line option to enable all the assert levels:

-D CY_ASSERT_LEVEL=CY_ASSERT_CLASS_3 

note

The use of special characters, such as spaces, parenthesis, etc. must be protected with quotes.

After CY_ASSERT_LEVEL is defined, firmware can use one of the three level macros to make an assertion. For example, if the parameter can vary between devices, firmware uses the L1 macro.

CY_ASSERT_L1(clkPath < SRSS_NUM_CLKPATH); 
If the parameter has bounds, firmware uses L2.
CY_ASSERT_L2(trim <= CY_CTB_TRIM_VALUE_MAX); 
If the parameter is an enum, firmware uses L3.
CY_ASSERT_L3(config->LossAction <= CY_SYSCLK_CSV_ERROR_FAULT_RESET); 
Each check uses the appropriate level macro for the kind of parameter being checked. If a particular assert class/level is not enabled, then the assert does nothing.

More Information

Refer to the technical reference manual (TRM).

Changelog

Version

Changes

Reason for Change

2.90

Added new functions Cy_SysLib_Rtos_Delay, Cy_SysLib_Rtos_DelayUs.

Provide user an option to overwrite delay function implementation based on target RTOS environment.

Added new functions Cy_SysLib_GetResetStatus, Cy_SysLib_GetWcoTrim and Cy_SysLib_SetWcoTrim.

Add a possibility to manage the backup domain reset better and to store/restore the WCO trimming value.

2.80

Support for CM33.

New devices support.

Update Cy_SysLib_GetResetReason API to read RES_CAUSE2 register as well.

Code Enhancement/Bug Fix.

2.70

Added new macros CY_SECTION_RAMFUNC_BEGIN, CY_SECTION_RAMFUNC_END, CY_SECTION_SHAREDMEM to enable overriding of the linker section placement.

Enhancement based on usability feedback.

Noted that implementation of CY_ASSERT() was changed back in version 2.50, so that Cy_SysLib_AssertFailed() function is not called and user application may need to be updated.

Documentation update.

Removed the issue related to the malloc() failure to report error for the case when requested allocation size is bigger than the heap size. Refer to the ARM GCC section for the more details. Removed empty Known Issues section.

Documentation update and clarification.

Fixed/Documented MISRA 2012 violations.

MISRA 2012 compliance.

2.60.1

Updated the Configuration Considerations section with the information that CY_ASSERT() macro is defined in the cy_utils.h file, which is part of the Cypress Core Library (core-lib)

Documentation update and clarification.

2.60

Updated the following functions for the PSoC 64 devices: Cy_SysLib_ClearFlashCacheAndBuffer, Cy_SysLib_ClearResetReason, Cy_SysLib_SetWaitStates.

Added PSoC 64 device support.

Minor documentation updates.

Documentation enhancement.

2.50.3

Add section Known Issues

Documentation update and clarification.

2.50.1

Used the core library defines for the message codes forming.

Improve PDL code base.

2.50

Moved following macros to the core library: CY_LO8,CY_HI8,CY_LO16,CY_HI16,CY_SWAP_ENDIAN16,CY_SWAP_ENDIAN32, CY_SWAP_ENDIAN64,CY_GET_REG8,CY_SET_REG8,CY_GET_REG16,CY_SET_REG16, CY_GET_REG24,CY_SET_REG24,CY_GET_REG32,CY_SET_REG32,_CLR_SET_FLD32U, CY_REG32_CLR_SET,_CLR_SET_FLD16U,CY_REG16_CLR_SET,_CLR_SET_FLD8U, CY_REG8_CLR_SET,_BOOL2FLD,_FLD2BOOL,CY_SYSLIB_DIV_ROUND, CY_SYSLIB_DIV_ROUNDUP,CY_NOINIT,CY_SECTION,CY_UNUSED,CY_NOINLINE, CY_ALIGN,CY_RAMFUNC_BEGIN,CY_RAMFUNC_END. Use at least version 1.1 of the core library: https://github.com/cypresssemiconductorco/core-lib.

Improve PDL code base.

2.40.1

Correct the CY_RAMFUNC_BEGIN macro for the IAR compiler.

Removed the IAR compiler warning.

2.40

Added new macros CY_SYSLIB_DIV_ROUND and CY_SYSLIB_DIV_ROUNDUP to easy perform integer division with rounding.

Improve PDL code base.

2.30

Updated implementation of the Cy_SysLib_AsmInfiniteLoop() function to be compatible with ARMC6.

Provided support for the ARM Compiler 6.

Minor documentation edits.

Documentation update and clarification.

Added new macros CY_RAMFUNC_BEGIN and CY_RAMFUNC_END for convenient placement function in RAM for all supported compilers.

Improve user experience.

2.20

Updated implementation of the Cy_SysLib_AssertFailed() function to be available in Release and Debug modes.

Provided support for the PDL static library in Release mode.

Minor documentation edits.

Documentation update and clarification.

2.10

Flattened the organization of the driver source code into the single source directory and the single include directory.

Driver library directory-structure simplification.

Added the following macros: CY_REG32_CLR_SET, _CLR_SET_FLD16U, CY_REG16_CLR_SET, _CLR_SET_FLD8U, CY_REG8_CLR_SET

Register access simplification.

Removed the Cy_SysLib_GetNumHfclkResetCause API function.

This feature is not supported by SRSS_ver1.

Added register access layer. Use register access macros instead of direct register access using dereferenced pointers.

Makes register access device-independent, so that the PDL does not need to be recompiled for each supported part number.

2.0.1

Minor documentation edits

Documentation update and clarification

2.0

Added Cy_SysLib_ResetBackupDomain() API implementation.
Added CY_NOINLINE attribute implementation.
Added DIE_YEAR field to 64-bit unique ID return value of Cy_SysLib_GetUniqueId() API.
Added storing of SCB->HFSR, SCB->SHCSR registers and SCB->MMFAR, SCB->BFAR addresses to Fault Handler debug structure.
Optimized Cy_SysLib_SetWaitStates() API implementation.

Improvements made based on usability feedback.

Added Assertion Classes and Levels.

For error checking, parameter validation and status returns in the PDL API.

Applied CY_NOINIT attribute to cy_assertFileName, cy_assertLine, and cy_faultFrame global variables.

To store debug information into a non-zero init area for future analysis.

Removed CY_WEAK attribute implementation.

CMSIS __WEAK attribute should be used instead.

1.0

Initial version