1 /***************************************************************************//** 2 * \file cyhal_adc.h 3 * 4 * \brief 5 * Provides a high level interface for interacting with the Infineon Analog to 6 * Digital Converter. This interface abstracts out the chip specific details. 7 * If any chip specific functionality is necessary, or performance is critical 8 * the low level functions can be used directly. 9 * 10 ******************************************************************************** 11 * \copyright 12 * Copyright 2018-2021 Cypress Semiconductor Corporation (an Infineon company) or 13 * an affiliate of Cypress Semiconductor Corporation 14 * 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); 18 * you may not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, 25 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 *******************************************************************************/ 29 30 /** 31 * \addtogroup group_hal_adc ADC (Analog to Digital Converter) 32 * \ingroup group_hal 33 * \{ 34 * High level interface for interacting with the analog to digital converter (ADC). 35 * 36 * \section cyhal_adc_features Features 37 * Each ADC instance supports one or more selectable channels, each 38 * of which can perform conversions on a different pin. 39 * See the device datasheet for details about which pins support ADC conversion. 40 * 41 * Both single-ended and differential channels are supported. The values returned 42 * by the read API are relative to the ADC's voltage range, which is device specific. 43 * See the BSP documentation for details. 44 * 45 * \section cyhal_adc_quickstart Quickstart 46 * Call \ref cyhal_adc_init to initialize an ADC instance by providing the ADC 47 * object (<b>obj</b>), input pin (<b>pin</b>) and clock (<b>clk</b>).<br> The input 48 * pin argument is just to signify which ADC instance to initialize. It does not 49 * actually reserve the pin or create an ADC channel for it. The clock parameter can 50 * be left NULL to use an available clock resource with a default frequency.<br> 51 * Use \ref cyhal_adc_channel_init_diff to initialize one or more channels associated 52 * with that instance.<br> 53 * Use \ref cyhal_adc_read for reading the results.<br> 54 * See \ref subsection_adc_snippet_1. 55 * 56 * \note \ref cyhal_adc_read_u16 always returns a 16 bit value in the range 57 * 0x0000-0xFFFF. If the underlying hardware does not support 16 bit resolution the 58 * value is scaled linearly to cover the full 16 bits. 59 * 60 * \section subsection_adc_snippets Code snippets 61 * \note Error checking is omitted for clarity 62 * \subsection subsection_adc_snippet_1 Snippet 1: Simple ADC initialization and reading conversion result 63 * The following snippet initializes an ADC and one channel. 64 * One ADC conversion result is returned corresponding to the input at the specified 65 * pin. 66 * \snippet hal_adc.c snippet_cyhal_adc_simple_init 67 * 68 * \subsection subsection_adc_snippet_2 Snippet 2: Multi-channel ADC initialization and reading conversion result 69 * The following snippet initializes an ADC with one single-ended channel and one differential channel 70 * \snippet hal_adc.c snippet_cyhal_adc_multi_init 71 * 72 * \subsection subsection_adc_snippet_3 Snippet 3: Asynchronously read multiple channels 73 * The following snippet illustrates how to asynchronously read multiple scans of multiple channels. 74 * \snippet hal_adc.c snippet_cyhal_adc_async_read 75 * 76 * \subsection subsection_adc_snippet_4 Snippet 4: Continuous scanning 77 * This snippet shows how to run the ADC in continuous mode and process results as each scan completes. 78 * \snippet hal_adc.c snippet_cyhal_adc_continuous_read 79 */ 80 81 #pragma once 82 83 #include <stdint.h> 84 #include <stdbool.h> 85 #include "cy_result.h" 86 #include "cyhal_hw_types.h" 87 #include "cyhal_gpio.h" 88 89 #if defined(__cplusplus) 90 extern "C" { 91 #endif 92 93 /** \addtogroup group_hal_results_adc ADC HAL Results 94 * ADC specific return codes 95 * \ingroup group_hal_results 96 * \{ *//** 97 */ 98 99 /** Bad argument */ 100 #define CYHAL_ADC_RSLT_BAD_ARGUMENT \ 101 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_ADC, 0)) 102 /** Failed to initialize ADC clock */ 103 #define CYHAL_ADC_RSLT_FAILED_CLOCK \ 104 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_ADC, 1)) 105 /** Failed to initialize ADC */ 106 #define CYHAL_ADC_RSLT_FAILED_INIT \ 107 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_ADC, 2)) 108 /** No channels available */ 109 #define CYHAL_ADC_RSLT_NO_CHANNELS \ 110 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_ADC, 3)) 111 112 /** 113 * \} 114 */ 115 116 /** Number of bits populated with meaningful data by each ADC sample */ 117 #define CYHAL_ADC_BITS 16 118 /** Maximum value that the ADC can return */ 119 #define CYHAL_ADC_MAX_VALUE ((1 << CYHAL_ADC_BITS) - 1) 120 121 /** Possible selections for ADC reference */ 122 typedef enum 123 { 124 CYHAL_ADC_REF_INTERNAL, //!< Internal reference. See the BSP documentation for the value of this reference. (Default) 125 CYHAL_ADC_REF_EXTERNAL, //!< Reference from external pin. 126 CYHAL_ADC_REF_VDDA, //!< Reference from VDDA (analog supply) 127 CYHAL_ADC_REF_VDDA_DIV_2, //!< Reference from VDDA (analog supply) divided by 2 128 } cyhal_adc_vref_t; 129 130 /** Vminus selection for single-ended channels */ 131 typedef enum 132 { 133 CYHAL_ADC_VNEG_VSSA, //!< Connect vminus to ground. 134 CYHAL_ADC_VNEG_VREF, //!< Connect vminus to the selected vref (see @ref cyhal_adc_vref_t) 135 } cyhal_adc_vneg_t; 136 137 /** ADC events */ 138 typedef enum 139 { 140 CYHAL_ADC_EOS = 1u, //!< End of scan: a scan of all channels has completed. Only applicable when continuously scanning 141 CYHAL_ADC_ASYNC_READ_COMPLETE = 2u, //!< An asynchronous read operation has completed. 142 } cyhal_adc_event_t; 143 144 /** Selections for ADC input signals */ 145 typedef enum 146 { 147 CYHAL_ADC_INPUT_START_SCAN, // !< Start a scan when a signal is received 148 } 149 cyhal_adc_input_t; 150 151 /** Selections for ADC output signals */ 152 typedef enum 153 { 154 CYHAL_ADC_OUTPUT_SCAN_COMPLETE, // !< An output signal should be triggered when a scan is complete 155 } 156 cyhal_adc_output_t; 157 158 /** Perform standard averaging. Divide the accumulated value by the number of samples. 159 * @note This is not supported in combination with @ref CYHAL_ADC_AVG_MODE_ACCUMULATE */ 160 #define CYHAL_ADC_AVG_MODE_AVERAGE (1u << 0) 161 /** Accumulate samples as in @ref CYHAL_ADC_AVG_MODE_AVERAGE, but do not divide by the number of samples */ 162 #define CYHAL_ADC_AVG_MODE_ACCUMULATE (1u << 1) 163 /** Average mode flag position indices shifted by greater than this are implementation specific. The value 164 * of this macro is subject to change between HAL versions. */ 165 #define CYHAL_ADC_AVG_MODE_MAX_SHIFT (1u) 166 167 /** Selects the default connection for the inverting input to achieve a single-ended channel. This connection 168 * is controlled by the `vneg` member of @ref cyhal_adc_config_t. 169 */ 170 #define CYHAL_ADC_VNEG CYHAL_NC_PIN_VALUE 171 172 /** ADC Configuration */ 173 typedef struct 174 { 175 /** Whether the ADC samples continuously (true) or only on demand (false). 176 * 177 * When configured to true, the ADC will immediately begin scanning all configured channels. 178 * When configured to false, the ADC will stop continuous scanning at the completion of the current scan 179 */ 180 bool continuous_scanning; 181 /** ADC resolution. See the implementation specific documentation for supported values */ 182 uint8_t resolution; 183 /** The number of samples that should be averaged together to obtain a result. A value of 1 disables averaging. */ 184 uint16_t average_count; 185 /** Flags to control the behavior of the averaging functionality when @ref average_count is greater than 1. 186 * This field contains zero or more flags that are OR'd together. All implementations define 187 * @ref CYHAL_ADC_AVG_MODE_AVERAGE and @ref CYHAL_ADC_AVG_MODE_ACCUMULATE (though some may not support both modes). 188 * Some implementations may define other flags to control additional aspects of the averaging functionality; see 189 * the implementation-specific documentation for details. 190 */ 191 uint32_t average_mode_flags; 192 /** The external voltage reference value, in millivolts. 193 * If vref is set to @ref CYHAL_ADC_REF_EXTERNAL, this must be nonzero. 194 * If vref is set to anything other than @ref CYHAL_ADC_REF_EXTERNAL, this must be zero. 195 */ 196 uint32_t ext_vref_mv; 197 /** Vminus selection for single-ended channels */ 198 cyhal_adc_vneg_t vneg; 199 /** ADC voltage reference */ 200 cyhal_adc_vref_t vref; 201 /** The GPIO that should be used for the external reference. If @ref CYHAL_ADC_REF_EXTERNAL 202 * is selected and the current target uses a GPIO for ADC ext_vref (see the BSP documentation), 203 * this must not be @ref NC. If the current target uses a dedicated pin (not a GPIO) for ADC ext_vref, 204 * or if any other reference is selected, this must be @ref NC. 205 */ 206 cyhal_gpio_t ext_vref; 207 /** Whether an external bypass capacitor should be used. Depending on the platform this may be required 208 * to reduce noise at sufficiently high sample rates. See the implementation specific documentation 209 * for details. 210 */ 211 bool is_bypassed; 212 /** The GPIO pin that should be used for the bypass capacitor. If `is_bypassed` is true and the current target 213 * uses a GPIO for the bypass capacitor connection, this must not be @ref NC. Otherwise, this must be @ref NC. 214 * Depending on the device, this may be the same GPIO as `ext_vref`. See the BSP documentation for details. 215 */ 216 cyhal_gpio_t bypass_pin; 217 } cyhal_adc_config_t; 218 219 /** ADC Channel Configuration */ 220 typedef struct 221 { 222 /** Whether this channel should be sampled when the ADC performs a scan */ 223 bool enabled; 224 /** Enable or disable averaging for this channel. 225 * All other aspects of the averging functionality are configured in @ref cyhal_adc_config_t 226 */ 227 bool enable_averaging; 228 /** Minimum time that this channel should be sampled, in nanoseconds. The actual time may be greater 229 * than this depending on hardware limitations, the sample rate, and the configuration of other channels. 230 * @note While this value is specified in ns, the underlying hardware generally does not support 231 * acquisition time with a granularity of 1 ns. See the implementation specific documentation for details. 232 */ 233 uint32_t min_acquisition_ns; 234 } cyhal_adc_channel_config_t; 235 236 /** Handler for ADC event callbacks */ 237 typedef void (*cyhal_adc_event_callback_t)(void *callback_arg, cyhal_adc_event_t event); 238 239 /** Initialize ADC peripheral 240 * 241 * The ADC will be initialized with the following default configuration: 242 * - Sample rate: See implementation-specific documentation 243 * - Average count: 1 (averaging disabled). 244 * - Continuous scanning: false 245 * - Single ended vneg: @ref CYHAL_ADC_VNEG_VREF 246 * - Vref: @ref CYHAL_ADC_REF_INTERNAL 247 * - External vref: @ref NC 248 * - Bypassed: false 249 * - Bypass pin: @ref NC 250 * - Power level: @ref CYHAL_POWER_LEVEL_DEFAULT 251 * 252 * To change the configuration, see @ref cyhal_adc_configure 253 * 254 * @param[out] obj Pointer to an ADC object. The caller must allocate the memory 255 * for this object but the init function will initialize its contents. 256 * @param[in] pin A pin corresponding to the ADC block to initialize 257 * Note: This pin is not reserved, it is just used to identify which ADC block to allocate. 258 * If multiple channels will be allocated for a single ADC instance, only one pin should be 259 * passed here; it does not matter which one. After calling this function once, call 260 * @ref cyhal_adc_channel_init_diff once for each pin whose value should be measured. 261 * @param[in] clk The clock to use can be shared, if not provided a new clock will be allocated 262 * @return The status of the init request. \ref CY_RSLT_SUCCESS is returned on success. 263 * On failure, a problem specific error code will be returned. 264 * This error could be from the HAL or lower level driver.<br> 265 * For all other return codes, please refer to device driver documentation available in the BSP landing page 266 */ 267 cy_rslt_t cyhal_adc_init(cyhal_adc_t *obj, cyhal_gpio_t pin, const cyhal_clock_t *clk); 268 269 /** Initialize the ADC peripheral and its channels using a configurator generated configuration struct 270 * 271 * @param[out] adc Pointer to an adc object. The caller must allocate the memory 272 * for this object but the init function will initialize its contents. 273 * @param[out] channels Array of pointers to ADC channel objects. This array must contain 274 * a minimum of one (non-null) entry per channel that is enabled by the configurator 275 * @param[in,out] num_channels Length of the `channels` array. If this value is too small for all of the channels 276 * enabled by the configurator an error will be returned. Will be updated with the 277 * number of channels that were enabled by the configurator. 278 * @param[in] cfg Configuration structure generated by the configurator. 279 * @return The status of the init request 280 */ 281 cy_rslt_t cyhal_adc_init_cfg(cyhal_adc_t *adc, cyhal_adc_channel_t** channels, uint8_t* num_channels, 282 const cyhal_adc_configurator_t *cfg); 283 284 /** Uninitialize the ADC peripheral and cyhal_adc_t object 285 * 286 * @param[in,out] obj The ADC object 287 */ 288 void cyhal_adc_free(cyhal_adc_t *obj); 289 290 /** Update the ADC configuration. 291 * 292 * @note If a scan is in progress, this may cause it to be interrupted. 293 * 294 * @param[in] obj The ADC object 295 * @param[in] config The configuration to apply 296 * @return The status of the configuration request 297 * On failure, a problem specific error code will be returned. 298 * This error could be from the HAL or lower level driver.<br> 299 * For all other return codes, please refer to device driver documentation available in the BSP landing page 300 */ 301 cy_rslt_t cyhal_adc_configure(cyhal_adc_t *obj, const cyhal_adc_config_t *config); 302 303 /** Changes the current operating power level of the ADC. 304 * 305 * If the power level is set to @ref CYHAL_POWER_LEVEL_OFF, the ADC will be powered-off 306 * but it will retain its configuration, so it is not necessary to reconfigure it when changing 307 * the power level from @ref CYHAL_POWER_LEVEL_OFF to any other value. 308 * 309 * @param[in] obj ADC object 310 * @param[in] power The power level to set 311 * @return The status of the set power request 312 * On failure, a problem specific error code will be returned. 313 * This error could be from the HAL or lower level driver.<br> 314 * For all other return codes, please refer to device driver documentation available in the BSP landing page 315 */ 316 cy_rslt_t cyhal_adc_set_power(cyhal_adc_t *obj, cyhal_power_level_t power); 317 318 /** Configure the number of samples per second. 319 * 320 * This is the number of times each enabled channel is sampled per second. The total number of samples performed 321 * by the ADC hardware per second is equal to `sample_rate_hz / num_channels_enabled`. 322 * Depending on the system clock configuration or limitations of the underlying hardware, it may not be possible 323 * to achieve precisely the desired sample rate. The `achived_sample_rate_hz` parameter will be updated to indicate 324 * the sample rate that was achived. 325 * @note The `achieved_sample_rate_hz` value is only valid while the configuration of the ADC and its channels remains 326 * umodified. If @ref cyhal_adc_configure, @ref cyhal_adc_channel_init_diff, @ref cyhal_adc_channel_configure, 327 * or @ref cyhal_adc_channel_free is called, it is necessary to call this function again in order to update the sample rate. 328 * Therefore, it is recommended to call this function after the ADC and all channels have been configured. 329 * 330 * @param[in] obj The ADC object to configure 331 * @param[in] desired_sample_rate_hz The desired sample rate, in hertz 332 * @param[out] achieved_sample_rate_hz The achieved sample rate, in hertz 333 * 334 * @return The status of the sample rate request. Note that inability to exactly match the requested sample 335 * rate is not considered an error. It is the application's responsibility to determine whether the achived rate 336 * is within the tolerance that it requires. 337 * \ref CY_RSLT_SUCCESS is returned on success.<br> 338 * On failure, a problem specific error code will be returned. This error could be from the HAL or lower level driver.<br> 339 * For all other return codes, please refer to device driver documentation available in the BSP landing page 340 */ 341 cy_rslt_t cyhal_adc_set_sample_rate(cyhal_adc_t* obj, uint32_t desired_sample_rate_hz, uint32_t* achieved_sample_rate_hz); 342 343 /** Initialize a differential ADC channel. 344 * @note: Some platforms may restrict which pins can be used as part of a differential pair. See the 345 * implementation-specific documentation for details. 346 * 347 * Configures the pin used by ADC. 348 * @param[out] obj The ADC channel object to initialize 349 * @param[in] adc The ADC for which the channel should be initialized 350 * @param[in] vplus Non-inverting input 351 * @param[in] vminus Inverting input. For a single ended channel, use @ref CYHAL_ADC_VNEG. 352 * @param[in] cfg The ADC channel configuration 353 * @return The status of the init request. 354 * On failure, a problem specific error code will be returned. 355 * This error could be from the HAL or lower level driver.<br> 356 * For all other return codes, please refer to device driver documentation available in the BSP landing page 357 */ 358 cy_rslt_t cyhal_adc_channel_init_diff(cyhal_adc_channel_t *obj, cyhal_adc_t* adc, cyhal_gpio_t vplus, cyhal_gpio_t vminus, const cyhal_adc_channel_config_t* cfg); 359 360 /** Update the ADC channel configuration. 361 * 362 * @note If a scan is in progress, this may cause it to be interrupted. It is not valid to change the enabled state 363 * of a channel while an asynchronous read operation is in progress. 364 * 365 * @param[in] obj The ADC channel object 366 * @param[in] config The configuration to apply 367 * @return The status of the configuration request 368 * On failure, a problem specific error code will be returned. 369 * This error could be from the HAL or lower level driver.<br> 370 * For all other return codes, please refer to device driver documentation available in the BSP landing page 371 */ 372 cy_rslt_t cyhal_adc_channel_configure(cyhal_adc_channel_t *obj, const cyhal_adc_channel_config_t *config); 373 374 /** Uninitialize the ADC channel and cyhal_adc_channel_t object 375 * 376 * @param[in,out] obj The ADC channel object 377 */ 378 void cyhal_adc_channel_free(cyhal_adc_channel_t *obj); 379 380 /** Read the value from the ADC pin, represented as an unsigned 16bit value 381 * where 0x0000 represents the minimum value in the ADC's range, and 0xFFFF 382 * represents the maximum value in the ADC's range. 383 * If continous scanning is disabled, this will block while a conversion is 384 * performed on the selected channel, then return the result. Depending on the 385 * ADC speed this function may block for some time. 386 * If continuous scanning is enabled, this will return the value from the most 387 * recent conversion of the specified channel (if called shortly after enabling 388 * continuous scanning it may block until at least one conversion has been performed 389 * on this channel). 390 * 391 * @param[in] obj The ADC object 392 * @return An unsigned 16bit value representing the current input voltage 393 */ 394 uint16_t cyhal_adc_read_u16(const cyhal_adc_channel_t *obj); 395 396 /** Read the value from ADC pin, represented as a 32-bit signed, right-aligned value. 397 * 398 * This is a 'resolution'-bit value, sign-extended to 32 bits. If the vplus signal is 399 * below the vminus signal, the result will be negative. If the vplus signal is above 400 * the vminus signal, the result will be positive. 401 * If continous scanning is disabled, this will block while a conversion is 402 * performed on the selected channel, then return the result. Depending on the 403 * ADC speed this function may block for some time. 404 * If continuous scanning is enabled, this will return the value from the most 405 * recent conversion of the specified channel (if called shortly after enabling 406 * continuous scanning it may block until at least one conversion has been performed 407 * on this channel). 408 * 409 * @param[in] obj The ADC object 410 * @return A signed 32 bit value representing the current input voltage 411 */ 412 int32_t cyhal_adc_read(const cyhal_adc_channel_t *obj); 413 414 /** Read the value from ADC pin, in microvolts. 415 * 416 * If continous scanning is disabled, this will block while a conversion is 417 * performed on the selected channel, then return the result. Depending on the 418 * ADC speed this function may block for some time. 419 * If continuous scanning is enabled, this will return the value from the most 420 * recent conversion of the specified channel (if called shortly after enabling 421 * continuous scanning it may block until at least one conversion has been performed 422 * on this channel). 423 * 424 * @param[in] obj The ADC object 425 * @return An unsigned 32 bit value representing the current input in microvolts 426 */ 427 int32_t cyhal_adc_read_uv(const cyhal_adc_channel_t *obj); 428 429 /** Scan the specified ADC channels in the background and copy the results 430 * into the array pointed to by `result_list`. 431 * 432 * Results are represented as 32-bit signed, right-aligned values. That is, they are 433 * 'resolution'-bit values, sign-extended to 32 bits. If the vplus signal is 434 * below the vminus signal, the result will be negative. If the vplus signal is above 435 * the vminus signal, the result will be positive. 436 * 437 * If continuous scanning is disabled, this will trigger num_scan new scans and copy the results 438 * into `result_list` once the scan is completed. 439 * 440 * If continuous scanning is enabled, this will copy the results of num_scan scans into the result_list as 441 * they complete, beginning with the most recently completed scan (if one exists). 442 * 443 * Scan results are placed sequentially into result_list. That is, result_list will contain all of the results from the 444 * first scan, followed by all of the results from the second scan, etc. If channels exist that are initialized but not 445 * enabled, they will consume locations in result_list, but these values are undefined. 446 * 447 * When the requested number of scans have been completed, the @ref CYHAL_ADC_ASYNC_READ_COMPLETE event will be raised. 448 * 449 * @ref cyhal_adc_set_async_mode can be used to control whether this uses DMA or a SW (CPU-driven) transfer. 450 * 451 * @param[in] obj ADC to read from 452 * @param[in] num_scan The number of scans of each channel that should be read 453 * @param[in] result_list The array where results should be. This must be of length num_scan * initialized_channels, 454 * where initialized_channels is the number of channels that have been initialized for this ADC 455 * (and not later freed) via @ref cyhal_adc_channel_init_diff 456 * @return The status of the read async request 457 * On failure, a problem specific error code will be returned. 458 * This error could be from the HAL or lower level driver.<br> 459 * For all other return codes, please refer to device driver documentation available in the BSP landing page 460 */ 461 cy_rslt_t cyhal_adc_read_async(cyhal_adc_t* obj, size_t num_scan, int32_t* result_list); 462 463 /** Scan the specified ADC channels in the background and copy the conversion results in microvolts 464 * into the array pointed to by `result_list`. 465 * 466 * If continuous scanning is disabled, this will trigger num_scan new scans and copy the results 467 * into `result_list` once the scan is completed. 468 * 469 * If continuous scanning is enabled, this will copy the results of num_scan scans into the result_list as 470 * they complete, beginning with the most recently completed scan (if one exists). 471 * 472 * Scan results are placed sequentially into result_list. That is, result_list will contain all of the results from the 473 * first scan, followed by all of the results from the second scan, etc. If channels exist that are initialized but not 474 * enabled, they will consume locations in result_list, but these values are undefined. 475 * 476 * When the requested number of scans have been completed, the @ref CYHAL_ADC_ASYNC_READ_COMPLETE event will be raised. 477 * 478 * @ref cyhal_adc_set_async_mode can be used to control whether this uses DMA or a SW (CPU-driven) transfer. 479 * 480 * @param[in] obj ADC to read from 481 * @param[in] num_scan The number of scans of each channel that should be read 482 * @param[in] result_list The array where results should be. This must be of length num_scan * initialized_channels, 483 * where initialized_channels is the number of channels that have been initialized for this ADC 484 * (and not later freed) via @ref cyhal_adc_channel_init_diff 485 * @return The status of the read async request 486 * On failure, a problem specific error code will be returned. 487 * This error could be from the HAL or lower level driver.<br> 488 * For all other return codes, please refer to device driver documentation available in the BSP landing page 489 */ 490 cy_rslt_t cyhal_adc_read_async_uv(cyhal_adc_t* obj, size_t num_scan, int32_t* result_list); 491 492 /** Set the mechanism that is used to perform ADC asynchronous transfers. The default is SW. 493 * @warning The effect of calling this function while an async transfer is pending is undefined. 494 * 495 * @param[in] obj The ADC object 496 * @param[in] mode The transfer mode 497 * @param[in] dma_priority The priority, if DMA is used. Valid values are the same as for @ref cyhal_dma_init. 498 * If DMA is not selected, the only valid value is CYHAL_DMA_PRIORITY_DEFAULT, and no 499 guarantees are made about prioritization. 500 * @return The status of the set mode request 501 * On failure, a problem specific error code will be returned. 502 * This error could be from the HAL or lower level driver.<br> 503 * For all other return codes, please refer to device driver documentation available in the BSP landing page 504 */ 505 cy_rslt_t cyhal_adc_set_async_mode(cyhal_adc_t *obj, cyhal_async_mode_t mode, uint8_t dma_priority); 506 507 /** Register an ADC callback handler 508 * 509 * This function will be called when one of the events enabled by \ref cyhal_adc_enable_event occurs. 510 * 511 * @param[in] obj The ADC object 512 * @param[in] callback The callback handler which will be invoked when the interrupt fires 513 * @param[in] callback_arg Generic argument that will be provided to the callback when called 514 */ 515 void cyhal_adc_register_callback(cyhal_adc_t *obj, cyhal_adc_event_callback_t callback, void *callback_arg); 516 517 /** Configure ADC events. 518 * 519 * When an enabled event occurs, the function specified by \ref cyhal_adc_register_callback will be called. 520 * 521 * @param[in] obj The ADC object 522 * @param[in] event The ADC event type 523 * @param[in] intr_priority The priority for NVIC interrupt events 524 * @param[in] enable True to turn on specified events, False to turn off 525 */ 526 void cyhal_adc_enable_event(cyhal_adc_t *obj, cyhal_adc_event_t event, uint8_t intr_priority, bool enable); 527 528 /** Connects a source signal and enables the specified input 529 * 530 * @param[in] obj The ADC object 531 * @param[in] source Source signal obtained from another driver's cyhal_<PERIPH>_enable_output 532 * @param[in] input Which input signal to connect to 533 * @return The status of the connection 534 */ 535 cy_rslt_t cyhal_adc_connect_digital(cyhal_adc_t *obj, cyhal_source_t source, cyhal_adc_input_t input); 536 537 /** Enables the specified output signal 538 * 539 * @param[in] obj The ADC object 540 * @param[in] output Which output signal to enable 541 * @param[out] source Pointer to user-allocated source signal object 542 * which will be initialized by enable_output. \p source should be passed to 543 * (dis)connect_digital functions to (dis)connect the associated endpoints. 544 * @return The status of the output enable 545 */ 546 cy_rslt_t cyhal_adc_enable_output(cyhal_adc_t *obj, cyhal_adc_output_t output, cyhal_source_t *source); 547 548 /** Disconnect a source signal and disable ADC input 549 * 550 * @param[in] obj The ADC object 551 * @param[in] source Source signal from cyhal_<PERIPH>_enable_output to disable 552 * @param[in] input Which input signal to disconnect 553 * @return The status of the disconnect 554 */ 555 cy_rslt_t cyhal_adc_disconnect_digital(cyhal_adc_t *obj, cyhal_source_t source, cyhal_adc_input_t input); 556 557 /** Disables specified output signal from ADC. 558 * 559 * @param[in] obj The ADC object 560 * @param[in] output Which output signal to disable 561 * @return The status of the disablement 562 */ 563 cy_rslt_t cyhal_adc_disable_output(cyhal_adc_t *obj, cyhal_adc_output_t output); 564 565 #if defined(__cplusplus) 566 } 567 #endif 568 569 #ifdef CYHAL_ADC_IMPL_HEADER 570 #include CYHAL_ADC_IMPL_HEADER 571 #endif /* CYHAL_ADC_IMPL_HEADER */ 572 573 /** \} group_hal_adc */ 574
