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-2022 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_GPIO = (0x08), //!< An error occurred in GPIO module 74 CYHAL_RSLT_MODULE_I2C = (0x09), //!< An error occurred in I2C module 75 CYHAL_RSLT_MODULE_I2S = (0x0A), //!< An error occurred in I2S module 76 CYHAL_RSLT_MODULE_IPC = (0x0B), //!< An error occurred in IPC 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 occurred in LPTimer module 81 CYHAL_RSLT_MODULE_NVM = (0x10), //!< An error occurred in NVM module 82 CYHAL_RSLT_MODULE_OPAMP = (0x11), //!< An error occurred in OpAmp module 83 CYHAL_RSLT_MODULE_PDMPCM = (0x12), //!< An error occurred in PDM/PCM module 84 CYHAL_RSLT_MODULE_PWM = (0x13), //!< An error occurred in PWM module 85 CYHAL_RSLT_MODULE_QSPI = (0x14), //!< An error occurred in QSPI module 86 CYHAL_RSLT_MODULE_QUADDEC = (0x15), //!< An error occurred in Quadrature Decoder module 87 CYHAL_RSLT_MODULE_RTC = (0x16), //!< An error occurred in RTC module 88 CYHAL_RSLT_MODULE_SDHC = (0x17), //!< An error occurred in SDHC module 89 CYHAL_RSLT_MODULE_SDIO = (0x18), //!< An error occurred in SDIO module 90 CYHAL_RSLT_MODULE_SPI = (0x19), //!< An error occurred in SPI module 91 CYHAL_RSLT_MODULE_SYSPM = (0x1A), //!< An error occurred in SysPM module 92 CYHAL_RSLT_MODULE_SYSTEM = (0x1B), //!< An error occurred in System module 93 CYHAL_RSLT_MODULE_TDM = (0x1C), //!< An error occurred in Timer module 94 CYHAL_RSLT_MODULE_TIMER = (0x1D), //!< An error occurred in Timer module 95 CYHAL_RSLT_MODULE_TRNG = (0x1E), //!< An error occurred in RNG module 96 CYHAL_RSLT_MODULE_UART = (0x1F), //!< An error occurred in UART module 97 CYHAL_RSLT_MODULE_USB = (0x20), //!< An error occurred in USB module 98 CYHAL_RSLT_MODULE_WDT = (0x21), //!< An error occurred in WDT module 99 // Implementation specific section 100 CYHAL_RSLT_MODULE_IMPL_TCPWM = (0x22), //!< An error occurred in TCPWM module (TCPWM based drivers are: Timer, PWM, Quadrature Decoder) 101 CYHAL_RSLT_MODULE_IMPL_SCB = (0x23), //!< An error occurred in SCB module (SCB based drivers are: I2C, SPI, UART) 102 CYHAL_RSLT_MODULE_T2TIMER = (0x24), //!< An error occurred in T2Timer module 103 }; 104 105 /** 106 * \} group_hal_results 107 */ 108 109 /** Modes that can be used for asynchronous transfers */ 110 typedef enum { 111 /** Use DMA if available. Otherwise fall back to software transfer. (Default) */ 112 CYHAL_ASYNC_DMA, 113 /** Always perform a software transfer */ 114 CYHAL_ASYNC_SW, 115 } cyhal_async_mode_t; 116 117 /** Enum of signal edge types */ 118 typedef enum 119 { 120 CYHAL_EDGE_TYPE_RISING_EDGE, //!< Rising edge 121 CYHAL_EDGE_TYPE_FALLING_EDGE, //!< Falling edge 122 CYHAL_EDGE_TYPE_BOTH_EDGES, //!< Both edges 123 CYHAL_EDGE_TYPE_LEVEL, //!< Level 124 } cyhal_edge_type_t; 125 126 /** @brief Selectable power levels. 127 * 128 * Power levels are defined relative to others. Higher power levels 129 * offer better performance but consume more power. 130 * 131 * Not all hardware supports four discrete power levels. If fewer 132 * power levels are supported, the values will be mapped as follows: 133 * | 4 Levels | 3 Levels | 2 Levels | 134 * | ---------------| -------------- | ----------------------------- | 135 * | Off | Off | Off | 136 * | Low | Low = Medium | Low = Medium = High = Default | 137 * | Medium | High = Default | | 138 * | High = Default | | | 139 * See the implementation specific documentation for details. 140 */ 141 typedef enum 142 { 143 /** Power-off the comparator, while retaining configuration */ 144 CYHAL_POWER_LEVEL_OFF, 145 /** Low comparator power and speed */ 146 CYHAL_POWER_LEVEL_LOW, 147 /** Medium comparator power and speed */ 148 CYHAL_POWER_LEVEL_MEDIUM, 149 /** High comparator power and speed */ 150 CYHAL_POWER_LEVEL_HIGH, 151 /** Default comparator power and speed */ 152 CYHAL_POWER_LEVEL_DEFAULT 153 } cyhal_power_level_t; 154 155 /** Signal trigger type */ 156 typedef enum 157 { 158 CYHAL_SIGNAL_TYPE_LEVEL = 0, //!< Level triggered 159 CYHAL_SIGNAL_TYPE_EDGE = 1, //!< Edge triggered 160 } cyhal_signal_type_t; 161 162 /** 163 * \addtogroup group_hal_syspm System Power Management 164 * \ingroup group_hal 165 * \{ 166 */ 167 168 /** Flags enum for the cpu state in a custom callback. This is used to indicate what 169 * states a callback should be called in. When a callback is called, only one of these 170 * will be set at a time. 171 */ 172 typedef enum 173 { 174 CYHAL_SYSPM_CB_CPU_SLEEP = 0x01U, /**< Flag for MCU sleep callback. */ 175 CYHAL_SYSPM_CB_CPU_DEEPSLEEP = 0x02U, /**< Flag for MCU deep sleep callback. */ 176 CYHAL_SYSPM_CB_CPU_DEEPSLEEP_RAM = 0x04U, /**< Flag for MCU deep sleep ram callback. */ 177 CYHAL_SYSPM_CB_SYSTEM_HIBERNATE = 0x08U, /**< Flag for Hibernate callback. */ 178 CYHAL_SYSPM_CB_SYSTEM_NORMAL = 0x10U, /**< Flag for Normal mode callback. */ 179 CYHAL_SYSPM_CB_SYSTEM_LOW = 0x20U, /**< Flag for Low power mode callback. */ 180 } cyhal_syspm_callback_state_t; 181 182 /** Define for enabling all system and MCU state callbacks .*/ 183 #define CYHAL_SYSPM_CALLBACK_STATE_ALL (CYHAL_SYSPM_CB_CPU_SLEEP\ 184 | CYHAL_SYSPM_CB_CPU_DEEPSLEEP\ 185 | CYHAL_SYSPM_CB_CPU_DEEPSLEEP_RAM\ 186 | CYHAL_SYSPM_CB_SYSTEM_HIBERNATE\ 187 | CYHAL_SYSPM_CB_SYSTEM_NORMAL\ 188 | CYHAL_SYSPM_CB_SYSTEM_LOW) 189 190 /** Enumeration of the transition modes in custom callback. The general sequence 191 * is: CHECK_READY, BEFORE_TRANSITION, AFTER_TRANSITION. 192 * If any callback indicates that it is not able to change state as part of 193 * CHECK_READY, CHECK_FAIL will be run instead of the BEFORE/AFTER_TRANSITION. 194 */ 195 typedef enum 196 { 197 CYHAL_SYSPM_CHECK_READY = 0x01U, /**< Callbacks with this mode are executed before entering into the 198 low power mode. The purpose of this transition state is to check 199 if the device is ready to enter the low power mode. The application 200 must not perform any actions that would prevent transition after 201 returning true for this mode. */ 202 CYHAL_SYSPM_CHECK_FAIL = 0x02U, /**< Callbacks with this mode are only executed if the callback returned true 203 for CYHAL_SYSPM_CHECK_READY and a later callback returns false for 204 CYHAL_SYSPM_CHECK_READY. This mode should roll back any changes made 205 to avoid blocking transition made in CYHAL_SYSPM_CHECK_READY mode*/ 206 CYHAL_SYSPM_BEFORE_TRANSITION = 0x04U, /**< Callbacks with this mode are executed after the CYHAL_SYSPM_CHECK_READY 207 callbacks' execution returns true. In this mode, the application must 208 perform the actions to be done before entering into the low power mode. */ 209 CYHAL_SYSPM_AFTER_TRANSITION = 0x08U, /**< In this mode, the application must perform the actions to be done after 210 exiting the low power mode. */ 211 CYHAL_SYSPM_AFTER_DS_WFI_TRANSITION = 0x10U, /**< Performs the actions to be done after exiting the Deepsleep low 212 power mode if entered and before the interrupts are enabled.This mode is not 213 invoked on all devices, see the implementation specific documentation for details. */ 214 } cyhal_syspm_callback_mode_t; 215 216 /** The system wide custom action power callback type. 217 * 218 * @param[in] state State the system or CPU is being transitioned into. 219 * @param[in] mode Callback mode. 220 * @param[in] callback_arg User argument passed as part of registering callback in @ref cyhal_syspm_register_callback. 221 * @return If mode is @ref CYHAL_SYSPM_CHECK_READY, then this indicates whether the low power mode should be allowed (true) or not (false). 222 Otherwise the return value is ignored. 223 */ 224 typedef bool (*cyhal_syspm_callback_t)(cyhal_syspm_callback_state_t state, cyhal_syspm_callback_mode_t mode, void* callback_arg); 225 226 /** Power management callback data object. This is used to register a new 227 * callback handler for power management transitions. The specific power 228 * states to register for can be specified as well as any modes 229 */ 230 typedef struct cyhal_syspm_callback_data 231 { 232 /** Callback to run on power state change */ 233 cyhal_syspm_callback_t callback; 234 /** Power states that should trigger calling the callback. Multiple 235 * \ref cyhal_syspm_callback_state_t values can be ored together. */ 236 cyhal_syspm_callback_state_t states; 237 /** Modes to ignore invoking the callback for. Multiple 238 * \ref cyhal_syspm_callback_mode_t values can be ored together. */ 239 cyhal_syspm_callback_mode_t ignore_modes; 240 /** Argument value to provide to the callback. */ 241 void *args; 242 /** Pointer to the next callback strucure. This should be initialized to NULL. */ 243 struct cyhal_syspm_callback_data *next; 244 } cyhal_syspm_callback_data_t; 245 246 /** 247 * \} group_hal_syspm 248 */ 249 250 /** 251 * \addtogroup group_hal_clock 252 * \{ 253 */ 254 255 /** Enum defining the different ways of specifying the acceptable clock tolerance. */ 256 typedef enum 257 { 258 CYHAL_TOLERANCE_HZ, //!< Clock tolerance specified directly in Hertz. 259 CYHAL_TOLERANCE_PPM, //!< Clock tolerance specified in parts-per-million. 260 CYHAL_TOLERANCE_PERCENT, //!< Clock tolerance specified in a percent. 261 } cyhal_clock_tolerance_unit_t; 262 263 /** Structure defining a clock tolerance. */ 264 typedef struct 265 { 266 cyhal_clock_tolerance_unit_t type; //!< The type of the clock tolerance value. 267 uint32_t value; //!< The tolerance value to use. 268 } cyhal_clock_tolerance_t; 269 270 /** 271 * \} group_hal_clock 272 */ 273 274 #if defined(__cplusplus) 275 } 276 #endif 277 278 /** \} group_hal_general_types */ 279
