ext/hal/qmsi/drivers/include/qm_ss_adc.h

/*
 * Copyright (c) 2017, Intel Corporation
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. Neither the name of the Intel Corporation nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE INTEL CORPORATION OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef __QM_SS_ADC_H__
#define __QM_SS_ADC_H__

#include "qm_common.h"
#include "qm_soc_regs.h"
#include "qm_sensor_regs.h"

/**
* Analog to Digital Converter (ADC) for the Sensor Subsystem.
*
* @defgroup groupSSADC SS ADC
* @{
*/

/**
 * SS ADC sample size type.
 */
typedef uint16_t qm_ss_adc_sample_t;

/**
 * SS ADC calibration type.
 */
typedef uint8_t qm_ss_adc_calibration_t;

/**
 * SS ADC status.
 */
typedef enum {
	QM_SS_ADC_IDLE = 0x0,      /**< ADC idle. */
	QM_SS_ADC_COMPLETE = 0x1,  /**< ADC data available. */
	QM_SS_ADC_OVERFLOW = 0x2,  /**< ADC overflow error. */
	QM_SS_ADC_UNDERFLOW = 0x4, /**< ADC underflow error. */
	QM_SS_ADC_SEQERROR = 0x8   /**< ADC sequencer error. */
} qm_ss_adc_status_t;

/**
 * SS ADC resolution type.
 */
typedef enum {
	QM_SS_ADC_RES_6_BITS = 0x5,  /**< 6-bit mode. */
	QM_SS_ADC_RES_8_BITS = 0x7,  /**< 8-bit mode. */
	QM_SS_ADC_RES_10_BITS = 0x9, /**< 10-bit mode. */
	QM_SS_ADC_RES_12_BITS = 0xB  /**< 12-bit mode. */
} qm_ss_adc_resolution_t;

/**
 * SS ADC operating mode type.
 */
typedef enum {
	QM_SS_ADC_MODE_DEEP_PWR_DOWN, /**< Deep power down mode. */
	QM_SS_ADC_MODE_PWR_DOWN,      /**< Power down mode. */
	QM_SS_ADC_MODE_STDBY,	 /**< Standby mode. */
	QM_SS_ADC_MODE_NORM_CAL,      /**< Normal mode, with calibration. */
	QM_SS_ADC_MODE_NORM_NO_CAL    /**< Normal mode, no calibration. */
} qm_ss_adc_mode_t;

/**
 * SS ADC channels type.
 */
typedef enum {
	QM_SS_ADC_CH_0,  /**< ADC Channel 0. */
	QM_SS_ADC_CH_1,  /**< ADC Channel 1. */
	QM_SS_ADC_CH_2,  /**< ADC Channel 2. */
	QM_SS_ADC_CH_3,  /**< ADC Channel 3. */
	QM_SS_ADC_CH_4,  /**< ADC Channel 4. */
	QM_SS_ADC_CH_5,  /**< ADC Channel 5. */
	QM_SS_ADC_CH_6,  /**< ADC Channel 6. */
	QM_SS_ADC_CH_7,  /**< ADC Channel 7. */
	QM_SS_ADC_CH_8,  /**< ADC Channel 8. */
	QM_SS_ADC_CH_9,  /**< ADC Channel 9. */
	QM_SS_ADC_CH_10, /**< ADC Channel 10. */
	QM_SS_ADC_CH_11, /**< ADC Channel 11. */
	QM_SS_ADC_CH_12, /**< ADC Channel 12. */
	QM_SS_ADC_CH_13, /**< ADC Channel 13. */
	QM_SS_ADC_CH_14, /**< ADC Channel 14. */
	QM_SS_ADC_CH_15, /**< ADC Channel 15. */
	QM_SS_ADC_CH_16, /**< ADC Channel 16. */
	QM_SS_ADC_CH_17, /**< ADC Channel 17. */
	QM_SS_ADC_CH_18  /**< ADC Channel 18. */
} qm_ss_adc_channel_t;

/**
 * SS ADC interrupt callback source.
 */
typedef enum {
	QM_SS_ADC_TRANSFER,     /**< Transfer complete or error callback. */
	QM_SS_ADC_MODE_CHANGED, /**< Mode change complete callback. */
	QM_SS_ADC_CAL_COMPLETE, /**< Calibration complete callback. */
} qm_ss_adc_cb_source_t;

/**
 * SS ADC configuration type.
 */
typedef struct {
	/**
	 * Sample interval in ADC clock cycles, defines the period to wait
	 * between the start of each sample and can be in the range
	 * [(resolution+2) - 255].
	 */
	uint8_t window;
	qm_ss_adc_resolution_t resolution; /**< 12, 10, 8, 6-bit resolution. */
} qm_ss_adc_config_t;

/**
 * SS ADC transfer type.
 */
typedef struct {
	qm_ss_adc_channel_t *ch; /**< Channel sequence array (1-32 channels). */
	uint8_t ch_len;		 /**< Number of channels in the above array. */
	qm_ss_adc_sample_t *samples; /**< Array to store samples. */
	uint32_t samples_len;	/**< Length of sample array. */

	/**
	 * Transfer callback.
	 *
	 * Called when a conversion is performed or an error is detected.
	 *
	 * @param[in] data The callback user data.
	 * @param[in] error 0 on success.
	 *                  Negative @ref errno for possible error codes.
	 * @param[in] status ADC status.
	 * @param[in] source Interrupt callback source.
	 */
	void (*callback)(void *data, int error, qm_ss_adc_status_t status,
			 qm_ss_adc_cb_source_t source);
	void *callback_data; /**< Callback user data. */
} qm_ss_adc_xfer_t;

