diff --git a/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_result.h b/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_result.h index fc05bd7401..f4410a6641 100644 --- a/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_result.h +++ b/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_result.h @@ -28,16 +28,27 @@ * \addtogroup group_result Result Type * \ingroup group_abstraction * \{ -* Basic function result handling. Defines a simple type for conveying -* information about whether something succeeded or details about any issues -* that were detected. -* -* \defgroup group_result_fields Fields -* \defgroup group_result_modules Modules -* \defgroup group_result_severity Severity + \anchor anchor_general_description +* Defines a type and related utilities for function result handling. +* +* The cy_rslt_t type is a structured bitfield which encodes information +* about result type, the originating module, and a code for the specific +* error (or warning etc). In order to extract these individual fields from +* a cy_rslt_t value, the utility macros @ref CY_RSLT_GET_TYPE, @ref CY_RSLT_GET_MODULE, +* and @ref CY_RSLT_GET_CODE are provided. For example: +* \code +* cy_rslt_t result = cy_hal_do_operation(arg); +* // Will be CY_RSLT_TYPE_INFO, CY_RSLT_TYPE_WARNING, CY_RSLT_TYPE_ERROR, or CY_RSLT_TYPE_FATAL +* uint8_t type = CY_RSLT_GET_TYPE(result) +* // See the "Modules" section for possible values +* uint16_t module_id = CY_RSLT_GET_MODULE(result); +* // Specific error codes are defined by each module +* uint16_t error_code = CY_RSLT_GET_CODE(result); +* \endcode */ -#pragma once +#if !defined(CY_RESULT_H) +#define CY_RESULT_H #include @@ -45,20 +56,21 @@ extern "C" { #endif -/** Provides the result of an operation as a structured bitfield */ +/** + * @brief Provides the result of an operation as a structured bitfield. + * + * See the \ref anchor_general_description "General Description" + * for more details on structure and usage. + */ typedef uint32_t cy_rslt_t; -/** Result value indicating success */ +/** @ref cy_rslt_t return value indicating success */ #define CY_RSLT_SUCCESS ((cy_rslt_t)0x00000000U) /** \cond INTERNAL */ /** Mask for the bit at position "x" */ #define CY_BIT_MASK(x) ((1U << (x)) - 1U) -/** Bit position of the result code */ -#define CY_RSLT_CODE_POSITION (0U) -/** Bit width of the result code */ -#define CY_RSLT_CODE_WIDTH (16U) /** Bit position of the result type */ #define CY_RSLT_TYPE_POSITION (16U) /** Bit width of the result type */ @@ -67,86 +79,126 @@ typedef uint32_t cy_rslt_t; #define CY_RSLT_MODULE_POSITION (18U) /** Bit width of the module identifier */ #define CY_RSLT_MODULE_WIDTH (14U) +/** Bit position of the result code */ +#define CY_RSLT_CODE_POSITION (0U) +/** Bit width of the result code */ +#define CY_RSLT_CODE_WIDTH (16U) -/** Mask for the result code */ -#define CY_RSLT_CODE_MASK CY_BIT_MASK(CY_RSLT_CODE_WIDTH) -/** Mask for the module identifier */ -#define CY_RSLT_MODULE_MASK CY_BIT_MASK(CY_RSLT_MODULE_WIDTH) /** Mask for the result type */ #define CY_RSLT_TYPE_MASK CY_BIT_MASK(CY_RSLT_TYPE_WIDTH) +/** Mask for the module identifier */ +#define CY_RSLT_MODULE_MASK CY_BIT_MASK(CY_RSLT_MODULE_WIDTH) +/** Mask for the result code */ +#define CY_RSLT_CODE_MASK CY_BIT_MASK(CY_RSLT_CODE_WIDTH) /** \endcond */ /** -* \addtogroup group_result_fields * \{ -* Utlity macros for constructing result values and extracting individual fields from existing results. +* @name Fields +* Utility macros for constructing result values and extracting individual fields from existing results. */ -/** Get the value of the result code field */ -#define CY_RSLT_GET_CODE(x) (((x) >> CY_RSLT_CODE_POSITION) & CY_RSLT_CODE_MASK) -/** Get the value of the result type field */ +/** + * @brief Get the value of the result type field + * @param x the @ref cy_rslt_t value from which to extract the result type + */ #define CY_RSLT_GET_TYPE(x) (((x) >> CY_RSLT_TYPE_POSITION) & CY_RSLT_TYPE_MASK) -/** Get the value of the module identifier field */ +/** + * @brief Get the value of the module identifier field + * @param x the @ref cy_rslt_t value from which to extract the module id + */ #define CY_RSLT_GET_MODULE(x) (((x) >> CY_RSLT_MODULE_POSITION) & CY_RSLT_MODULE_MASK) +/** + * @brief Get the value of the result code field + * @param x the @ref cy_rslt_t value from which to extract the result code + */ +#define CY_RSLT_GET_CODE(x) (((x) >> CY_RSLT_CODE_POSITION) & CY_RSLT_CODE_MASK) -/** Create a result value from the specified type, module, and result code */ +/** + * @brief Create a new @ref cy_rslt_t value that encodes the specified type, module, and result code. + * @param type one of @ref CY_RSLT_TYPE_INFO, @ref CY_RSLT_TYPE_WARNING, + * @ref CY_RSLT_TYPE_ERROR, @ref CY_RSLT_TYPE_FATAL + * @param module Identifies the module where this result originated; see @ref anchor_modules "Modules". + * @param code a module-defined identifier to identify the specific situation that + * this result describes. + */ #define CY_RSLT_CREATE(type, module, code) \ ((((module) & CY_RSLT_MODULE_MASK) << CY_RSLT_MODULE_POSITION) | \ (((code) & CY_RSLT_CODE_MASK) << CY_RSLT_CODE_POSITION) | \ (((type) & CY_RSLT_TYPE_MASK) << CY_RSLT_TYPE_POSITION)) -/** \} group_result_fields */ +/** \} fields */ /** -* \addtogroup group_result_severity * \{ +*@name Result Types */ -/** Informational-only result */ +/** @brief The result code is informational-only */ #define CY_RSLT_TYPE_INFO (0U) -/** Warning result */ +/** @brief The result code is a warning */ #define CY_RSLT_TYPE_WARNING (1U) -/** Error result */ +/** @brief The result code is an error */ #define CY_RSLT_TYPE_ERROR (2U) -/** Fatal error result */ +/** @brief The result code is a fatal error */ #define CY_RSLT_TYPE_FATAL (3U) -/** \} group_result_severity */ +/** \} severity */ /** -* \addtogroup group_result_modules * \{ +@name Modules +@anchor anchor_modules * Defines codes to identify the module from which an error originated. * For some large libraries, a range of module codes is defined here; * see the library documentation for values corresonding to individual modules. */ /**** DRIVER Module codes: 0x0000 - 0x00FF ****/ -/** Base identifier for peripheral driver library modules (0x0000 - 0x007F) */ -#define CY_RSLT_MODULE_DRIVERS_PDL_BASE (0x0000U) -/** Base identifier for wireless host driver library modules (0x0080 - 0x00FF) */ -#define CY_RSLT_MODULE_DRIVERS_WHD_BASE (0x0080U) +/** Base module identifier for peripheral driver library drivers (0x0000 - 0x007F) */ +#define CY_RSLT_MODULE_DRIVERS_PDL_BASE (0x0000U) +/** Base module identifier for wireless host driver library modules (0x0080 - 0x00FF) */ +#define CY_RSLT_MODULE_DRIVERS_WHD_BASE (0x0080U) -/** Base identifier for HAL modules (0x0100 - 0x017F) */ -#define CY_RSLT_MODULE_ABSTRACTION_HAL_BASE (0x0100U) +/** Base module identifier for HAL drivers (0x0100 - 0x017F) */ +#define CY_RSLT_MODULE_ABSTRACTION_HAL_BASE (0x0100U) /** Module identifier for board support package */ -#define CY_RSLT_MODULE_ABSTRACTION_BSP (0x0180U) +#define CY_RSLT_MODULE_ABSTRACTION_BSP (0x0180U) /** Module identifier for file system abstraction */ -#define CY_RSLT_MODULE_ABSTRACTION_FS (0x0181U) +#define CY_RSLT_MODULE_ABSTRACTION_FS (0x0181U) /** Module identifier for resource abstraction */ -#define CY_RSLT_MODULE_ABSTRACTION_RESOURCE (0x0182U) +#define CY_RSLT_MODULE_ABSTRACTION_RESOURCE (0x0182U) /** Module identifier for rtos abstraction */ -#define CY_RSLT_MODULE_ABSTRACTION_OS (0x0183U) +#define CY_RSLT_MODULE_ABSTRACTION_OS (0x0183U) /** Base identifier for environment abstraction modules (0x0184 - 0x01FF) */ -#define CY_RSLT_MODULE_ABSTRACTION_ENV (0x0184U) +#define CY_RSLT_MODULE_ABSTRACTION_ENV (0x0184U) -/** Base identifier for Middleware module codes (0x0200 - 0x02FF) */ -#define CY_RSLT_MODULE_MIDDLEWARE_BASE (0x0200U) +/** Base module identifier for Board Libraries (0x01A0 - 0x01BF) */ +#define CY_RSLT_MODULE_BOARD_LIB_BASE (0x01A0U) +/** Module identifier for the Retarget IO Board Library */ +#define CY_RSLT_MODULE_BOARD_LIB_RETARGET_IO (0x1A0U) +/** Module identifier for the RGB LED Board Library */ +#define CY_RSLT_MODULE_BOARD_LIB_RGB_LED (0x01A1U) +/** Module identifier for the Serial Flash Board Library */ +#define CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH (0x01A2U) -/** \} group_result_modules */ +/** Base module identifier for Shield Board Libraries (0x01C0 - 0x01FF) */ +#define CY_RSLT_MODULE_BOARD_SHIELD_BASE (0x01C0U) +/** Module identifier for Shield Board CY8CKIT-028-EPD */ +#define CY_RSLT_MODULE_BOARD_SHIELD_028_EPD (0x01C0U) +/** Module identifier for Shield Board CY8CKIT-028-TFT */ +#define CY_RSLT_MODULE_BOARD_SHIELD_028_TFT (0x01C1U) + + +/** Base module identifier for Middleware Libraries (0x0200 - 0x02FF) */ +#define CY_RSLT_MODULE_MIDDLEWARE_BASE (0x0200U) + +/** \} modules */ #ifdef __cplusplus } #endif +#endif /* CY_RESULT_H */ + /** \} group_result */ diff --git a/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_utils.h b/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_utils.h index 30a99344c1..ea4631b974 100644 --- a/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_utils.h +++ b/targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_utils.h @@ -27,31 +27,23 @@ * \ingroup group_abstraction * \{ * Basic utility macros and functions. -* -* \defgroup group_utils_macros Macros */ -#pragma once +#if !defined(CY_UTILS_H) +#define CY_UTILS_H #if defined(__cplusplus) extern "C" { #endif -/** -* \addtogroup group_utils_macros -* \{ -*/ - /** Simple macro to supress the unused parameter warning by casting to void. */ #define CY_UNUSED_PARAMETER(x) ( (void)(x) ) /** Halt the processor in the debug state - * @return */ -static inline uint32_t CY_HALT() +static inline void CY_HALT() { __asm(" bkpt 1"); - return 0; } #ifdef CY_ASSERT @@ -60,7 +52,8 @@ static inline uint32_t CY_HALT() /** Utility macro when neither NDEBUG or CY_NO_ASSERT is not declared to check a condition and, if false, trigger a breakpoint */ #if defined(NDEBUG) || defined(CY_NO_ASSERT) - #define CY_ASSERT(x) CY_UNUSED_PARAMETER(x) + #define CY_ASSERT(x) do { \ + } while(0) #else #define CY_ASSERT(x) do { \ if(!(x)) \ @@ -70,10 +63,333 @@ static inline uint32_t CY_HALT() } while(0) #endif /* defined(NDEBUG) */ -/** \} group_utils_macros */ + +/******************************************************************************* +* Data manipulation defines +*******************************************************************************/ + +/** Get the lower 8 bits of a 16-bit value. */ +#define CY_LO8(x) ((uint8_t) ((x) & 0xFFU)) +/** Get the upper 8 bits of a 16-bit value. */ +#define CY_HI8(x) ((uint8_t) ((uint16_t)(x) >> 8U)) + +/** Get the lower 16 bits of a 32-bit value. */ +#define CY_LO16(x) ((uint16_t) ((x) & 0xFFFFU)) +/** Get the upper 16 bits of a 32-bit value. */ +#define CY_HI16(x) ((uint16_t) ((uint32_t)(x) >> 16U)) + +/** Swap the byte ordering of a 16-bit value */ +#define CY_SWAP_ENDIAN16(x) ((uint16_t)(((x) << 8U) | (((x) >> 8U) & 0x00FFU))) + +/** Swap the byte ordering of a 32-bit value */ +#define CY_SWAP_ENDIAN32(x) ((uint32_t)((((x) >> 24U) & 0x000000FFU) | (((x) & 0x00FF0000U) >> 8U) | \ + (((x) & 0x0000FF00U) << 8U) | ((x) << 24U))) + +/** Swap the byte ordering of a 64-bit value */ +#define CY_SWAP_ENDIAN64(x) ((uint64_t) (((uint64_t) CY_SWAP_ENDIAN32((uint32_t)(x)) << 32U) | \ + CY_SWAP_ENDIAN32((uint32_t)((x) >> 32U)))) + + +/******************************************************************************* +* Memory model definitions +*******************************************************************************/ +#if defined(__ARMCC_VERSION) + /** To create cross compiler compatible code, use the CY_NOINIT, CY_SECTION, CY_UNUSED, CY_ALIGN + * attributes at the first place of declaration/definition. + * For example: CY_NOINIT uint32_t noinitVar; + */ + #if (__ARMCC_VERSION >= 6010050) + #define CY_NOINIT __attribute__ ((section(".noinit"))) + #else + #define CY_NOINIT __attribute__ ((section(".noinit"), zero_init)) + #endif /* (__ARMCC_VERSION >= 6010050) */ + #define CY_SECTION(name) __attribute__ ((section(name))) + #define CY_UNUSED __attribute__ ((unused)) + #define CY_NOINLINE __attribute__ ((noinline)) + /* Specifies the minimum alignment (in bytes) for variables of the specified type. */ + #define CY_ALIGN(align) __ALIGNED(align) + #define CY_RAMFUNC_BEGIN __attribute__ ((section(".cy_ramfunc"))) + #define CY_RAMFUNC_END +#elif defined (__GNUC__) + #if defined (__clang__) + #define CY_NOINIT __attribute__ ((section("__DATA, __noinit"))) + #define CY_SECTION(name) __attribute__ ((section("__DATA, "name))) + #define CY_RAMFUNC_BEGIN __attribute__ ((section("__DATA, .cy_ramfunc"))) + #define CY_RAMFUNC_END + #else + #define CY_NOINIT __attribute__ ((section(".noinit"))) + #define CY_SECTION(name) __attribute__ ((section(name))) + #define CY_RAMFUNC_BEGIN __attribute__ ((section(".cy_ramfunc"))) + #define CY_RAMFUNC_END + #endif + + #define CY_UNUSED __attribute__ ((unused)) + #define CY_NOINLINE __attribute__ ((noinline)) + #define CY_ALIGN(align) __ALIGNED(align) +#elif defined (__ICCARM__) + #define CY_PRAGMA(x) _Pragma(#x) + #define CY_NOINIT __no_init + #define CY_SECTION(name) CY_PRAGMA(location = name) + #define CY_UNUSED + #define CY_NOINLINE CY_PRAGMA(optimize = no_inline) + #define CY_RAMFUNC_BEGIN CY_PRAGMA(diag_suppress = Ta023) __ramfunc + #define CY_RAMFUNC_END CY_PRAGMA(diag_default = Ta023) + #if (__VER__ < 8010001) + #define CY_ALIGN(align) CY_PRAGMA(data_alignment = align) + #else + #define CY_ALIGN(align) __ALIGNED(align) + #endif /* (__VER__ < 8010001) */ +#else + #error "An unsupported toolchain" +#endif /* (__ARMCC_VERSION) */ + + +/******************************************************************************* +* Macro Name: CY_GET_REG8(addr) +****************************************************************************//** +* +* Reads the 8-bit value from the specified address. This function can't be +* used to access the Core register, otherwise a fault occurs. +* +* \param addr The register address. +* +* \return The read value. +* +*******************************************************************************/ +#define CY_GET_REG8(addr) (*((const volatile uint8_t *)(addr))) + + +/******************************************************************************* +* Macro Name: CY_SET_REG8(addr, value) +****************************************************************************//** +* +* Writes an 8-bit value to the specified address. This function can't be +* used to access the Core register, otherwise a fault occurs. +* +* \param addr The register address. +* +* \param value The value to write. +* +*******************************************************************************/ +#define CY_SET_REG8(addr, value) (*((volatile uint8_t *)(addr)) = (uint8_t)(value)) + + +/******************************************************************************* +* Macro Name: CY_GET_REG16(addr) +****************************************************************************//** +* +* Reads the 16-bit value from the specified address. +* +* \param addr The register address. +* +* \return The read value. +* +*******************************************************************************/ +#define CY_GET_REG16(addr) (*((const volatile uint16_t *)(addr))) + + +/******************************************************************************* +* Macro Name: CY_SET_REG16(addr, value) +****************************************************************************//** +* +* Writes the 16-bit value to the specified address. +* +* \param addr The register address. +* +* \param value The value to write. +* +*******************************************************************************/ +#define CY_SET_REG16(addr, value) (*((volatile uint16_t *)(addr)) = (uint16_t)(value)) + + +/******************************************************************************* +* Macro Name: CY_GET_REG24(addr) +****************************************************************************//** +* +* Reads the 24-bit value from the specified address. +* +* \param addr The register address. +* +* \return The read value. +* +*******************************************************************************/ +#define CY_GET_REG24(addr) (((uint32_t) (*((const volatile uint8_t *)(addr)))) | \ + (((uint32_t) (*((const volatile uint8_t *)(addr) + 1))) << 8U) | \ + (((uint32_t) (*((const volatile uint8_t *)(addr) + 2))) << 16U)) + + +/******************************************************************************* +* Macro Name: CY_SET_REG24(addr, value) +****************************************************************************//** +* +* Writes the 24-bit value to the specified address. +* +* \param addr The register address. +* +* \param value The value to write. +* +*******************************************************************************/ +#define CY_SET_REG24(addr, value) do \ + { \ + (*((volatile uint8_t *) (addr))) = (uint8_t)(value); \ + (*((volatile uint8_t *) (addr) + 1)) = (uint8_t)((value) >> 8U); \ + (*((volatile uint8_t *) (addr) + 2)) = (uint8_t)((value) >> 16U); \ + } \ + while(0) + + +/******************************************************************************* +* Macro Name: CY_GET_REG32(addr) +****************************************************************************//** +* +* Reads the 32-bit value from the specified register. The address is the little +* endian order (LSB in lowest address). +* +* \param addr The register address. +* +* \return The read value. +* +*******************************************************************************/ +#define CY_GET_REG32(addr) (*((const volatile uint32_t *)(addr))) + + +/******************************************************************************* +* Macro Name: CY_SET_REG32(addr, value) +****************************************************************************//** +* +* Writes the 32-bit value to the specified register. The address is the little +* endian order (LSB in lowest address). +* +* \param addr The register address. +* +* \param value The value to write. +* +*******************************************************************************/ +#define CY_SET_REG32(addr, value) (*((volatile uint32_t *)(addr)) = (uint32_t)(value)) + + +/******************************************************************************* +* Macro Name: _CLR_SET_FLD32U +****************************************************************************//** +* +* The macro for setting a register with a name field and value for providing +* get-clear-modify-write operations. +* Returns a resulting value to be assigned to the register. +* +*******************************************************************************/ +#define _CLR_SET_FLD32U(reg, field, value) (((reg) & ((uint32_t)(~(field ## _Msk)))) | (_VAL2FLD(field, value))) + + +/******************************************************************************* +* Macro Name: CY_REG32_CLR_SET +****************************************************************************//** +* +* Uses _CLR_SET_FLD32U macro for providing get-clear-modify-write +* operations with a name field and value and writes a resulting value +* to the 32-bit register. +* +*******************************************************************************/ +#define CY_REG32_CLR_SET(reg, field, value) ((reg) = _CLR_SET_FLD32U((reg), field, (value))) + + +/******************************************************************************* +* Macro Name: _CLR_SET_FLD16U +****************************************************************************//** +* +* The macro for setting a 16-bit register with a name field and value for providing +* get-clear-modify-write operations. +* Returns a resulting value to be assigned to the 16-bit register. +* +*******************************************************************************/ +#define _CLR_SET_FLD16U(reg, field, value) ((uint16_t)(((reg) & ((uint16_t)(~(field ## _Msk)))) | \ + ((uint16_t)_VAL2FLD(field, value)))) + + +/******************************************************************************* +* Macro Name: CY_REG16_CLR_SET +****************************************************************************//** +* +* Uses _CLR_SET_FLD16U macro for providing get-clear-modify-write +* operations with a name field and value and writes a resulting value +* to the 16-bit register. +* +*******************************************************************************/ +#define CY_REG16_CLR_SET(reg, field, value) ((reg) = _CLR_SET_FLD16U((reg), field, (value))) + + +/******************************************************************************* +* Macro Name: _CLR_SET_FLD8U +****************************************************************************//** +* +* The macro for setting a 8-bit register with a name field and value for providing +* get-clear-modify-write operations. +* Returns a resulting value to be assigned to the 8-bit register. +* +*******************************************************************************/ +#define _CLR_SET_FLD8U(reg, field, value) ((uint8_t)(((reg) & ((uint8_t)(~(field ## _Msk)))) | \ + ((uint8_t)_VAL2FLD(field, value)))) + + +/******************************************************************************* +* Macro Name: CY_REG8_CLR_SET +****************************************************************************//** +* +* Uses _CLR_SET_FLD8U macro for providing get-clear-modify-write +* operations with a name field and value and writes a resulting value +* to the 8-bit register. +* +*******************************************************************************/ +#define CY_REG8_CLR_SET(reg, field, value) ((reg) = _CLR_SET_FLD8U((reg), field, (value))) + + +/******************************************************************************* +* Macro Name: _BOOL2FLD +****************************************************************************//** +* +* Returns a field mask if the value is not false. +* Returns 0, if the value is false. +* +*******************************************************************************/ +#define _BOOL2FLD(field, value) (((value) != false) ? (field ## _Msk) : 0UL) + + +/******************************************************************************* +* Macro Name: _FLD2BOOL +****************************************************************************//** +* +* Returns true, if the value includes the field mask. +* Returns false, if the value doesn't include the field mask. +* +*******************************************************************************/ +#define _FLD2BOOL(field, value) (((value) & (field ## _Msk)) != 0UL) + + +/******************************************************************************* +* Macro Name: CY_SYSLIB_DIV_ROUND +****************************************************************************//** +* +* Calculates a / b with rounding to the nearest integer, +* a and b must have the same sign. +* +*******************************************************************************/ +#define CY_SYSLIB_DIV_ROUND(a, b) (((a) + ((b) / 2U)) / (b)) + + +/******************************************************************************* +* Macro Name: CY_SYSLIB_DIV_ROUNDUP +****************************************************************************//** +* +* Calculates a / b with rounding up if remainder != 0, +* both a and b must be positive. +* +*******************************************************************************/ +#define CY_SYSLIB_DIV_ROUNDUP(a, b) ((((a) - 1U) / (b)) + 1U) + #ifdef __cplusplus } #endif +#endif /* CY_UTILS_H */ + /** \} group_utils */