/*
 * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

// DO NOT USE THESE APIS IN ANY APPLICATIONS

#pragma once
#include "esp_err.h"
#include "hal/adc_types.h"
#include "soc/soc_caps.h"


#ifdef __cplusplus
extern "C" {
#endif

/*------------------------------------------------------------------------------
* For those who use APB_SARADC periph
*----------------------------------------------------------------------------*/
/**
 * @brief Claim the usage of the APB_SARADC periph
 *
 * Reference count inside
 */
void adc_apb_periph_claim(void);

/**
 * @brief Free the usage of the APB_SARADC periph
 *
 * Reference count inside
 */
void adc_apb_periph_free(void);


/*------------------------------------------------------------------------------
* ADC Power
*----------------------------------------------------------------------------*/
/**
 * @brief Acquire the ADC Power
 */
void adc_power_acquire(void);

/**
 * @brief Release the ADC Power
 */
void adc_power_release(void);


/*---------------------------------------------------------------
            ADC IOs
---------------------------------------------------------------*/
/**
 * @brief Get ADC channel from the given GPIO number
 *
 * @param[in]  io_num     GPIO number
 * @param[out] unit_id    ADC unit
 * @param[out] channel    ADC channel
 *
 * @return
 *        - ESP_OK:              On success
 *        - ESP_ERR_INVALID_ARG: Invalid argument
 *        - ESP_ERR_NOT_FOUND:   The IO is not a valid ADC pad
 */
esp_err_t adc_io_to_channel(int io_num, adc_unit_t *unit_id, adc_channel_t *channel);

/**
 * @brief Get GPIO number from the given ADC channel
 *
 * @param[in]  unit_id    ADC unit
 * @param[in]  channel    ADC channel
 * @param[out] io_num     GPIO number
 *
 * @param
 *       - ESP_OK:              On success
 *       - ESP_ERR_INVALID_ARG: Invalid argument
 */
esp_err_t adc_channel_to_io(adc_unit_t unit_id, adc_channel_t channel, int *io_num);


#if SOC_ADC_CALIBRATION_V1_SUPPORTED
/*---------------------------------------------------------------
            ADC Hardware Calibration
---------------------------------------------------------------*/
/**
 * @brief Calculate the ADC HW calibration code. (Based on the pre-stored efuse or actual calibration)
 *
 * @param adc_n ADC unit to calibrate
 * @param atten Attenuation to use
 */
void adc_calc_hw_calibration_code(adc_unit_t adc_n, adc_atten_t atten);

/**
 * @brief Set the ADC HW calibration code.
 *
 * @param adc_n ADC unit to calibrate
 * @param atten Attenuation to use
 */
void adc_set_hw_calibration_code(adc_unit_t adc_n, adc_atten_t atten);
#endif //#if SOC_ADC_CALIBRATION_V1_SUPPORTED

/*---------------------------------------------------------------
            ADC Oneshot Read API ISR Version
---------------------------------------------------------------*/
typedef struct adc_oneshot_unit_ctx_t *adc_oneshot_unit_handle_t;
/**
 * @brief ISR version to get one ADC conversion raw result
 *
 * @note This API only provide atomic register settings, without hardware resources protection. When other drivers are using
 *       SAR-ADCs, calling this API may get wrong ADC result.
 * @note This API can be called in an ISR context.
 * @note Strongly suggest using this function when there's no concurrent hardware usage to the ADC. You can refer to ADC Oneshot
 *       Programming Guide to know ADC Hardware Limitations
 *
 * @param[in] handle    ADC handle
 * @param[in] chan      ADC channel
 * @param[out] out_raw  ADC conversion raw result
 *
 * @return
 *        - ESP_OK:                On success
 *        - ESP_ERR_INVALID_ARG:   Invalid arguments
 *        - ESP_ERR_INVALID_STATE: Invalid state, the ADC result is invalid
 */
esp_err_t adc_oneshot_read_isr(adc_oneshot_unit_handle_t handle, adc_channel_t chan, int *out_raw);


#ifdef __cplusplus
}
#endif