1 /***************************************************************************//** 2 * \file cyhal_general_types.h 3 * 4 * \brief 5 * Provides basic types that are used across different HAL drivers. 6 * 7 ******************************************************************************** 8 * \copyright 9 * Copyright 2018-2021 Cypress Semiconductor Corporation (an Infineon company) or 10 * an affiliate of Cypress Semiconductor Corporation 11 * 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_hal_general_types General Types 29 * \ingroup group_hal_types 30 * \{ 31 * This section documents the basic types that are used by multiple HAL drivers. 32 */ 33 34 #pragma once 35 36 #include <stdint.h> 37 #include <stdbool.h> 38 #include "cy_result.h" 39 40 #if defined(__cplusplus) 41 extern "C" { 42 #endif 43 44 /** 45 * \addtogroup group_hal_results Result Codes 46 * \ingroup group_hal_types 47 * \{ 48 * HAL specific return codes definitions for all drivers. HAL drivers are generally 49 * built on top of a lower level driver. In this case the errors returned from the 50 * HAL could be one of the values below or a value from that lower level driver. 51 * See the device specific documentation for details about the other error codes. 52 * The HAL uses the same \ref CY_RSLT_CREATE macro to define result codes using 53 * the standard \ref cy_rslt_t format. All HAL results use the module ID \ref 54 * CY_RSLT_MODULE_ABSTRACTION_HAL. Driver distinction is done as part of the 16-bit 55 * code field. The HAL splits this into individual bytes. The upper byte signifies 56 * the HAL driver using values from the \ref cyhal_rslt_module_chip enum. The lower 57 * byte is defined by each HAL driver. 58 */ 59 60 61 /** 62 * Enum to specify module IDs for \ref cy_rslt_t values returned from the HAL. 63 */ 64 enum cyhal_rslt_module_chip 65 { 66 CYHAL_RSLT_MODULE_ADC = (0x01), //!< An error occurred in ADC module 67 CYHAL_RSLT_MODULE_CLOCK = (0x02), //!< An error occurred in Clock module 68 CYHAL_RSLT_MODULE_COMP = (0x03), //!< An error occurred in comparator module 69 CYHAL_RSLT_MODULE_CRC = (0x04), //!< An error occurred in crypto CRC module 70 CYHAL_RSLT_MODULE_DAC = (0x05), //!< An error occurred in DAC module 71 CYHAL_RSLT_MODULE_DMA = (0x06), //!< An error occurred in DMA module 72 CYHAL_RSLT_MODULE_EZI2C = (0x07), //!< An error occurred in EZI2C module 73 CYHAL_RSLT_MODULE_FLASH = (0x08), //!< An error occurred in flash module 74 CYHAL_RSLT_MODULE_GPIO = (0x09), //!< An error occurred in GPIO module 75 CYHAL_RSLT_MODULE_I2C = (0x0A), //!< An error occurred in I2C module 76 CYHAL_RSLT_MODULE_I2S = (0x0B), //!< An error occurred in I2S module 77 CYHAL_RSLT_MODULE_INTERCONNECT = (0x0C), //!< An error occurred in Interconnect module 78 CYHAL_RSLT_MODULE_HWMGR = (0x0D), //!< An error occurred in hardware management module 79 CYHAL_RSLT_MODULE_KEYSCAN = (0x0E), //!< An error occurred in KeyScan module 80 CYHAL_RSLT_MODULE_LPTIMER = (0x0F), //!< An error occured in LPTimer module 81 CYHAL_RSLT_MODULE_OPAMP = (0x10), //!< An error occurred in OpAmp module 82 CYHAL_RSLT_MODULE_PDMPCM = (0x11), //!< An error occurred in PDM/PCM module 83 CYHAL_RSLT_MODULE_PWM = (0x12), //!< An error occurred in PWM module 84 CYHAL_RSLT_MODULE_QSPI = (0x13), //!< An error occurred in QSPI module 85 CYHAL_RSLT_MODULE_QUADDEC = (0x14), //!< An error occurred in Quadrature Decoder module 86 CYHAL_RSLT_MODULE_RTC = (0x15), //!< An error occurred in RTC module 87 CYHAL_RSLT_MODULE_SDHC = (0x16), //!< An error occurred in SDHC module 88 CYHAL_RSLT_MODULE_SDIO = (0x17), //!< An error occurred in SDIO module 89 CYHAL_RSLT_MODULE_SPI = (0x18), //!< An error occurred in SPI module 90 CYHAL_RSLT_MODULE_SYSPM = (0x19), //!< An error occurred in SysPM module 91 CYHAL_RSLT_MODULE_SYSTEM = (0x1A), //!< An error occurred in System module 92 CYHAL_RSLT_MODULE_TDM = (0x1B), //!< An error occurred in Timer module 93 CYHAL_RSLT_MODULE_TIMER = (0x1C), //!< An error occurred in Timer module 94 CYHAL_RSLT_MODULE_TRNG = (0x1D), //!< An error occurred in RNG module 95 CYHAL_RSLT_MODULE_UART = (0x1E), //!< An error occurred in UART module 96 CYHAL_RSLT_MODULE_USB = (0x1F), //!< An error occurred in USB module 97 CYHAL_RSLT_MODULE_WDT = (0x20), //!< An error occurred in WDT module 98 // Implementation specific section 99 CYHAL_RSLT_MODULE_IMPL_TCPWM = (0x21), //!< An error occurred in TCPWM module (TCPWM based drivers are: Timer, PWM, Quadrature Decoder) 100 CYHAL_RSLT_MODULE_IMPL_SCB = (0x22), //!< An error occurred in SCB module (SCB based drivers are: I2C, SPI, UART) 101 }; 102 103 /** 104 * \} group_hal_results 105 */ 106 107 /** Modes that can be used for asynchronous transfers */ 108 typedef enum { 109 /** Use DMA if available. Otherwise fall back to software transfer. (Default) */ 110 CYHAL_ASYNC_DMA, 111 /** Always perform a software transfer */ 112 CYHAL_ASYNC_SW, 113 } cyhal_async_mode_t; 114 115 /** Enum of signal edge types */ 116 typedef enum 117 { 118 CYHAL_EDGE_TYPE_RISING_EDGE, //!< Rising edge 119 CYHAL_EDGE_TYPE_FALLING_EDGE, //!< Falling edge 120 CYHAL_EDGE_TYPE_BOTH_EDGES, //!< Both edges 121 CYHAL_EDGE_TYPE_LEVEL, //!< Level 122 } cyhal_edge_type_t; 123 124 /** @brief Selectable power levels. 125 * 126 * Power levels are defined relative to others. Higher power levels 127 * offer better performance but consume more power. 128 * 129 * Not all hardware supports four discrete power levels. If fewer 130 * power levels are supported, the values will be mapped as follows: 131 * | 4 Levels | 3 Levels | 2 Levels | 132 * | ---------------| -------------- | ----------------------------- | 133 * | Off | Off | Off | 134 * | Low | Low = Medium | Low = Medium = High = Default | 135 * | Medium | High = Default | | 136 * | High = Default | | | 137 * See the implementation specific documentation for details. 138 */ 139 typedef enum 140 { 141 /** Power-off the comparator, while retaining configuration */ 142 CYHAL_POWER_LEVEL_OFF, 143 /** Low comparator power and speed */ 144 CYHAL_POWER_LEVEL_LOW, 145 /** Medium comparator power and speed */ 146 CYHAL_POWER_LEVEL_MEDIUM, 147 /** High comparator power and speed */ 148 CYHAL_POWER_LEVEL_HIGH, 149 /** Default comparator power and speed */ 150 CYHAL_POWER_LEVEL_DEFAULT 151 } cyhal_power_level_t; 152 153 /** Signal trigger type */ 154 typedef enum 155 { 156 CYHAL_SIGNAL_TYPE_LEVEL = 0, //!< Level triggered 157 CYHAL_SIGNAL_TYPE_EDGE = 1, //!< Edge triggered 158 } cyhal_signal_type_t; 159 160 /** 161 * \addtogroup group_hal_syspm System Power Management 162 * \ingroup group_hal 163 * \{ 164 */ 165 166 /** Flags enum for the cpu state in a custom callback. This is used to indicate what 167 * states a callback should be called in. When a callback is called, only one of these 168 * will be set at a time. 169 */ 170 typedef enum 171 { 172 CYHAL_SYSPM_CB_CPU_SLEEP = 0x01U, /**< Flag for MCU sleep callback. */ 173 CYHAL_SYSPM_CB_CPU_DEEPSLEEP = 0x02U, /**< Flag for MCU deep sleep callback. */ 174 CYHAL_SYSPM_CB_SYSTEM_HIBERNATE = 0x04U, /**< Flag for Hibernate callback. */ 175 CYHAL_SYSPM_CB_SYSTEM_NORMAL = 0x08U, /**< Flag for Normal mode callback. */ 176 CYHAL_SYSPM_CB_SYSTEM_LOW = 0x10U, /**< Flag for Low power mode callback. */ 177 } cyhal_syspm_callback_state_t; 178 179 /** Define for enabling all system and MCU state callbacks .*/ 180 #define CYHAL_SYSPM_CALLBACK_STATE_ALL (CYHAL_SYSPM_CB_CPU_SLEEP\ 181 | CYHAL_SYSPM_CB_CPU_DEEPSLEEP\ 182 | CYHAL_SYSPM_CB_SYSTEM_HIBERNATE\ 183 | CYHAL_SYSPM_CB_SYSTEM_NORMAL\ 184 | CYHAL_SYSPM_CB_SYSTEM_LOW) 185 186 /** Enumeration of the transition modes in custom callback. The general sequence 187 * is: CHECK_READY, BEFORE_TRANSITION, AFTER_TRANSITION. 188 * If any callback indicates that it is not able to change state as part of 189 * CHECK_READY, CHECK_FAIL will be run instead of the BEFORE/AFTER_TRANSITION. 190 */ 191 typedef enum 192 { 193 CYHAL_SYSPM_CHECK_READY = 0x01U, /**< Callbacks with this mode are executed before entering into the 194 low power mode. The purpose of this transition state is to check 195 if the device is ready to enter the low power mode. The application 196 must not perform any actions that would prevent transition after 197 returning true for this mode. */ 198 CYHAL_SYSPM_CHECK_FAIL = 0x02U, /**< Callbacks with this mode are only executed if the callback returned true 199 for CYHAL_SYSPM_CHECK_READY and a later callback returns false for 200 CYHAL_SYSPM_CHECK_READY. This mode should roll back any changes made 201 to avoid blocking transition made in CYHAL_SYSPM_CHECK_READY mode*/ 202 CYHAL_SYSPM_BEFORE_TRANSITION = 0x04U, /**< Callbacks with this mode are executed after the CYHAL_SYSPM_CHECK_READY 203 callbacks' execution returns true. In this mode, the application must 204 perform the actions to be done before entering into the low power mode. */ 205 CYHAL_SYSPM_AFTER_TRANSITION = 0x08U, /**< In this mode, the application must perform the actions to be done after 206 exiting the low power mode. */ 207 } cyhal_syspm_callback_mode_t; 208 209 /** The system wide custom action power callback type. 210 * 211 * @param[in] state State the system or CPU is being transitioned into. 212 * @param[in] mode Callback mode. 213 * @param[in] callback_arg User argument passed as part of registering callback in @ref cyhal_syspm_register_callback. 214 * @return If mode is @ref CYHAL_SYSPM_CHECK_READY, then this indicates whether the low power mode should be allowed (true) or not (false). 215 Otherwise the return value is ignored. 216 */ 217 typedef bool (*cyhal_syspm_callback_t)(cyhal_syspm_callback_state_t state, cyhal_syspm_callback_mode_t mode, void* callback_arg); 218 219 /** Power management callback data object. This is used to register a new 220 * callback handler for power management transitions. The specific power 221 * states to register for can be specified as well as any modes 222 */ 223 typedef struct cyhal_syspm_callback_data 224 { 225 /** Callback to run on power state change */ 226 cyhal_syspm_callback_t callback; 227 /** Power states that should trigger calling the callback. Multiple 228 * \ref cyhal_syspm_callback_state_t values can be ored together. */ 229 cyhal_syspm_callback_state_t states; 230 /** Modes to ignore invoking the callback for. Multiple 231 * \ref cyhal_syspm_callback_mode_t values can be ored together. */ 232 cyhal_syspm_callback_mode_t ignore_modes; 233 /** Argument value to provide to the callback. */ 234 void *args; 235 /** Pointer to the next callback strucure. This should be initialized to NULL. */ 236 struct cyhal_syspm_callback_data *next; 237 } cyhal_syspm_callback_data_t; 238 239 /** 240 * \} group_hal_syspm 241 */ 242 243 /** 244 * \addtogroup group_hal_clock 245 * \{ 246 */ 247 248 /** Enum defining the different ways of specifying the acceptable clock tolerance. */ 249 typedef enum 250 { 251 CYHAL_TOLERANCE_HZ, //!< Clock tolerance specified directly in Hertz. 252 CYHAL_TOLERANCE_PPM, //!< Clock tolerance specified in parts-per-million. 253 CYHAL_TOLERANCE_PERCENT, //!< Clock tolerance specified in a percent. 254 } cyhal_clock_tolerance_unit_t; 255 256 /** Structure defining a clock tolerance. */ 257 typedef struct 258 { 259 cyhal_clock_tolerance_unit_t type; //!< The type of the clock tolerance value. 260 uint32_t value; //!< The tolerance value to use. 261 } cyhal_clock_tolerance_t; 262 263 /** 264 * \} group_hal_clock 265 */ 266 267 #if defined(__cplusplus) 268 } 269 #endif 270 271 /** \} group_hal_general_types */ 272
