esp-idf/components/driver/sigma_delta/include/driver/sdm.h

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

#pragma once

#include <stdint.h>
#include "hal/sdm_types.h"
#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Type of Sigma Delta channel handle
 */
typedef struct sdm_channel_t *sdm_channel_handle_t;

/**
 * @brief Sigma Delta channel configuration
 */
typedef struct {
    int gpio_num;               /*!< GPIO number */
    sdm_clock_source_t clk_src; /*!< Clock source */
    uint32_t sample_rate_hz;    /*!< Over sample rate in Hz, it determines the frequency of the carrier pulses */
    struct {
        uint32_t invert_out: 1;   /*!< Whether to invert the output signal */
        uint32_t io_loop_back: 1; /*!< For debug/test, the signal output from the GPIO will be fed to the input path as well */
    } flags;                      /*!< Extra flags */
} sdm_config_t;

/**
 * @brief Create a new Sigma Delta channel
 *
 * @param[in] config SDM configuration
 * @param[out] ret_chan Returned SDM channel handle
 * @return
 *      - ESP_OK: Create SDM channel successfully
 *      - ESP_ERR_INVALID_ARG: Create SDM channel failed because of invalid argument
 *      - ESP_ERR_NO_MEM: Create SDM channel failed because out of memory
 *      - ESP_ERR_NOT_FOUND: Create SDM channel failed because all channels are used up and no more free one
 *      - ESP_FAIL: Create SDM channel failed because of other error
 */
esp_err_t sdm_new_channel(const sdm_config_t *config, sdm_channel_handle_t *ret_chan);

/**
 * @brief Delete the Sigma Delta channel
 *
 * @param[in] chan SDM channel created by `sdm_new_channel`
 * @return
 *      - ESP_OK: Delete the SDM channel successfully
 *      - ESP_ERR_INVALID_ARG: Delete the SDM channel failed because of invalid argument
 *      - ESP_ERR_INVALID_STATE: Delete the SDM channel failed because the channel is not in init state
 *      - ESP_FAIL: Delete the SDM channel failed because of other error
 */
esp_err_t sdm_del_channel(sdm_channel_handle_t chan);

/**
 * @brief Enable the Sigma Delta channel
 *
 * @note This function will transit the channel state from init to enable.
 * @note This function will acquire a PM lock, if a specific source clock (e.g. APB) is selected in the `sdm_config_t`, while `CONFIG_PM_ENABLE` is enabled.
 *
 * @param[in] chan SDM channel created by `sdm_new_channel`
 * @return
 *      - ESP_OK: Enable SDM channel successfully
 *      - ESP_ERR_INVALID_ARG: Enable SDM channel failed because of invalid argument
 *      - ESP_ERR_INVALID_STATE: Enable SDM channel failed because the channel is already enabled
 *      - ESP_FAIL: Enable SDM channel failed because of other error
 */
esp_err_t sdm_channel_enable(sdm_channel_handle_t chan);

/**
 * @brief Disable the Sigma Delta channel
 *
 * @note This function will do the opposite work to the `sdm_channel_enable()`
 *
 * @param[in] chan SDM channel created by `sdm_new_channel`
 * @return
 *      - ESP_OK: Disable SDM channel successfully
 *      - ESP_ERR_INVALID_ARG: Disable SDM channel failed because of invalid argument
 *      - ESP_ERR_INVALID_STATE: Disable SDM channel failed because the channel is not enabled yet
 *      - ESP_FAIL: Disable SDM channel failed because of other error
 */
esp_err_t sdm_channel_disable(sdm_channel_handle_t chan);

/**
 * @brief Set the pulse density of the PDM output signal.
 *
 * @note The raw output signal requires a low-pass filter to restore it into analog voltage,
*        the restored analog output voltage could be Vout = VDD_IO / 256 * density + VDD_IO / 2
 * @note This function is allowed to run within ISR context
 * @note This function will be placed into IRAM if `CONFIG_SDM_CTRL_FUNC_IN_IRAM` is on,
 *       so that it's allowed to be executed when Cache is disabled
 *
 * @param[in] chan SDM channel created by `sdm_new_channel`
 * @param[in] density Quantized pulse density of the PDM output signal, ranges from -128 to 127.
 *                    But the range of [-90, 90] can provide a better randomness.
 * @return
 *      - ESP_OK: Set pulse density successfully
 *      - ESP_ERR_INVALID_ARG: Set pulse density failed because of invalid argument
 *      - ESP_FAIL: Set pulse density failed because of other error
 */
esp_err_t sdm_channel_set_pulse_density(sdm_channel_handle_t chan, int8_t density);

/**
 * @brief The alias function of `sdm_channel_set_pulse_density`, it decides the pulse density of the output signal
 *
 * @note  `sdm_channel_set_pulse_density` has a more appropriate name compare this
 *        alias function, suggest to turn to `sdm_channel_set_pulse_density` instead
 *
 * @param[in] chan SDM channel created by `sdm_new_channel`
 * @param[in] duty Actually it's the quantized pulse density of the PDM output signal
 *
 * @return
 *      - ESP_OK: Set duty cycle successfully
 *      - ESP_ERR_INVALID_ARG: Set duty cycle failed because of invalid argument
 *      - ESP_FAIL: Set duty cycle failed because of other error
 */
esp_err_t sdm_channel_set_duty(sdm_channel_handle_t chan, int8_t duty);

#ifdef __cplusplus
}
#endif