/**
 * @file        hal_adc.h
 * @copyright   Nehemis SARL reserves all rights even in the event of industrial
 *              property rights. We reserve all rights of disposal such as
 *              copying and passing on to third parties.
 *
 * @brief       STM HAL ADC wrapper class.
 */

#ifndef HAL_ADC_H
#define HAL_ADC_H

/******************************************************************************
 * Include Header Files
 ******************************************************************************/
#include "nms_types.h"
#include "map_hal.h"

/* CubeMX */
#include "adc.h"

/******************************************************************************
 * Typedef
 ******************************************************************************/
typedef enum
{
    HAL_ADC_SUCCESS = 0U,
    HAL_ADC_ERROR,
    HAL_ADC_TIMEOUT
} HalAdcStatus_ten;

/******************************************************************************
 * Function Declarations
 ******************************************************************************/
/**
 * @brief  Initializes the ADC hardware interface.
 *         This function sets up the necessary resources and configurations for the ADC.
 *
 * @return  Error code: 0 if successful, nonzero otherwise.
 */
void HalAdcCalibrate(MapHalAdcModule_en module_en);

/**
 * @brief  Starts the ADC conversion on the specified ADC module.
 *         This function initiates the conversion process for the given ADC module.
 *
 * @param  module_en	The ADC module to be used (based on the system configuration).
 *
 * @return  Error code: 0 if successful, nonzero otherwise.
 */
uint32 HalAdcStart(MapHalAdcModule_en module_en);

/**
 * @brief   Reads the ADC value from the specified ADC module.
 *
 * @param   module_en		The ADC module to read from.
 * 			adcValue_pu32	Pointer to store the ADC value.
 *
 * @return  Error code: 0 if successful, nonzero otherwise.
 */
uint32 HalAdcRead(MapHalAdcModule_en module_en, uint32 *adcValue_pu32);

/**
 * @brief  Stops the ADC conversion for the specified ADC module.
 *
 * @param  module_en	The ADC module to stop.
 *
 * @return uint32_t: Status of the ADC stop operation.
 */
uint32 HalAdcStop(MapHalAdcModule_en module_en);

/**
 * @brief   Reads the ADC value in DMA mode
 *
 * @param   module_en		The ADC module to read from.
 * 			pData_u32	    Pointer to store the ADC value.
 * 			length_u32		Length of data.
 *
 * @return  Error code: 0 if successful, nonzero otherwise.
 */
uint32 HalAdcStartDMA(MapHalAdcModule_en module_en, uint32 * pData_u32, uint32 length_u32);

/**
 * @brief  Deinitializes the specified ADC module.
 *         This function frees up the resources associated with the ADC module
 *         and prepares it for shutdown or reconfiguration.
 *
 * @param  adcModule_en		The ADC module to deinitialize.
 *
 * @return None
 */
void HalAdcDeinit(MapHalAdcModule_en adcModule_en);

/**
 * @brief  Configures a callback function for ADC conversion completion.
 *         This function registers a callback function that will be called
 *         once the ADC conversion is completed.
 *
 * @param  adcModule_en		The ADC module to configure the callback for.
 *         callback_pfn     Pointer to the callback function that will be called
 *                          after the ADC conversion is complete.
 *                          The callback should return a `uint32` value.
 *
 * @return  Error code: 0 if successful, nonzero otherwise.
 */
uint32 HalAdcConfigureCallback(MapHalAdcModule_en adcModule_en, uint32 (*callback_pfn)(void));

#endif /* HAL_ADC_H */