1 /***************************************************************************//** 2 * \file cyhal_comp.h 3 * 4 * Provides a high level interface for interacting with the Infineon Analog Comparator. 5 * This interface abstracts out the chip specific details. 6 * If any chip specific functionality is required the low level functions can 7 * be used directly. 8 * 9 ******************************************************************************** 10 * \copyright 11 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 12 * an affiliate of Cypress Semiconductor Corporation 13 * 14 * SPDX-License-Identifier: Apache-2.0 15 * 16 * Licensed under the Apache License, Version 2.0 (the "License"); 17 * you may not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, 24 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 *******************************************************************************/ 28 29 /** 30 * \addtogroup group_hal_comp COMP (Analog Comparator) 31 * \ingroup group_hal 32 * \{ 33 * High level interface for interacting with an analog Comparator. 34 * 35 * \section cyhal_comp_features Features 36 * The analog comparator measures one input voltage from the non-inverting pin against 37 * a second voltage provided on the inverting pin. The result of this comparison can 38 * be used in three ways: 39 * - Output to pin 40 * - Read state via firmware (see @ref cyhal_comp_read) 41 * - Event triggered on rising or falling edge (see @ref cyhal_comp_event_t) 42 * 43 * These three abilities can be used in any combination. 44 * 45 * \section cyhal_comp_quickstart Quickstart 46 * Call \ref cyhal_comp_init to initialize a comparator instance by providing the comparator 47 * object (**obj**), non-inverting input pin (**vin_p**), inverting input pin (**vin_m**), optional 48 * output pin (**output**), and configuration (**cfg**). 49 * 50 * Use \ref cyhal_comp_read to read the comparator state from firmware. 51 * 52 * Use \ref cyhal_comp_register_callback and \ref cyhal_comp_enable_event to configure a 53 * callback that will be invoked on a rising and/or falling edge of the comparator output. 54 * 55 * \section subsection_comp_snippets Code Snippets: 56 * \note Error checking is omitted for clarity 57 * \section subsection_comp_snippet_1 Snippet 1: Comparator initialization 58 * The following snippet initializes the comparator and powers it on 59 * \snippet hal_comp.c snippet_cyhal_comp_init 60 * 61 * \section subsection_comp_snippet_2 Snippet 2: Comparator read value 62 * The following snippet reads the current comparator value into a variable 63 * \snippet hal_comp.c snippet_cyhal_comp_read 64 * 65 * \section subsection_comp_snippet_3 Snippet 3: Comparator event registration 66 * The following snippet registers a callback that will be called on either a rising or falling 67 * edge of the comparator output. 68 * \snippet hal_comp.c snippet_cyhal_comp_event 69 * 70 * \section subsection_comp_snippet_4 Snippet 4: Comparator powering-off and on 71 * The following snippet demonstrates temporarily powering-off the comparator without freeing it. 72 * \snippet hal_comp.c snippet_cyhal_comp_start_stop 73 * 74 */ 75 76 #pragma once 77 78 #include <stdint.h> 79 #include <stdbool.h> 80 #include "cyhal_gpio.h" 81 #include "cy_result.h" 82 #include "cyhal_hw_types.h" 83 84 #if defined(__cplusplus) 85 extern "C" { 86 #endif 87 88 /** \addtogroup group_hal_results_comp Comparator HAL Results 89 * Comparator specific return codes 90 * \ingroup group_hal_results 91 * \{ *//** 92 */ 93 94 /** The requested pins are invalid */ 95 #define CYHAL_COMP_RSLT_ERR_INVALID_PIN \ 96 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_COMP, 1)) 97 /** Bad argument */ 98 #define CYHAL_COMP_RSLT_ERR_BAD_ARGUMENT \ 99 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_COMP, 2)) 100 101 /** 102 * \} 103 */ 104 105 /** Comparator event types */ 106 typedef enum 107 { 108 CYHAL_COMP_RISING_EDGE = 0x01, //!< Rising edge on comparator output 109 CYHAL_COMP_FALLING_EDGE = 0x02, //!< Falling edge on comparator output 110 } cyhal_comp_event_t; 111 112 /** Configuration options for the Comparator */ 113 typedef struct 114 { 115 /** Power mode the comparator should operate in. Lower modes save power but operate at lower speed. */ 116 cyhal_power_level_t power; 117 /** Whether hysteresis should be used. See the implementation-specific documentation for the hysteresis value */ 118 bool hysteresis; 119 } cyhal_comp_config_t; 120 121 /** 122 * Handler for Comparator events 123 * 124 * \note Not all hardware is capable of differentiating which type of edge triggered an 125 * event when both rising and falling edges are enabled. If the edge cannot be determined, 126 * the `event` argument will be `CYHAL_COMP_RISING_EDGE | CYHAL_COMP_FALLING_EDGE` 127 */ 128 typedef void (*cyhal_comp_event_callback_t)(void *callback_arg, cyhal_comp_event_t event); 129 130 131 /** Initialize the Comparator peripheral. 132 * 133 * @param[out] obj Pointer to a Comparator object. The caller must allocate the memory 134 * for this object but the init function will initialize its contents. 135 * @param[in] vin_p Non-inverting input pin 136 * @param[in] vin_m Inverting input pin 137 * @param[in] output Comparator output pin. May be @ref NC. 138 * @param[in] cfg Configuration structure 139 * @return The status of the init request 140 */ 141 cy_rslt_t cyhal_comp_init(cyhal_comp_t *obj, cyhal_gpio_t vin_p, cyhal_gpio_t vin_m, cyhal_gpio_t output, cyhal_comp_config_t *cfg); 142 143 /** Initialize the comparator peripheral using a configurator generated configuration struct 144 * 145 * @param[out] obj Pointer to a comparator object. The caller must allocate the memory 146 * for this object but the init function will initialize its contents. 147 * @param[in] cfg Configuration structure generated by a configurator. 148 * @return The status of the init request 149 */ 150 cy_rslt_t cyhal_comp_init_cfg(cyhal_comp_t *obj, const cyhal_comp_configurator_t *cfg); 151 152 /** Deinitialize the Comparator peripheral. 153 * 154 * @param[in] obj Comparator object 155 */ 156 void cyhal_comp_free(cyhal_comp_t *obj); 157 158 /** Changes the current operating power level of the comparator. 159 * 160 * If the power level is set to @ref CYHAL_POWER_LEVEL_OFF, the comparator will be powered-off 161 * but it will retain its configuration, so it is not necessary to reconfigure it when changing 162 * the power level from @ref CYHAL_POWER_LEVEL_OFF to any other value. 163 * 164 * @param[in] obj Comparator object 165 * @param[in] power The power level to set 166 * @return The status of the set power request 167 */ 168 cy_rslt_t cyhal_comp_set_power(cyhal_comp_t *obj, cyhal_power_level_t power); 169 170 /** Reconfigure the Comparator. 171 * 172 * This retains the powered state of the comparator. 173 * Depending on the implementation, it may be necessary to temporarily deconfigure and/or 174 * power off the comparator in order to apply the new configuration. However, if the 175 * comparator is powered-off when this function is called, it will remain powered-off after 176 * it returns. Likewise, if the comparator is powered-on when this function is called, 177 * it will remain powered-on after it returns. 178 * 179 * @param[in] obj Comparator object 180 * @param[in] cfg New configuration to apply 181 * @return The status of the configure request 182 */ 183 cy_rslt_t cyhal_comp_configure(cyhal_comp_t *obj, cyhal_comp_config_t *cfg); 184 185 /** Reads the Comparator state. 186 * 187 * @param[in] obj Comparator object 188 * @return The Comparator state. True if the non-inverting pin voltage is greater than the 189 * inverting pin voltage, false otherwise. 190 */ 191 bool cyhal_comp_read(cyhal_comp_t *obj); 192 193 /** Register/clear a callback handler for Comparator events 194 * 195 * This function will be called when one of the events enabled by \ref cyhal_comp_enable_event occurs. 196 * 197 * @param[in] obj Comparator object 198 * @param[in] callback Function to call when the specified event happens 199 * @param[in] callback_arg Generic argument that will be provided to the handler when called 200 */ 201 void cyhal_comp_register_callback(cyhal_comp_t *obj, cyhal_comp_event_callback_t callback, void *callback_arg); 202 203 /** Enable or Disable a Comparator event 204 * 205 * When an enabled event occurs, the function specified by \ref cyhal_comp_register_callback will be called. 206 * 207 * @param[in] obj Comparator object 208 * @param[in] event Comparator event 209 * @param[in] intr_priority Priority for NVIC interrupt events 210 * @param[in] enable True to turn on event, False to turn off 211 */ 212 void cyhal_comp_enable_event(cyhal_comp_t *obj, cyhal_comp_event_t event, uint8_t intr_priority, bool enable); 213 214 215 #if defined(__cplusplus) 216 } 217 #endif 218 219 #ifdef CYHAL_COMP_IMPL_HEADER 220 #include CYHAL_COMP_IMPL_HEADER 221 #endif /* CYHAL_COMP_IMPL_HEADER */ 222 223 /** \} group_hal_comp */ 224