/**
 * Switch operating mode of SS ADC.
 *
 * This call is blocking.
 *
 * @param[in] adc Which ADC to enable.
 * @param[in] mode ADC operating mode.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_set_mode(const qm_ss_adc_t adc, const qm_ss_adc_mode_t mode);

/**
 * Switch operating mode of SS ADC.
 *
 * This call is non-blocking and will call the user callback on completion. An
 * interrupt will not be generated if the user requests the same mode the ADC
 * is currently in (default mode on boot is deep power down).
 *
 * @param[in] adc Which ADC to enable.
 * @param[in] mode ADC operating mode.
 * @param[in] callback Callback called on completion.
 * @param[in] callback_data The callback user data.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_irq_set_mode(const qm_ss_adc_t adc, const qm_ss_adc_mode_t mode,
			   void (*callback)(void *data, int error,
					    qm_ss_adc_status_t status,
					    qm_ss_adc_cb_source_t source),
			   void *callback_data);

/**
 * Calibrate the SS ADC.
 *
 * It is necessary to calibrate if it is intended to use Normal Mode With
 * Calibration. The calibration must be performed if the ADC is used for the
 * first time or has been in deep power down mode. This call is blocking.
 *
 * @param[in] adc Which ADC to calibrate.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_calibrate(const qm_ss_adc_t adc);

/**
 * Calibrate the SS ADC.
 *
 * It is necessary to calibrate if it is intended to use Normal Mode With
 * Calibration. The calibration must be performed if the ADC is used for the
 * first time or has been in deep power down mode. This call is non-blocking
 * and will call the user callback on completion.
 *
 * @param[in] adc Which ADC to calibrate.
 * @param[in] callback Callback called on completion.
 * @param[in] callback_data The callback user data.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_irq_calibrate(const qm_ss_adc_t adc,
			    void (*callback)(void *data, int error,
					     qm_ss_adc_status_t status,
					     qm_ss_adc_cb_source_t source),
			    void *callback_data);

/**
 * Set SS ADC calibration data.
 *
 * @param[in] adc Which ADC to set calibration for.
 * @param[in] cal Calibration data.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_set_calibration(const qm_ss_adc_t adc,
			      const qm_ss_adc_calibration_t cal);

/**
 * Get the current calibration data for an SS ADC.
 *
 * @param[in] adc Which ADC to get calibration for.
 * @param[out] cal Calibration data. This must not be NULL.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_get_calibration(const qm_ss_adc_t adc,
			      qm_ss_adc_calibration_t *const cal);

/**
 * Set SS ADC configuration.
 *
 * This sets the sample window and resolution.
 *
 * @param[in] adc Which ADC to configure.
 * @param[in] cfg ADC configuration. This must not be NULL.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_set_config(const qm_ss_adc_t adc,
			 const qm_ss_adc_config_t *const cfg);

/**
 * Synchronously read values from the ADC.
 *
 * This blocking call can read 1-32 ADC values into the array provided.
 *
 * @param[in] adc Which ADC to read.
 * @param[in,out] xfer Channel and sample info. This must not be NULL.
 * @param[out] status Get status of the adc device.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_convert(const qm_ss_adc_t adc, qm_ss_adc_xfer_t *const xfer,
		      qm_ss_adc_status_t *const status);

/**
 * Asynchronously read values from the SS ADC.
 *
 * This is a non-blocking call and will call the user provided callback after
 * the requested number of samples have been converted.
 *
 * @param[in] adc Which ADC to read.
 * @param[in,out] xfer Channel sample and callback info. This must not be NULL.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_irq_convert(const qm_ss_adc_t adc, qm_ss_adc_xfer_t *const xfer);

/**
 * Save SS ADC context.
 *
 * Save the configuration of the specified ADC peripheral before entering sleep.
 *
 * Note: Calibration data is not saved with this function. The value of the
 * ADC_ENA bit in the ADC Control register is also not saved with this function.
 *
 * @param[in] adc SS ADC port index.
 * @param[out] ctx SS ADC context structure. This must not be NULL.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_save_context(const qm_ss_adc_t adc,
			   qm_ss_adc_context_t *const ctx);

/**
 * Restore SS ADC context.
 *
 * Restore the configuration of the specified ADC peripheral after exiting
 * sleep.
 *
 * Note: Previous calibration data is not restored with this function, the user
 * may need to recalibrate the ADC. The user will need to set the ADC_ENA bit
 * in the ADC Control register as it is initialized to 0.
 *
 * @param[in] adc SS ADC port index.
 * @param[in] ctx SS ADC context structure. This must not be NULL.
 *
 * @return Standard errno return type for QMSI.
 * @retval 0 on success.
 * @retval Negative @ref errno for possible error codes.
 */
int qm_ss_adc_restore_context(const qm_ss_adc_t adc,
			      const qm_ss_adc_context_t *const ctx);

/**
 * @}
 */
#endif /* __QM_ADC_H__ */