1 /***************************************************************************//** 2 * \file cy_result.h 3 * 4 * \brief 5 * Basic function result handling. Defines a simple type for conveying 6 * information about whether something succeeded or details about any issues 7 * that were detected. 8 * 9 ******************************************************************************** 10 * \copyright 11 * Copyright 2018-2020 Cypress Semiconductor Corporation 12 * SPDX-License-Identifier: Apache-2.0 13 * 14 * Licensed under the Apache License, Version 2.0 (the "License"); 15 * you may not use this file except in compliance with the License. 16 * You may obtain a copy of the License at 17 * 18 * http://www.apache.org/licenses/LICENSE-2.0 19 * 20 * Unless required by applicable law or agreed to in writing, software 21 * distributed under the License is distributed on an "AS IS" BASIS, 22 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 23 * See the License for the specific language governing permissions and 24 * limitations under the License. 25 *******************************************************************************/ 26 27 /** 28 * \addtogroup group_result Result Type 29 * \ingroup group_abstraction 30 * \{ 31 * \anchor anchor_general_description 32 * \brief Defines a type and related utilities for function result handling. 33 * 34 * The @ref cy_rslt_t type is a structured bitfield which encodes information 35 * about result type, the originating module, and a code for the specific 36 * error (or warning etc). In order to extract these individual fields from 37 * a @ref cy_rslt_t value, the utility macros @ref CY_RSLT_GET_TYPE, @ref CY_RSLT_GET_MODULE, 38 * and @ref CY_RSLT_GET_CODE are provided. For example: 39 * \code 40 * cy_rslt_t result = cy_hal_do_operation(arg); 41 * // Will be CY_RSLT_TYPE_INFO, CY_RSLT_TYPE_WARNING, CY_RSLT_TYPE_ERROR, or CY_RSLT_TYPE_FATAL 42 * uint8_t type = CY_RSLT_GET_TYPE(result) 43 * // See the "Modules" section for possible values 44 * uint16_t module_id = CY_RSLT_GET_MODULE(result); 45 * // Specific error codes are defined by each module 46 * uint16_t error_code = CY_RSLT_GET_CODE(result); 47 * \endcode 48 */ 49 50 #if !defined(CY_RESULT_H) 51 #define CY_RESULT_H 52 53 #include <stdint.h> 54 55 #if defined(__cplusplus) 56 extern "C" { 57 #endif 58 59 /** 60 * @brief Provides the result of an operation as a structured bitfield. 61 * 62 * See the \ref anchor_general_description "General Description" 63 * for more details on structure and usage. 64 */ 65 typedef uint32_t cy_rslt_t; 66 67 /** @ref cy_rslt_t return value indicating success */ 68 #define CY_RSLT_SUCCESS ((cy_rslt_t)0x00000000U) 69 70 /** \cond INTERNAL */ 71 /** Mask for the bit at position "x" */ 72 #define CY_BIT_MASK(x) ((1UL << (x)) - 1U) 73 74 /** Bit position of the result type */ 75 #define CY_RSLT_TYPE_POSITION (16U) 76 /** Bit width of the result type */ 77 #define CY_RSLT_TYPE_WIDTH (2U) 78 /** Bit position of the module identifier */ 79 #define CY_RSLT_MODULE_POSITION (18U) 80 /** Bit width of the module identifier */ 81 #define CY_RSLT_MODULE_WIDTH (14U) 82 /** Bit position of the result code */ 83 #define CY_RSLT_CODE_POSITION (0U) 84 /** Bit width of the result code */ 85 #define CY_RSLT_CODE_WIDTH (16U) 86 87 /** Mask for the result type */ 88 #define CY_RSLT_TYPE_MASK CY_BIT_MASK(CY_RSLT_TYPE_WIDTH) 89 /** Mask for the module identifier */ 90 #define CY_RSLT_MODULE_MASK CY_BIT_MASK(CY_RSLT_MODULE_WIDTH) 91 /** Mask for the result code */ 92 #define CY_RSLT_CODE_MASK CY_BIT_MASK(CY_RSLT_CODE_WIDTH) 93 94 /** \endcond */ 95 96 /** 97 * \{ 98 * @name Fields 99 * Utility macros for constructing result values and extracting individual fields from existing results. 100 */ 101 102 /** 103 * @brief Get the value of the result type field 104 * @param x the @ref cy_rslt_t value from which to extract the result type 105 */ 106 #define CY_RSLT_GET_TYPE(x) (((x) >> CY_RSLT_TYPE_POSITION) & CY_RSLT_TYPE_MASK) 107 /** 108 * @brief Get the value of the module identifier field 109 * @param x the @ref cy_rslt_t value from which to extract the module id 110 */ 111 #define CY_RSLT_GET_MODULE(x) (((x) >> CY_RSLT_MODULE_POSITION) & CY_RSLT_MODULE_MASK) 112 /** 113 * @brief Get the value of the result code field 114 * @param x the @ref cy_rslt_t value from which to extract the result code 115 */ 116 #define CY_RSLT_GET_CODE(x) (((x) >> CY_RSLT_CODE_POSITION) & CY_RSLT_CODE_MASK) 117 118 /** 119 * @brief Create a new @ref cy_rslt_t value that encodes the specified type, module, and result code. 120 * @param type one of @ref CY_RSLT_TYPE_INFO, @ref CY_RSLT_TYPE_WARNING, 121 * @ref CY_RSLT_TYPE_ERROR, @ref CY_RSLT_TYPE_FATAL 122 * @param module Identifies the module where this result originated; see @ref anchor_modules "Modules". 123 * @param code a module-defined identifier to identify the specific situation that 124 * this result describes. 125 */ 126 #define CY_RSLT_CREATE(type, module, code) \ 127 ((((module) & CY_RSLT_MODULE_MASK) << CY_RSLT_MODULE_POSITION) | \ 128 (((code) & CY_RSLT_CODE_MASK) << CY_RSLT_CODE_POSITION) | \ 129 (((type) & CY_RSLT_TYPE_MASK) << CY_RSLT_TYPE_POSITION)) 130 131 /** \} fields */ 132 133 /** 134 * \{ 135 * @name Result Types 136 * Defines codes to identify the type of result. 137 */ 138 139 /** @brief The result code is informational-only */ 140 #define CY_RSLT_TYPE_INFO (0U) 141 /** @brief The result code is warning of a problem but will proceed */ 142 #define CY_RSLT_TYPE_WARNING (1U) 143 /** @brief The result code is an error */ 144 #define CY_RSLT_TYPE_ERROR (2U) 145 /** @brief The result code is a fatal error */ 146 #define CY_RSLT_TYPE_FATAL (3U) 147 148 /** \} severity */ 149 150 /** 151 * \{ 152 * @name Modules 153 * @anchor anchor_modules 154 * Defines codes to identify the module from which an error originated. 155 * For some large libraries, a range of module codes is defined here; 156 * see the library documentation for values corresponding to individual modules. 157 * Valid range is 0x0000-0x4000. 158 */ 159 /**** DRIVER Module codes: 0x0000 - 0x00FF ****/ 160 /** Base module identifier for peripheral driver library drivers (0x0000 - 0x007F) */ 161 #define CY_RSLT_MODULE_DRIVERS_PDL_BASE (0x0000U) 162 /** Base module identifier for wireless host driver library modules (0x0080 - 0x00FF) */ 163 #define CY_RSLT_MODULE_DRIVERS_WHD_BASE (0x0080U) 164 165 /** Deprecated. Use \ref CY_RSLT_MODULE_ABSTRACTION_HAL */ 166 #define CY_RSLT_MODULE_ABSTRACTION_HAL_BASE (0x0100U) 167 /** Module identifier for the Hardware Abstraction Layer */ 168 #define CY_RSLT_MODULE_ABSTRACTION_HAL (0x0100U) 169 /** Module identifier for board support package */ 170 #define CY_RSLT_MODULE_ABSTRACTION_BSP (0x0180U) 171 /** Module identifier for file system abstraction */ 172 #define CY_RSLT_MODULE_ABSTRACTION_FS (0x0181U) 173 /** Module identifier for resource abstraction */ 174 #define CY_RSLT_MODULE_ABSTRACTION_RESOURCE (0x0182U) 175 /** Module identifier for rtos abstraction */ 176 #define CY_RSLT_MODULE_ABSTRACTION_OS (0x0183U) 177 /** Base identifier for environment abstraction modules (0x0184 - 0x01FF) */ 178 #define CY_RSLT_MODULE_ABSTRACTION_ENV (0x0184U) 179 180 /** Base module identifier for Board Libraries (0x01A0 - 0x01BF) */ 181 #define CY_RSLT_MODULE_BOARD_LIB_BASE (0x01A0U) 182 /** Module identifier for the Retarget IO Board Library */ 183 #define CY_RSLT_MODULE_BOARD_LIB_RETARGET_IO (0x1A0U) 184 /** Module identifier for the RGB LED Board Library */ 185 #define CY_RSLT_MODULE_BOARD_LIB_RGB_LED (0x01A1U) 186 /** Module identifier for the Serial Flash Board Library */ 187 #define CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH (0x01A2U) 188 /** Module identifier for the WiFi Host Driver + Board Support Integration Library */ 189 #define CY_RSLT_MODULE_BOARD_LIB_WHD_INTEGRATION (0x01A3U) 190 191 /** Base module identifier for Shield Board Libraries (0x01B8 - 0x01BF) */ 192 #define CY_RSLT_MODULE_BOARD_SHIELD_BASE (0x01B8U) 193 /** Module identifier for Shield Board CY8CKIT-028-EPD */ 194 #define CY_RSLT_MODULE_BOARD_SHIELD_028_EPD (0x01B8U) 195 /** Module identifier for Shield Board CY8CKIT-028-TFT */ 196 #define CY_RSLT_MODULE_BOARD_SHIELD_028_TFT (0x01B9U) 197 /** Module identifier for Shield Board CY8CKIT-032 */ 198 #define CY_RSLT_MODULE_BOARD_SHIELD_032 (0x01BAU) 199 200 /** Base module identifier for Board Hardware Libraries (0x01C0 - 0x01FF) */ 201 #define CY_RSLT_MODULE_BOARD_HARDWARE_BASE (0x01C0U) 202 /** Module identifier for the BMI160 Motion Sensor Library */ 203 #define CY_RSLT_MODULE_BOARD_HARDWARE_BMI160 (0x01C0U) 204 /** Module identifier for the E2271CS021 E-Ink Controller Library */ 205 #define CY_RSLT_MODULE_BOARD_HARDWARE_E2271CS021 (0x01C1U) 206 /** Module identifier for the NTC GPIO Thermistor Library */ 207 #define CY_RSLT_MODULE_BOARD_HARDWARE_THERMISTOR (0x01C2U) 208 /** Module identifier for the SSD1306 OLED Controller Library */ 209 #define CY_RSLT_MODULE_BOARD_HARDWARE_SSD1306 (0x01C3U) 210 /** Module identifier for the ST7789V TFT Controller Library */ 211 #define CY_RSLT_MODULE_BOARD_HARDWARE_ST7789V (0x01C4U) 212 /** Module identifier for the Light Sensor Library */ 213 #define CY_RSLT_MODULE_BOARD_HARDWARE_LIGHT_SENSOR (0x01C5U) 214 /** Module identifier for the AK4954A Audio Codec Library */ 215 #define CY_RSLT_MODULE_BOARD_HARDWARE_AK4954A (0x01C6U) 216 217 /** Base module identifier for Middleware Libraries (0x0200 - 0x02FF) */ 218 #define CY_RSLT_MODULE_MIDDLEWARE_BASE (0x0200U) 219 220 /** \} modules */ 221 222 #ifdef __cplusplus 223 } 224 #endif 225 226 #endif /* CY_RESULT_H */ 227 228 /** \} group_result */ 229
