Update psoc6 core_lib with additional documentation and bit manipulation

utilities.

Author: dustin-crossman

targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/core_lib/include/cy_result.h

@@ -28,37 +28,49 @@
 * \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 <stdint.h>
 
 #if defined(__cplusplus)
 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 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)
 
-/** Base identifier for Middleware module codes (0x0200 - 0x02FF) */
-#define CY_RSLT_MODULE_MIDDLEWARE_BASE            (0x0200U)
+/** 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)
 
-/** \} group_result_modules */
+
+/** 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 */