Merge branch 'refactor/i2s_driver_rewrite' into 'master'
🔨 i2s: i2s driver-NG Closes IDF-3714 and IDF-4592 See merge request espressif/esp-idf!15175
This commit is contained in:
Kevin (Lao Kaiyao)
@@ -1,495 +0,0 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "esp_types.h"
|
||||
#include "esp_err.h"
|
||||
#include "freertos/FreeRTOS.h"
|
||||
#include "freertos/semphr.h"
|
||||
#include "soc/soc_caps.h"
|
||||
#include "hal/i2s_types.h"
|
||||
#include "esp_intr_alloc.h"
|
||||
|
||||
#if SOC_I2S_SUPPORTS_ADC
|
||||
#include "driver/adc.h"
|
||||
#endif
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define I2S_PIN_NO_CHANGE (-1) /*!< Use in i2s_pin_config_t for pins which should not be changed */
|
||||
|
||||
/**
|
||||
* @brief I2S port number, the max port number is (I2S_NUM_MAX -1).
|
||||
*/
|
||||
typedef enum {
|
||||
I2S_NUM_0 = 0, /*!< I2S port 0 */
|
||||
#if SOC_I2S_NUM > 1
|
||||
I2S_NUM_1 = 1, /*!< I2S port 1 */
|
||||
#endif
|
||||
I2S_NUM_MAX, /*!< I2S port max */
|
||||
} i2s_port_t;
|
||||
|
||||
#if SOC_I2S_SUPPORTS_PCM
|
||||
/**
|
||||
* @brief I2S PCM configuration
|
||||
*
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_pcm_compress_t pcm_type; /*!< I2S PCM a/u-law decompress or compress type */
|
||||
} i2s_pcm_cfg_t;
|
||||
#endif
|
||||
|
||||
#if SOC_I2S_SUPPORTS_PDM_TX
|
||||
/**
|
||||
* @brief Default I2S PDM Up-Sampling Rate configuration
|
||||
*/
|
||||
#define I2S_PDM_DEFAULT_UPSAMPLE_CONFIG(rate) { \
|
||||
.sample_rate = rate, \
|
||||
.fp = 960, \
|
||||
.fs = (rate) / 100, \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief I2S PDM up-sample rate configuration
|
||||
* @note TX PDM can only be set to the following two upsampling rate configurations:
|
||||
* 1: fp = 960, fs = sample_rate / 100, in this case, Fpdm = 128*48000
|
||||
* 2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm = 128*sample_rate
|
||||
* If the pdm receiver do not care the pdm serial clock, it's recommended set Fpdm = 128*48000.
|
||||
* Otherwise, the second configuration should be applied.
|
||||
*/
|
||||
typedef struct {
|
||||
int sample_rate; /*!< I2S PDM sample rate */
|
||||
int fp; /*!< I2S PDM TX upsampling paramater. Normally it should be set to 960 */
|
||||
int fs; /*!< I2S PDM TX upsampling paramater. When it is set to 480, the pdm clock frequency Fpdm = 128 * sample_rate, when it is set to sample_rate / 100， Fpdm will be fixed to 128*48000 */
|
||||
} i2s_pdm_tx_upsample_cfg_t;
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief I2S pin number for i2s_set_pin
|
||||
*
|
||||
*/
|
||||
typedef struct {
|
||||
int mck_io_num; /*!< MCK in out pin. Note that ESP32 supports setting MCK on GPIO0/GPIO1/GPIO3 only*/
|
||||
int bck_io_num; /*!< BCK in out pin*/
|
||||
int ws_io_num; /*!< WS in out pin*/
|
||||
int data_out_num; /*!< DATA out pin*/
|
||||
int data_in_num; /*!< DATA in pin*/
|
||||
} i2s_pin_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S driver configuration parameters
|
||||
*
|
||||
*/
|
||||
typedef struct {
|
||||
|
||||
i2s_mode_t mode; /*!< I2S work mode */
|
||||
uint32_t sample_rate; /*!< I2S sample rate */
|
||||
i2s_bits_per_sample_t bits_per_sample; /*!< I2S sample bits in one channel */
|
||||
i2s_channel_fmt_t channel_format; /*!< I2S channel format.*/
|
||||
i2s_comm_format_t communication_format; /*!< I2S communication format */
|
||||
int intr_alloc_flags; /*!< Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info */
|
||||
union {
|
||||
int dma_desc_num; /*!< The total number of descriptors used by I2S DMA to receive/transmit data */
|
||||
int dma_buf_count __attribute__((deprecated)); /*!< This is an alias to 'dma_desc_num' for backward compatibility */
|
||||
};
|
||||
union {
|
||||
int dma_frame_num; /*!< Number of frames for one-time sampling. The frame here means the total data from all the channels in a WS cycle */
|
||||
int dma_buf_len __attribute__((deprecated)); /*!< This is an alias to 'dma_frame_num' for backward compatibility */
|
||||
};
|
||||
|
||||
bool use_apll; /*!< I2S using APLL as main I2S clock, enable it to get accurate clock */
|
||||
bool tx_desc_auto_clear; /*!< I2S auto clear tx descriptor if there is underflow condition (helps in avoiding noise in case of data unavailability) */
|
||||
int fixed_mclk; /*!< I2S using fixed MCLK output. If use_apll = true and fixed_mclk > 0, then the clock output for i2s is fixed and equal to the fixed_mclk value. If fixed_mclk set, mclk_multiple won't take effect */
|
||||
i2s_mclk_multiple_t mclk_multiple; /*!< The multiple of I2S master clock(MCLK) to sample rate */
|
||||
i2s_bits_per_chan_t bits_per_chan; /*!< I2S total bits in one channel， only take effect when larger than 'bits_per_sample', default '0' means equal to 'bits_per_sample' */
|
||||
|
||||
#if SOC_I2S_SUPPORTS_TDM
|
||||
i2s_channel_t chan_mask; /*!< I2S active channel bit mask, set value in `i2s_channel_t` to enable specific channel, the bit map of active channel can not exceed (0x1<<total_chan). */
|
||||
uint32_t total_chan; /*!< I2S Total number of channels. If it is smaller than the biggest active channel number, it will be set to this number automatically. */
|
||||
bool left_align; /*!< Set to enable left alignment */
|
||||
bool big_edin; /*!< Set to enable big edin */
|
||||
bool bit_order_msb; /*!< Set to enable msb order */
|
||||
bool skip_msk; /*!< Set to enable skip mask. If it is enabled, only the data of the enabled channels will be sent, otherwise all data stored in DMA TX buffer will be sent */
|
||||
#endif // SOC_I2S_SUPPORTS_TDM
|
||||
|
||||
} i2s_driver_config_t;
|
||||
|
||||
typedef i2s_driver_config_t i2s_config_t; // for backward compatible
|
||||
typedef intr_handle_t i2s_isr_handle_t; // for backward compatible
|
||||
|
||||
/**
|
||||
* @brief I2S event queue types
|
||||
*
|
||||
*/
|
||||
typedef enum {
|
||||
I2S_EVENT_DMA_ERROR,
|
||||
I2S_EVENT_TX_DONE, /*!< I2S DMA finish sent 1 buffer*/
|
||||
I2S_EVENT_RX_DONE, /*!< I2S DMA finish received 1 buffer*/
|
||||
I2S_EVENT_TX_Q_OVF, /*!< I2S DMA sent queue overflow*/
|
||||
I2S_EVENT_RX_Q_OVF, /*!< I2S DMA receive queue overflow*/
|
||||
I2S_EVENT_MAX, /*!< I2S event max index*/
|
||||
} i2s_event_type_t;
|
||||
|
||||
/**
|
||||
* @brief Event structure used in I2S event queue
|
||||
*
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_event_type_t type; /*!< I2S event type */
|
||||
size_t size; /*!< I2S data size for I2S_DATA event*/
|
||||
} i2s_event_t;
|
||||
|
||||
/**
|
||||
* @brief Set I2S pin number
|
||||
*
|
||||
* @note
|
||||
* The I2S peripheral output signals can be connected to multiple GPIO pads.
|
||||
* However, the I2S peripheral input signal can only be connected to one GPIO pad.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param pin I2S Pin structure, or NULL to set 2-channel 8-bit internal DAC pin configuration (GPIO25 & GPIO26)
|
||||
*
|
||||
* Inside the pin configuration structure, set I2S_PIN_NO_CHANGE for any pin where
|
||||
* the current configuration should not be changed.
|
||||
*
|
||||
* @note if *pin is set as NULL, this function will initialize both of the built-in DAC channels by default.
|
||||
* if you don't want this to happen and you want to initialize only one of the DAC channels, you can call i2s_set_dac_mode instead.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_FAIL IO error
|
||||
*/
|
||||
esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin);
|
||||
|
||||
#if SOC_I2S_SUPPORTS_PDM_RX
|
||||
/**
|
||||
* @brief Set PDM mode down-sample rate
|
||||
* In PDM RX mode, there would be 2 rounds of downsample process in hardware.
|
||||
* In the first downsample process, the sampling number can be 16 or 8.
|
||||
* In the second downsample process, the sampling number is fixed as 8.
|
||||
* So the clock frequency in PDM RX mode would be (fpcm * 64) or (fpcm * 128) accordingly.
|
||||
* @param i2s_num I2S port number
|
||||
* @param downsample i2s RX down sample rate for PDM mode.
|
||||
*
|
||||
* @note After calling this function, it would call i2s_set_clk inside to update the clock frequency.
|
||||
* Please call this function after I2S driver has been initialized.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_NO_MEM Out of memory
|
||||
*/
|
||||
esp_err_t i2s_set_pdm_rx_down_sample(i2s_port_t i2s_num, i2s_pdm_dsr_t downsample);
|
||||
#endif
|
||||
|
||||
#if SOC_I2S_SUPPORTS_PDM_TX
|
||||
/**
|
||||
* @brief Set TX PDM mode up-sample rate
|
||||
* @note If you have set PDM mode while calling 'i2s_driver_install',
|
||||
* default PDM TX upsample parameters have already been set,
|
||||
* no need to call this function again if you don't have to change the default configuration
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
* @param upsample_cfg Set I2S PDM up-sample rate configuration
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_NO_MEM Out of memory
|
||||
*/
|
||||
esp_err_t i2s_set_pdm_tx_up_sample(i2s_port_t i2s_num, const i2s_pdm_tx_upsample_cfg_t *upsample_cfg);
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief Install and start I2S driver.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param i2s_config I2S configurations - see i2s_config_t struct
|
||||
*
|
||||
* @param queue_size I2S event queue size/depth.
|
||||
*
|
||||
* @param i2s_queue I2S event queue handle, if set NULL, driver will not use an event queue.
|
||||
*
|
||||
* This function must be called before any I2S driver read/write operations.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_NO_MEM Out of memory
|
||||
* - ESP_ERR_INVALID_STATE Current I2S port is in use
|
||||
*/
|
||||
esp_err_t i2s_driver_install(i2s_port_t i2s_num, const i2s_config_t *i2s_config, int queue_size, void *i2s_queue);
|
||||
|
||||
/**
|
||||
* @brief Uninstall I2S driver.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_INVALID_STATE I2S port has been uninstalled by others (e.g. LCD i80)
|
||||
*/
|
||||
esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num);
|
||||
|
||||
/**
|
||||
* @brief Write data to I2S DMA transmit buffer.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param src Source address to write from
|
||||
*
|
||||
* @param size Size of data in bytes
|
||||
*
|
||||
* @param[out] bytes_written Number of bytes written, if timeout, the result will be less than the size passed in.
|
||||
*
|
||||
* @param ticks_to_wait TX buffer wait timeout in RTOS ticks. If this
|
||||
* many ticks pass without space becoming available in the DMA
|
||||
* transmit buffer, then the function will return (note that if the
|
||||
* data is written to the DMA buffer in pieces, the overall operation
|
||||
* may still take longer than this timeout.) Pass portMAX_DELAY for no
|
||||
* timeout.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_write(i2s_port_t i2s_num, const void *src, size_t size, size_t *bytes_written, TickType_t ticks_to_wait);
|
||||
|
||||
/**
|
||||
* @brief Write data to I2S DMA transmit buffer while expanding the number of bits per sample. For example, expanding 16-bit PCM to 32-bit PCM.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param src Source address to write from
|
||||
*
|
||||
* @param size Size of data in bytes
|
||||
*
|
||||
* @param src_bits Source audio bit
|
||||
*
|
||||
* @param aim_bits Bit wanted, no more than 32, and must be greater than src_bits
|
||||
*
|
||||
* @param[out] bytes_written Number of bytes written, if timeout, the result will be less than the size passed in.
|
||||
*
|
||||
* @param ticks_to_wait TX buffer wait timeout in RTOS ticks. If this
|
||||
* many ticks pass without space becoming available in the DMA
|
||||
* transmit buffer, then the function will return (note that if the
|
||||
* data is written to the DMA buffer in pieces, the overall operation
|
||||
* may still take longer than this timeout.) Pass portMAX_DELAY for no
|
||||
* timeout.
|
||||
*
|
||||
* Format of the data in source buffer is determined by the I2S
|
||||
* configuration (see i2s_config_t).
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_write_expand(i2s_port_t i2s_num, const void *src, size_t size, size_t src_bits, size_t aim_bits, size_t *bytes_written, TickType_t ticks_to_wait);
|
||||
|
||||
/**
|
||||
* @brief Read data from I2S DMA receive buffer
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param dest Destination address to read into
|
||||
*
|
||||
* @param size Size of data in bytes
|
||||
*
|
||||
* @param[out] bytes_read Number of bytes read, if timeout, bytes read will be less than the size passed in.
|
||||
*
|
||||
* @param ticks_to_wait RX buffer wait timeout in RTOS ticks. If this many ticks pass without bytes becoming available in the DMA receive buffer, then the function will return (note that if data is read from the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.
|
||||
*
|
||||
* @note If the built-in ADC mode is enabled, we should call i2s_adc_enable and i2s_adc_disable around the whole reading process,
|
||||
* to prevent the data getting corrupted.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_read(i2s_port_t i2s_num, void *dest, size_t size, size_t *bytes_read, TickType_t ticks_to_wait);
|
||||
|
||||
/**
|
||||
* @brief Set sample rate used for I2S RX and TX.
|
||||
*
|
||||
* The bit clock rate is determined by the sample rate and i2s_config_t configuration parameters (number of channels, bits_per_sample).
|
||||
*
|
||||
* `bit_clock = rate * (number of channels) * bits_per_sample`
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param rate I2S sample rate (ex: 8000, 44100...)
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_NO_MEM Out of memory
|
||||
*/
|
||||
esp_err_t i2s_set_sample_rates(i2s_port_t i2s_num, uint32_t rate);
|
||||
|
||||
/**
|
||||
* @brief Stop I2S driver
|
||||
*
|
||||
* There is no need to call i2s_stop() before calling i2s_driver_uninstall().
|
||||
*
|
||||
* Disables I2S TX/RX, until i2s_start() is called.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_stop(i2s_port_t i2s_num);
|
||||
|
||||
/**
|
||||
* @brief Start I2S driver
|
||||
*
|
||||
* It is not necessary to call this function after i2s_driver_install() (it is started automatically), however it is necessary to call it after i2s_stop().
|
||||
*
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_start(i2s_port_t i2s_num);
|
||||
|
||||
/**
|
||||
* @brief Zero the contents of the TX DMA buffer.
|
||||
*
|
||||
* Pushes zero-byte samples into the TX DMA buffer, until it is full.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num);
|
||||
|
||||
#if SOC_I2S_SUPPORTS_PCM
|
||||
/**
|
||||
* @brief Configure I2S a/u-law decompress or compress
|
||||
*
|
||||
* @note This function should be called after i2s driver installed
|
||||
* Only take effecttive when the i2s 'communication_format' is set to 'I2S_COMM_FORMAT_STAND_PCM_SHORT' or 'I2S_COMM_FORMAT_STAND_PCM_LONG'
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param pcm_cfg including mode selection and a/u-law decompress or compress configuration paramater
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_pcm_config(i2s_port_t i2s_num, const i2s_pcm_cfg_t *pcm_cfg);
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief Set clock & bit width used for I2S RX and TX.
|
||||
*
|
||||
* Similar to i2s_set_sample_rates(), but also sets bit width.
|
||||
*
|
||||
* 1. stop i2s;
|
||||
* 2. calculate mclk, bck, bck_factor
|
||||
* 3. malloc dma buffer;
|
||||
* 4. start i2s
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @param rate I2S sample rate (ex: 8000, 44100...)
|
||||
*
|
||||
* @param bits_cfg I2S bits configuration
|
||||
* the low 16 bits is for data bits per sample in one channel (see 'i2s_bits_per_sample_t')
|
||||
* the high 16 bits is for total bits in one channel (see 'i2s_bits_per_chan_t')
|
||||
* high 16bits =0 means same as the bits per sample.
|
||||
*
|
||||
* @param ch I2S channel, (I2S_CHANNEL_MONO, I2S_CHANNEL_STEREO or specific channel in TDM mode)
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_NO_MEM Out of memory
|
||||
*/
|
||||
esp_err_t i2s_set_clk(i2s_port_t i2s_num, uint32_t rate, uint32_t bits_cfg, i2s_channel_t ch);
|
||||
|
||||
/**
|
||||
* @brief get clock set on particular port number.
|
||||
*
|
||||
* @param i2s_num I2S port number
|
||||
*
|
||||
* @return
|
||||
* - actual clock set by i2s driver
|
||||
*/
|
||||
float i2s_get_clk(i2s_port_t i2s_num);
|
||||
|
||||
#if SOC_I2S_SUPPORTS_ADC
|
||||
/**
|
||||
* @brief Set built-in ADC mode for I2S DMA, this function will initialize ADC pad,
|
||||
* and set ADC parameters.
|
||||
* @note In this mode, the ADC maximum sampling rate is 150KHz. Set the sampling rate through ``i2s_config_t``.
|
||||
* @param adc_unit SAR ADC unit index
|
||||
* @param adc_channel ADC channel index
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_set_adc_mode(adc_unit_t adc_unit, adc1_channel_t adc_channel);
|
||||
|
||||
/**
|
||||
* @brief Start to use I2S built-in ADC mode
|
||||
* @note This function would acquire the lock of ADC to prevent the data getting corrupted
|
||||
* during the I2S peripheral is being used to do fully continuous ADC sampling.
|
||||
*
|
||||
* @param i2s_num i2s port index
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_INVALID_STATE Driver state error
|
||||
*/
|
||||
esp_err_t i2s_adc_enable(i2s_port_t i2s_num);
|
||||
|
||||
/**
|
||||
* @brief Stop to use I2S built-in ADC mode
|
||||
* @param i2s_num i2s port index
|
||||
* @note This function would release the lock of ADC so that other tasks can use ADC.
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_ERR_INVALID_STATE Driver state error
|
||||
*/
|
||||
esp_err_t i2s_adc_disable(i2s_port_t i2s_num);
|
||||
#endif // SOC_I2S_SUPPORTS_ADC
|
||||
|
||||
#if SOC_I2S_SUPPORTS_DAC
|
||||
/**
|
||||
* @brief Set I2S dac mode, I2S built-in DAC is disabled by default
|
||||
*
|
||||
* @param dac_mode DAC mode configurations - see i2s_dac_mode_t
|
||||
*
|
||||
* @note Built-in DAC functions are only supported on I2S0 for current ESP32 chip.
|
||||
* If either of the built-in DAC channel are enabled, the other one can not
|
||||
* be used as RTC DAC function at the same time.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2s_set_dac_mode(i2s_dac_mode_t dac_mode);
|
||||
#endif //SOC_I2S_SUPPORTS_DAC
|
||||
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,212 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "driver/i2s_types.h"
|
||||
#include "hal/i2s_types.h"
|
||||
|
||||
#include "esp_types.h"
|
||||
#include "esp_err.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief get default I2S property
|
||||
*/
|
||||
#define I2S_CHANNEL_DEFAULT_CONFIG(i2s_num, i2s_role) { \
|
||||
.id = i2s_num, \
|
||||
.role = i2s_role, \
|
||||
.dma_desc_num = 3, \
|
||||
.dma_frame_num = 500, \
|
||||
.auto_clear = false, \
|
||||
}
|
||||
|
||||
#define I2S_GPIO_UNUSED GPIO_NUM_NC /*!< Used in i2s_gpio_config_t for signals which are not used */
|
||||
|
||||
/**
|
||||
* @brief Group of I2S callbacks
|
||||
* @note The callbacks are all running under ISR environment
|
||||
* @note When CONFIG_I2S_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM.
|
||||
* The variables used in the function should be in the SRAM as well.
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_isr_callback_t on_recv; /**< Callback of data received event, only for rx channel
|
||||
* The event data includes DMA buffer address and size that just finished receiving data
|
||||
*/
|
||||
i2s_isr_callback_t on_recv_q_ovf; /**< Callback of receiving queue overflowed event, only for rx channel
|
||||
* The event data includes buffer size that has been overwritten
|
||||
*/
|
||||
i2s_isr_callback_t on_sent; /**< Callback of data sent event, only for tx channel
|
||||
* The event data includes DMA buffer address and size that just finished sending data
|
||||
*/
|
||||
i2s_isr_callback_t on_send_q_ovf; /**< Callback of sending queue overflowed evnet, only for tx channel
|
||||
* The event data includes buffer size that has been overwritten
|
||||
*/
|
||||
} i2s_event_callbacks_t;
|
||||
|
||||
/**
|
||||
* @brief I2S controller channel configuration
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_port_t id; /*!< I2S port id */
|
||||
i2s_role_t role; /*!< I2S role, I2S_ROLE_MASTER or I2S_ROLE_SLAVE */
|
||||
|
||||
/* DMA configurations */
|
||||
uint32_t dma_desc_num; /*!< I2S DMA buffer number, it is also the number of DMA descriptor */
|
||||
uint32_t dma_frame_num; /*!< I2S frame number in one DMA buffer. One frame means one-time sample data in all slots */
|
||||
bool auto_clear; /*!< Set to auto clear DMA TX buffer, i2s will always send zero automatically if no data to send */
|
||||
|
||||
} i2s_chan_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S channel information
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_port_t id; /*!< I2S port id */
|
||||
i2s_role_t role; /*!< I2S role, I2S_ROLE_MASTER or I2S_ROLE_SLAVE */
|
||||
i2s_dir_t dir; /*!< I2S channel direction */
|
||||
i2s_comm_mode_t mode; /*!< I2S channel communication mode */
|
||||
i2s_chan_handle_t pair_chan; /*!< I2S pair channel handle in duplex mode, always NULL in simplex mode */
|
||||
} i2s_chan_info_t;
|
||||
|
||||
/**
|
||||
* @brief Allocate new I2S channel(s)
|
||||
* @note The new created I2S channel handle will be REGISTERED state after it is allocated successfully.
|
||||
* @note When the port id in channel configuration is I2S_NUM_AUTO, driver will allocate I2S port automatically
|
||||
* on one of the i2s controller, otherwise driver will try to allocate the new channel on the selected port.
|
||||
* @note If both tx_handle and rx_handle are not NULL, it means this I2S controller will work at full-duplex mode,
|
||||
* the rx and tx channels will be allocated on a same I2S port in this case.
|
||||
* Note that some configurations of tx/rx channel are shared on ESP32 and ESP32S2,
|
||||
* so please make sure they are working at same condition and under same status(start/stop).
|
||||
* Currently, full-duplex mode can't guarantee tx/rx channels write/read synchronously,
|
||||
* they can only share the clock signals for now.
|
||||
* @note If tx_handle OR rx_handle is NULL, it means this I2S controller will work at simplex mode.
|
||||
* For ESP32 and ESP32S2, the whole I2S controller (i.e. both rx and tx channel) will be occupied,
|
||||
* even if only one of rx or tx channel is registered.
|
||||
* For the other targets, another channel on this controller will still available.
|
||||
*
|
||||
* @param[in] chan_cfg I2S controller channel configurations
|
||||
* @param[out] ret_tx_handle I2S channel handler used for managing the sending channel(optional)
|
||||
* @param[out] ret_rx_handle I2S channel handler used for managing the receiving channel(optional)
|
||||
* @return
|
||||
* - ESP_OK Allocate new channel(s) success
|
||||
* - ESP_ERR_NOT_SUPPORTED The communication mode is not supported on the current chip
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer or illegal parameter in i2s_chan_config_t
|
||||
* - ESP_ERR_NOT_FOUND No available I2S channel found
|
||||
*/
|
||||
esp_err_t i2s_new_channel(const i2s_chan_config_t *chan_cfg, i2s_chan_handle_t *ret_tx_handle, i2s_chan_handle_t *ret_rx_handle);
|
||||
|
||||
/**
|
||||
* @brief Delete the i2s channel
|
||||
* @note Only allowed to be called when the i2s channel is at REGISTERED or READY state (i.e., it should stop before deleting it).
|
||||
* @note Resource will be free automatically if all channels in one port are deleted
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* - ESP_OK Delete successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer
|
||||
*/
|
||||
esp_err_t i2s_del_channel(i2s_chan_handle_t handle);
|
||||
|
||||
/**
|
||||
* @brief Get I2S channel information
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[out] chan_info I2S channel basic information
|
||||
* @return
|
||||
* - ESP_OK Get i2s channel information success
|
||||
* - ESP_ERR_NOT_FOUND The input handle doesn't match any registered I2S channels, it may not an i2s channel handle or not available any more
|
||||
* - ESP_ERR_INVALID_ARG The input handle or chan_info pointer is NULL
|
||||
*/
|
||||
esp_err_t i2s_channel_get_info(i2s_chan_handle_t handle, i2s_chan_info_t *chan_info);
|
||||
|
||||
/**
|
||||
* @brief Enable the i2s channel
|
||||
* @note Only allowed to be called when the channel state is READY, (i.e., channel has been initialized, but not started)
|
||||
* the channel will enter RUNNING state once it is enabled successfully.
|
||||
* @note Enbale the channel can start the I2S communication on hardware. It will start outputting bclk and ws signal.
|
||||
* For mclk signal, it will start to output when initialization is finished
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* - ESP_OK Start successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer
|
||||
* - ESP_ERR_INVALID_STATE This channel has not initialized or already started
|
||||
*/
|
||||
esp_err_t i2s_channel_enable(i2s_chan_handle_t handle);
|
||||
|
||||
/**
|
||||
* @brief Disable the i2s channel
|
||||
* @note Only allowed to be called when the channel state is READY / RUNNING, (i.e., channel has been initialized)
|
||||
* the channel will enter READY state once it is disabled successfully.
|
||||
* @note Disable the channel can stop the I2S communication on hardware. It will stop bclk and ws signal but not mclk signal
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @return
|
||||
* - ESP_OK Stop successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer
|
||||
* - ESP_ERR_INVALID_STATE This channel has not stated
|
||||
*/
|
||||
esp_err_t i2s_channel_disable(i2s_chan_handle_t handle);
|
||||
|
||||
/**
|
||||
* @brief I2S write data
|
||||
* @note Only allowed to be called when the channel state is RUNNING, (i.e., tx channel has been started and is not writing now)
|
||||
* but the RUNNING only stands for the software state, it doesn't mean there is no the signal transporting on line.
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] src The pointer of sent data buffer
|
||||
* @param[in] size Max data buffer length
|
||||
* @param[out] bytes_written Byte number that actually be sent
|
||||
* @param[in] timeout_ms Max block time
|
||||
* @return
|
||||
* - ESP_OK Write successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer or this handle is not tx handle
|
||||
* - ESP_ERR_TIMEOUT Writing timeout, no writing event received from ISR within ticks_to_wait
|
||||
* - ESP_ERR_INVALID_STATE I2S is not ready to write
|
||||
*/
|
||||
esp_err_t i2s_channel_write(i2s_chan_handle_t handle, const void *src, size_t size, size_t *bytes_written, uint32_t timeout_ms);
|
||||
|
||||
/**
|
||||
* @brief I2S read data
|
||||
* @note Only allowed to be called when the channel state is RUNNING
|
||||
* but the RUNNING only stands for the software state, it doesn't mean there is no the signal transporting on line.
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] dest The pointer of receiving data buffer
|
||||
* @param[in] size Max data buffer length
|
||||
* @param[out] bytes_read Byte number that actually be read
|
||||
* @param[in] timeout_ms Max block time
|
||||
* @return
|
||||
* - ESP_OK Read successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer or this handle is not rx handle
|
||||
* - ESP_ERR_TIMEOUT Reading timeout, no reading event received from ISR within ticks_to_wait
|
||||
* - ESP_ERR_INVALID_STATE I2S is not ready to read
|
||||
*/
|
||||
esp_err_t i2s_channel_read(i2s_chan_handle_t handle, void *dest, size_t size, size_t *bytes_read, uint32_t timeout_ms);
|
||||
|
||||
/**
|
||||
* @brief Set event callbacks for I2S channel
|
||||
*
|
||||
* @note Only allowed to be called when the channel state is REGISTARED / READY, (i.e., before channel starts)
|
||||
* @note User can deregister a previously registered callback by calling this function and setting the callback member in the `callbacks` structure to NULL.
|
||||
* @note When CONFIG_I2S_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM.
|
||||
* The variables used in the function should be in the SRAM as well. The `user_data` should also reside in SRAM or internal RAM as well.
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] callbacks Group of callback functions
|
||||
* @param[in] user_data User data, which will be passed to callback functions directly
|
||||
* @return
|
||||
* - ESP_OK Set event callbacks successfully
|
||||
* - ESP_ERR_INVALID_ARG Set event callbacks failed because of invalid argument
|
||||
* - ESP_ERR_INVALID_STATE Set event callbacks failed because the current channel state is not REGISTARED or READY
|
||||
*/
|
||||
esp_err_t i2s_channel_register_event_callback(i2s_chan_handle_t handle, const i2s_event_callbacks_t *callbacks, void *user_data);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,354 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* This file is specified for I2S PDM communication mode
|
||||
* Features:
|
||||
* - Only support PDM tx/rx mode
|
||||
* - Fixed to 2 slots
|
||||
* - Data bit width only support 16 bits
|
||||
*/
|
||||
#pragma once
|
||||
|
||||
#include "hal/i2s_types.h"
|
||||
#include "hal/gpio_types.h"
|
||||
#include "driver/i2s_common.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#if SOC_I2S_SUPPORTS_PDM_RX
|
||||
|
||||
/**
|
||||
* @brief PDM format in 2 slots(RX)
|
||||
* @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_PDM_RX_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief i2s default pdm rx clock configuration
|
||||
* @param rate sample rate
|
||||
*/
|
||||
#define I2S_PDM_RX_CLK_DEFAULT_CONFIG(rate) { \
|
||||
.sample_rate_hz = rate, \
|
||||
.clk_src = I2S_CLK_SRC_DEFAULT, \
|
||||
.mclk_multiple = I2S_MCLK_MULTIPLE_256, \
|
||||
.dn_sample_mode = I2S_PDM_DSR_8S \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief I2S slot configuration for pdm rx mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
i2s_data_bit_width_t data_bit_width; /*!< I2S sample data bit width (valid data bits per sample), only support 16 bits for PDM mode */
|
||||
i2s_slot_bit_width_t slot_bit_width; /*!< I2S slot bit width (total bits per slot) , only support 16 bits for PDM mode */
|
||||
i2s_slot_mode_t slot_mode; /*!< Set mono or stereo mode with I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO */
|
||||
} i2s_pdm_rx_slot_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S clock configuration for pdm rx mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
uint32_t sample_rate_hz; /*!< I2S sample rate */
|
||||
i2s_clock_src_t clk_src; /*!< Choose clock source */
|
||||
i2s_mclk_multiple_t mclk_multiple; /*!< The multiple of mclk to the sample rate */
|
||||
/* Particular fields */
|
||||
i2s_pdm_dsr_t dn_sample_mode; /*!< Down-sampling rate mode */
|
||||
} i2s_pdm_rx_clk_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S PDM tx mode GPIO pins configuration
|
||||
*/
|
||||
typedef struct {
|
||||
gpio_num_t clk; /*!< PDM clk pin, output */
|
||||
gpio_num_t din; /*!< DATA pin, input */
|
||||
struct {
|
||||
uint32_t clk_inv: 1; /*!< Set 1 to invert the clk output */
|
||||
} invert_flags; /*!< GPIO pin invert flags */
|
||||
} i2s_pdm_rx_gpio_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S PDM RX mode major configuration that including clock/slot/gpio configuration
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_pdm_rx_clk_config_t clk_cfg; /*!< PDM RX clock configurations, can be genertated by macro I2S_PDM_RX_CLK_DEFAULT_CONFIG */
|
||||
i2s_pdm_rx_slot_config_t slot_cfg; /*!< PDM RX slot configurations, can be genertated by macro I2S_PDM_RX_SLOT_DEFAULT_CONFIG */
|
||||
i2s_pdm_rx_gpio_config_t gpio_cfg; /*!< PDM RX slot configurations, specified by user */
|
||||
} i2s_pdm_rx_config_t;
|
||||
|
||||
/**
|
||||
* @brief Initialize i2s channel to PDM RX mode
|
||||
* @note Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
|
||||
* and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
|
||||
*
|
||||
* @param[in] handle I2S rx channel handler
|
||||
* @param[in] pdm_rx_cfg Configurations for PDM RX mode, including clock, slot and gpio
|
||||
* The clock configuration can be generated by the helper macro `I2S_PDM_RX_CLK_DEFAULT_CONFIG`
|
||||
* The slot configuration can be generated by the helper macro `I2S_PDM_RX_SLOT_DEFAULT_CONFIG`
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Initialize successfully
|
||||
* - ESP_ERR_NO_MEM No memory for storing the channel information
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer or invalid configuration
|
||||
* - ESP_ERR_INVALID_STATE This channel is not registered
|
||||
*/
|
||||
esp_err_t i2s_channel_init_pdm_rx_mode(i2s_chan_handle_t handle, const i2s_pdm_rx_config_t *pdm_rx_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S clock for PDM RX mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S rx channel handler
|
||||
* @param[in] clk_cfg PDM RX mode clock configuration, can be generated by `I2S_PDM_RX_CLK_DEFAULT_CONFIG`
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not PDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_pdm_rx_clock(i2s_chan_handle_t handle, const i2s_pdm_rx_clk_config_t *clk_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S slot for PDM RX mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S rx channel handler
|
||||
* @param[in] slot_cfg PDM RX mode slot configuration, can be generated by `I2S_PDM_RX_SLOT_DEFAULT_CONFIG`
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_NO_MEM No memory for DMA buffer
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not PDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_pdm_rx_slot(i2s_chan_handle_t handle, const i2s_pdm_rx_slot_config_t *slot_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S gpio for PDM RX mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S rx channel handler
|
||||
* @param[in] gpio_cfg PDM RX mode gpio configuration, specified by user
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not PDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_pdm_rx_gpio_config_t *gpio_cfg);
|
||||
|
||||
|
||||
#endif // SOC_I2S_SUPPORTS_PDM_RX
|
||||
|
||||
|
||||
#if SOC_I2S_SUPPORTS_PDM_TX
|
||||
#if SOC_I2S_HW_VERSION_2
|
||||
/**
|
||||
* @brief PDM style in 2 slots(TX)
|
||||
* @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_PDM_TX_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.sd_prescale = 0, \
|
||||
.sd_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
.hp_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
.lp_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
.sinc_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
.sd_en = true, \
|
||||
.hp_en = true, \
|
||||
.hp_cut_off_freq_hz = 49, \
|
||||
.sd_dither = 0, \
|
||||
.sd_dither2 = 0, \
|
||||
}
|
||||
#else
|
||||
/**
|
||||
* @brief PDM style in 2 slots(TX)
|
||||
* @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_PDM_TX_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.sd_prescale = 0, \
|
||||
.sd_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
.hp_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
.lp_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
.sinc_scale = I2S_PDM_SIG_SCALING_MUL_1, \
|
||||
}
|
||||
#endif // SOC_I2S_HW_VERSION_2
|
||||
|
||||
/**
|
||||
* @brief i2s default pdm tx clock configuration
|
||||
* @note TX PDM can only be set to the following two up-sampling rate configurations:
|
||||
* 1: fp = 960, fs = sample_rate_hz / 100, in this case, Fpdm = 128*48000
|
||||
* 2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm = 128*sample_rate_hz
|
||||
* If the pdm receiver do not care the pdm serial clock, it's recommended set Fpdm = 128*48000.
|
||||
* Otherwise, the second configuration should be adopted.
|
||||
* @param rate sample rate
|
||||
*/
|
||||
#define I2S_PDM_TX_CLK_DEFAULT_CONFIG(rate) { \
|
||||
.sample_rate_hz = rate, \
|
||||
.clk_src = I2S_CLK_SRC_DEFAULT, \
|
||||
.mclk_multiple = I2S_MCLK_MULTIPLE_256, \
|
||||
.up_sample_fp = 960, \
|
||||
.up_sample_fs = ((rate) / 100), \
|
||||
}
|
||||
|
||||
/*
|
||||
High Pass Filter Cut-off Frequency Sheet
|
||||
+----------------+------------------+----------------+------------------+----------------+------------------+
|
||||
| param0, param5 | cut-off freq(Hz) | param0, param5 | cut-off freq(Hz) | param0, param5 | cut-off freq(Hz) |
|
||||
+----------------+------------------+----------------+------------------+----------------+------------------+
|
||||
| (0, 0) | 185 | (3, 3) | 115 | (5, 5) | 69 |
|
||||
| (0, 1) | 172 | (1, 7) | 106 | (4, 7) | 63 |
|
||||
| (1, 1) | 160 | (2, 4) | 104 | (5, 6) | 58 |
|
||||
| (1, 2) | 150 | (4, 4) | 92 | (5, 7) | 49 |
|
||||
| (2, 2) | 137 | (2, 7) | 91.5 | (6, 6) | 46 |
|
||||
| (2, 3) | 126 | (4, 5) | 81 | (6, 7) | 35.5 |
|
||||
| (0, 3) | 120 | (3, 7) | 77.2 | (7, 7) | 23.3 |
|
||||
+----------------+------------------+----------------+------------------+----------------+------------------+
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief I2S slot configuration for pdm tx mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
i2s_data_bit_width_t data_bit_width; /*!< I2S sample data bit width (valid data bits per sample), only support 16 bits for PDM mode */
|
||||
i2s_slot_bit_width_t slot_bit_width; /*!< I2S slot bit width (total bits per slot), only support 16 bits for PDM mode */
|
||||
i2s_slot_mode_t slot_mode; /*!< Set mono or stereo mode with I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO */
|
||||
/* Particular fields */
|
||||
uint32_t sd_prescale; /*!< Sigma-delta filter prescale */
|
||||
i2s_pdm_sig_scale_t sd_scale; /*!< Sigma-delta filter scaling value */
|
||||
i2s_pdm_sig_scale_t hp_scale; /*!< High pass filter scaling value */
|
||||
i2s_pdm_sig_scale_t lp_scale; /*!< Low pass filter scaling value */
|
||||
i2s_pdm_sig_scale_t sinc_scale; /*!< Sinc filter scaling value */
|
||||
#if SOC_I2S_HW_VERSION_2
|
||||
bool sd_en; /*!< Sigma-delta filter enable */
|
||||
bool hp_en; /*!< High pass filter enable */
|
||||
float hp_cut_off_freq_hz; /*!< High pass filter cut-off frequency, range 23.3Hz ~ 185Hz, see cut-off frequency sheet above */
|
||||
uint32_t sd_dither; /*!< Sigma-delta filter dither */
|
||||
uint32_t sd_dither2; /*!< Sigma-delta filter dither2 */
|
||||
#endif // SOC_I2S_HW_VERSION_2
|
||||
} i2s_pdm_tx_slot_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S clock configuration for pdm tx mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
uint32_t sample_rate_hz; /*!< I2S sample rate */
|
||||
i2s_clock_src_t clk_src; /*!< Choose clock source */
|
||||
i2s_mclk_multiple_t mclk_multiple; /*!< The multiple of mclk to the sample rate */
|
||||
/* Particular fields */
|
||||
uint32_t up_sample_fp; /*!< Up-sampling param fp */
|
||||
uint32_t up_sample_fs; /*!< Up-sampling param fs */
|
||||
} i2s_pdm_tx_clk_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S PDM tx mode GPIO pins configuration
|
||||
*/
|
||||
typedef struct {
|
||||
gpio_num_t clk; /*!< PDM clk pin, output */
|
||||
gpio_num_t dout; /*!< DATA pin, output */
|
||||
struct {
|
||||
uint32_t clk_inv: 1; /*!< Set 1 to invert the clk output */
|
||||
} invert_flags; /*!< GPIO pin invert flags */
|
||||
} i2s_pdm_tx_gpio_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S PDM TX mode major configuration that including clock/slot/gpio configuration
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_pdm_tx_clk_config_t clk_cfg; /*!< PDM TX clock configurations, can be genertated by macro I2S_PDM_TX_CLK_DEFAULT_CONFIG */
|
||||
i2s_pdm_tx_slot_config_t slot_cfg; /*!< PDM TX slot configurations, can be genertated by macro I2S_PDM_TX_SLOT_DEFAULT_CONFIG */
|
||||
i2s_pdm_tx_gpio_config_t gpio_cfg; /*!< PDM TX gpio configurations, specified by user */
|
||||
} i2s_pdm_tx_config_t;
|
||||
|
||||
/**
|
||||
* @brief Initialize i2s channel to PDM TX mode
|
||||
* @note Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
|
||||
* and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
|
||||
*
|
||||
* @param[in] handle I2S tx channel handler
|
||||
* @param[in] pdm_tx_cfg Configurations for PDM TX mode, including clock, slot and gpio
|
||||
* The clock configuration can be generated by the helper macro `I2S_PDM_TX_CLK_DEFAULT_CONFIG`
|
||||
* The slot configuration can be generated by the helper macro `I2S_PDM_TX_SLOT_DEFAULT_CONFIG`
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Initialize successfully
|
||||
* - ESP_ERR_NO_MEM No memory for storing the channel information
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer or invalid configuration
|
||||
* - ESP_ERR_INVALID_STATE This channel is not registered
|
||||
*/
|
||||
esp_err_t i2s_channel_init_pdm_tx_mode(i2s_chan_handle_t handle, const i2s_pdm_tx_config_t *pdm_tx_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S clock for PDM TX mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S tx channel handler
|
||||
* @param[in] clk_cfg PDM TX mode clock configuration, can be generated by `I2S_PDM_TX_CLK_DEFAULT_CONFIG`
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not PDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_pdm_tx_clock(i2s_chan_handle_t handle, const i2s_pdm_tx_clk_config_t *clk_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S slot for PDM TX mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S tx channel handler
|
||||
* @param[in] slot_cfg PDM TX mode slot configuration, can be generated by `I2S_PDM_TX_SLOT_DEFAULT_CONFIG`
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_NO_MEM No memory for DMA buffer
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not PDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_pdm_tx_slot(i2s_chan_handle_t handle, const i2s_pdm_tx_slot_config_t *slot_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S gpio for PDM TX mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S tx channel handler
|
||||
* @param[in] gpio_cfg PDM TX mode gpio configuration, specified by user
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not PDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_pdm_tx_gpio(i2s_chan_handle_t handle, const i2s_pdm_tx_gpio_config_t *gpio_cfg);
|
||||
|
||||
#endif // SOC_I2S_SUPPORTS_PDM_TX
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,274 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* This file is specified for I2S standard communication mode
|
||||
* Features:
|
||||
* - Philip/MSB/PCM are supported in standard mode
|
||||
* - Fixed to 2 slots
|
||||
*/
|
||||
#pragma once
|
||||
|
||||
#include "hal/i2s_types.h"
|
||||
#include "hal/gpio_types.h"
|
||||
#include "driver/i2s_common.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#if SOC_I2S_HW_VERSION_1 // For esp32/esp32-s2
|
||||
/**
|
||||
* @brief Philip format in 2 slots
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_STD_PHILIP_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mono_or_stereo == I2S_SLOT_MODE_MONO) ? \
|
||||
I2S_STD_SLOT_ONLY_LEFT : I2S_STD_SLOT_LEFT_RIGHT, \
|
||||
.ws_width = bits_per_sample, \
|
||||
.ws_pol = false, \
|
||||
.bit_shift = true, \
|
||||
.msb_right = true, \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief PCM(short) format in 2 slots
|
||||
* @note PCM(long) is sample as philip in 2 slots
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_STD_PCM_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mono_or_stereo == I2S_SLOT_MODE_MONO) ? \
|
||||
I2S_STD_SLOT_ONLY_LEFT : I2S_STD_SLOT_LEFT_RIGHT, \
|
||||
.ws_width = 1, \
|
||||
.ws_pol = true, \
|
||||
.bit_shift = true, \
|
||||
.msb_right = true, \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief MSB format in 2 slots
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_STD_MSB_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mono_or_stereo == I2S_SLOT_MODE_MONO) ? \
|
||||
I2S_STD_SLOT_ONLY_LEFT : I2S_STD_SLOT_LEFT_RIGHT, \
|
||||
.ws_width = bits_per_sample, \
|
||||
.ws_pol = false, \
|
||||
.bit_shift = false, \
|
||||
.msb_right = true, \
|
||||
}
|
||||
|
||||
#else
|
||||
/**
|
||||
* @brief Philip format in 2 slots
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_STD_PHILIP_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mono_or_stereo == I2S_SLOT_MODE_MONO) ? \
|
||||
I2S_STD_SLOT_ONLY_LEFT : I2S_STD_SLOT_LEFT_RIGHT, \
|
||||
.ws_width = bits_per_sample, \
|
||||
.ws_pol = false, \
|
||||
.bit_shift = true, \
|
||||
.left_align = false, \
|
||||
.big_endian = false, \
|
||||
.bit_order_lsb = false \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief PCM(short) format in 2 slots
|
||||
* @note PCM(long) is sample as philip in 2 slots
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_STD_PCM_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mono_or_stereo == I2S_SLOT_MODE_MONO) ? \
|
||||
I2S_STD_SLOT_ONLY_LEFT : I2S_STD_SLOT_LEFT_RIGHT, \
|
||||
.ws_width = 1, \
|
||||
.ws_pol = true, \
|
||||
.bit_shift = true, \
|
||||
.left_align = false, \
|
||||
.big_endian = false, \
|
||||
.bit_order_lsb = false \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief MSB format in 2 slots
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
*/
|
||||
#define I2S_STD_MSB_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
|
||||
.data_bit_width = bits_per_sample, \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mono_or_stereo == I2S_SLOT_MODE_MONO) ? \
|
||||
I2S_STD_SLOT_ONLY_LEFT : I2S_STD_SLOT_LEFT_RIGHT, \
|
||||
.ws_width = bits_per_sample, \
|
||||
.ws_pol = false, \
|
||||
.bit_shift = false, \
|
||||
.left_align = false, \
|
||||
.big_endian = false, \
|
||||
.bit_order_lsb = false \
|
||||
}
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief i2s default standard clock configuration
|
||||
* @note Please set the mclk_multiple to I2S_MCLK_MULTIPLE_384 while using 24 bits data width
|
||||
* Otherwise the sample rate might be imprecise since the bclk division is not a integer
|
||||
* @param rate sample rate
|
||||
*/
|
||||
#define I2S_STD_CLK_DEFAULT_CONFIG(rate) { \
|
||||
.sample_rate_hz = rate, \
|
||||
.clk_src = I2S_CLK_SRC_DEFAULT, \
|
||||
.mclk_multiple = I2S_MCLK_MULTIPLE_256, \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief I2S slot configuration for standard mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
i2s_data_bit_width_t data_bit_width; /*!< I2S sample data bit width (valid data bits per sample) */
|
||||
i2s_slot_bit_width_t slot_bit_width; /*!< I2S slot bit width (total bits per slot) */
|
||||
i2s_slot_mode_t slot_mode; /*!< Set mono or stereo mode with I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO */
|
||||
|
||||
/* Particular fields */
|
||||
i2s_std_slot_mask_t slot_mask; /*!< Select the left, right or both slot */
|
||||
uint32_t ws_width; /*!< WS signal width (i.e. the number of bclk ticks that ws signal is high) */
|
||||
bool ws_pol; /*!< WS signal polarity, set true to enable high lever first */
|
||||
bool bit_shift; /*!< Set to enbale bit shift in Philip mode */
|
||||
#if SOC_I2S_HW_VERSION_1 // For esp32/esp32-s2
|
||||
bool msb_right; /*!< Set to place right channel data at the MSB in the FIFO */
|
||||
#else
|
||||
bool left_align; /*!< Set to enable left alignment */
|
||||
bool big_endian; /*!< Set to enable big endian */
|
||||
bool bit_order_lsb; /*!< Set to enable lsb first */
|
||||
#endif
|
||||
} i2s_std_slot_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S clock configuration for standard mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
uint32_t sample_rate_hz; /*!< I2S sample rate */
|
||||
i2s_clock_src_t clk_src; /*!< Choose clock source */
|
||||
i2s_mclk_multiple_t mclk_multiple; /*!< The multiple of mclk to the sample rate */
|
||||
} i2s_std_clk_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S standard mode GPIO pins configuration
|
||||
*/
|
||||
typedef struct {
|
||||
gpio_num_t mclk; /*!< MCK pin, output */
|
||||
gpio_num_t bclk; /*!< BCK pin, input in slave role, output in master role */
|
||||
gpio_num_t ws; /*!< WS pin, input in slave role, output in master role */
|
||||
gpio_num_t dout; /*!< DATA pin, output */
|
||||
gpio_num_t din; /*!< DATA pin, input */
|
||||
struct {
|
||||
uint32_t mclk_inv: 1; /*!< Set 1 to invert the mclk output */
|
||||
uint32_t bclk_inv: 1; /*!< Set 1 to invert the bclk input/output */
|
||||
uint32_t ws_inv: 1; /*!< Set 1 to invert the ws input/output */
|
||||
} invert_flags; /*!< GPIO pin invert flags */
|
||||
} i2s_std_gpio_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S standard mode major configuration that including clock/slot/gpio configuration
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_std_clk_config_t clk_cfg; /*!< Standard mode clock configuration, can be generated by macro I2S_STD_CLK_DEFAULT_CONFIG */
|
||||
i2s_std_slot_config_t slot_cfg; /*!< Standard mode slot configuration, can be generated by macros I2S_STD_[mode]_SLOT_DEFAULT_CONFIG, [mode] can be replaced with PHILIP/MSB/PCM */
|
||||
i2s_std_gpio_config_t gpio_cfg; /*!< Standard mode gpio configuration, specified by user */
|
||||
} i2s_std_config_t;
|
||||
|
||||
/**
|
||||
* @brief Initialize i2s channel to standard mode
|
||||
* @note Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
|
||||
* and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] std_cfg Configurations for standard mode, including clock, slot and gpio
|
||||
* The clock configuration can be generated by the helper macro `I2S_STD_CLK_DEFAULT_CONFIG`
|
||||
* The slot configuration can be generated by the helper macro `I2S_STD_PHILIP_SLOT_DEFAULT_CONFIG`,
|
||||
* `I2S_STD_PCM_SLOT_DEFAULT_CONFIG` or `I2S_STD_MSB_SLOT_DEFAULT_CONFIG`
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Initialize successfully
|
||||
* - ESP_ERR_NO_MEM No memory for storing the channel information
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer or invalid configuration
|
||||
* - ESP_ERR_INVALID_STATE This channel is not registered
|
||||
*/
|
||||
esp_err_t i2s_channel_init_std_mode(i2s_chan_handle_t handle, const i2s_std_config_t *std_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S clock for standard mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] clk_cfg Standard mode clock configuration, can be generated by `I2S_STD_CLK_DEFAULT_CONFIG`
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not standard mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_std_clock(i2s_chan_handle_t handle, const i2s_std_clk_config_t *clk_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S slot for standard mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] slot_cfg Standard mode slot configuration, can be generated by `I2S_STD_PHILIP_SLOT_DEFAULT_CONFIG`,
|
||||
* `I2S_STD_PCM_SLOT_DEFAULT_CONFIG` and `I2S_STD_MSB_SLOT_DEFAULT_CONFIG`.
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_NO_MEM No memory for DMA buffer
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not standard mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_std_slot(i2s_chan_handle_t handle, const i2s_std_slot_config_t *slot_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S gpio for standard mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] gpio_cfg Standard mode gpio configuration, specified by user
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not standard mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_std_gpio(i2s_chan_handle_t handle, const i2s_std_gpio_config_t *gpio_cfg);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,252 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* This file is specified for I2S TDM communication mode
|
||||
* Features:
|
||||
* - More than 2 slots
|
||||
*/
|
||||
#pragma once
|
||||
|
||||
#include "hal/i2s_types.h"
|
||||
#include "hal/gpio_types.h"
|
||||
#include "driver/i2s_common.h"
|
||||
|
||||
#if SOC_I2S_SUPPORTS_TDM
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define I2S_TDM_AUTO_SLOT_NUM (0) // Auto means total slot number will be equal to the maximum active slot number
|
||||
#define I2S_TDM_AUTO_WS_WIDTH (0) // Auto means ws signal width will be equal to the half width of a frame
|
||||
|
||||
/**
|
||||
* @brief Philip format in active slot that enabled by mask
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
* @param mask active slot mask
|
||||
*/
|
||||
#define I2S_TDM_PHILIP_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo, mask) { \
|
||||
.data_bit_width = (bits_per_sample), \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mask), \
|
||||
.ws_width = I2S_TDM_AUTO_WS_WIDTH, \
|
||||
.ws_pol = false, \
|
||||
.bit_shift = true, \
|
||||
.left_align = false, \
|
||||
.big_endian = false, \
|
||||
.bit_order_lsb = false, \
|
||||
.skip_mask = false, \
|
||||
.total_slot = I2S_TDM_AUTO_SLOT_NUM \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief MSB format in active slot enabled that by mask
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
* @param mask active slot mask
|
||||
*/
|
||||
#define I2S_TDM_MSB_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo, mask) { \
|
||||
.data_bit_width = (bits_per_sample), \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mask), \
|
||||
.ws_width = I2S_TDM_AUTO_WS_WIDTH, \
|
||||
.ws_pol = false, \
|
||||
.bit_shift = false, \
|
||||
.left_align = false, \
|
||||
.big_endian = false, \
|
||||
.bit_order_lsb = false, \
|
||||
.skip_mask = false ,\
|
||||
.total_slot = I2S_TDM_AUTO_SLOT_NUM \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief PCM(short) format in active slot that enabled by mask
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
* @param mask active slot mask
|
||||
*/
|
||||
#define I2S_TDM_PCM_SHORT_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo, mask) { \
|
||||
.data_bit_width = (bits_per_sample), \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mask), \
|
||||
.ws_width = 1, \
|
||||
.ws_pol = true, \
|
||||
.bit_shift = true, \
|
||||
.left_align = false, \
|
||||
.big_endian = false, \
|
||||
.bit_order_lsb = false, \
|
||||
.skip_mask = false, \
|
||||
.total_slot = I2S_TDM_AUTO_SLOT_NUM \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief PCM(long) format in active slot that enabled by mask
|
||||
* @param bits_per_sample i2s data bit width
|
||||
* @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
|
||||
* @param mask active slot mask
|
||||
*/
|
||||
#define I2S_TDM_PCM_LONG_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo, mask) { \
|
||||
.data_bit_width = (bits_per_sample), \
|
||||
.slot_bit_width = I2S_SLOT_BIT_WIDTH_AUTO, \
|
||||
.slot_mode = mono_or_stereo, \
|
||||
.slot_mask = (mask), \
|
||||
.ws_width = (bits_per_sample), \
|
||||
.ws_pol = true, \
|
||||
.bit_shift = true, \
|
||||
.left_align = false, \
|
||||
.big_endian = false, \
|
||||
.bit_order_lsb = false, \
|
||||
.skip_mask = false, \
|
||||
.total_slot = I2S_TDM_AUTO_SLOT_NUM \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief i2s default tdm clock configuration
|
||||
* @note Please set the mclk_multiple to I2S_MCLK_MULTIPLE_384 while the data width in slot configuration is set to 24 bits
|
||||
* Otherwise the sample rate might be imprecise since the bclk division is not a integer
|
||||
* @param rate sample rate
|
||||
*/
|
||||
#define I2S_TDM_CLK_DEFAULT_CONFIG(rate) { \
|
||||
.sample_rate_hz = rate, \
|
||||
.clk_src = I2S_CLK_SRC_DEFAULT, \
|
||||
.mclk_multiple = I2S_MCLK_MULTIPLE_256, \
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief I2S slot configuration for tdm mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
i2s_data_bit_width_t data_bit_width; /*!< I2S sample data bit width (valid data bits per sample) */
|
||||
i2s_slot_bit_width_t slot_bit_width; /*!< I2S slot bit width (total bits per slot) */
|
||||
i2s_slot_mode_t slot_mode; /*!< Set mono or stereo mode with I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO */
|
||||
|
||||
/* Particular fields */
|
||||
i2s_tdm_slot_mask_t slot_mask; /*!< Slot mask. Activating slots by setting 1 to corresponding bits. When the activated slots is not consecutive, those data in unactivated slots will be ignored */
|
||||
uint32_t ws_width; /*!< WS signal width (i.e. the number of bclk ticks that ws signal is high) */
|
||||
bool ws_pol; /*!< WS signal polarity, set true to enable high lever first */
|
||||
bool bit_shift; /*!< Set true to enable bit shift in Philip mode */
|
||||
|
||||
bool left_align; /*!< Set true to enable left alignment */
|
||||
bool big_endian; /*!< Set true to enable big endian */
|
||||
bool bit_order_lsb; /*!< Set true to enable lsb first */
|
||||
|
||||
bool skip_mask; /*!< Set true to enable skip mask. If it is enabled, only the data of the enabled channels will be sent, otherwise all data stored in DMA TX buffer will be sent */
|
||||
uint32_t total_slot; /*!< I2S total number of slots. If it is smaller than the biggest activated channel number, it will be set to this number automatically. */
|
||||
} i2s_tdm_slot_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S clock configuration for tdm mode
|
||||
*/
|
||||
typedef struct {
|
||||
/* General fields */
|
||||
uint32_t sample_rate_hz; /*!< I2S sample rate */
|
||||
i2s_clock_src_t clk_src; /*!< Choose clock source */
|
||||
i2s_mclk_multiple_t mclk_multiple; /*!< The multiple of mclk to the sample rate */
|
||||
} i2s_tdm_clk_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S TDM mode GPIO pins configuration
|
||||
*/
|
||||
typedef struct {
|
||||
gpio_num_t mclk; /*!< MCK pin, output */
|
||||
gpio_num_t bclk; /*!< BCK pin, input in slave role, output in master role */
|
||||
gpio_num_t ws; /*!< WS pin, input in slave role, output in master role */
|
||||
gpio_num_t dout; /*!< DATA pin, output */
|
||||
gpio_num_t din; /*!< DATA pin, input */
|
||||
struct {
|
||||
uint32_t mclk_inv: 1; /*!< Set 1 to invert the mclk output */
|
||||
uint32_t bclk_inv: 1; /*!< Set 1 to invert the bclk input/output */
|
||||
uint32_t ws_inv: 1; /*!< Set 1 to invert the ws input/output */
|
||||
} invert_flags; /*!< GPIO pin invert flags */
|
||||
} i2s_tdm_gpio_config_t;
|
||||
|
||||
/**
|
||||
* @brief I2S TDM mode major configuration that including clock/slot/gpio configuration
|
||||
*/
|
||||
typedef struct {
|
||||
i2s_tdm_clk_config_t clk_cfg; /*!< TDM mode clock configuration, can be generated by macro I2S_TDM_CLK_DEFAULT_CONFIG */
|
||||
i2s_tdm_slot_config_t slot_cfg; /*!< TDM mode slot configuration, can be generated by macros I2S_TDM_[mode]_SLOT_DEFAULT_CONFIG, [mode] can be replaced with PHILIP/MSB/PCM_SHORT/PCM_LONG */
|
||||
i2s_tdm_gpio_config_t gpio_cfg; /*!< TDM mode gpio configuration, specified by user */
|
||||
} i2s_tdm_config_t;
|
||||
|
||||
/**
|
||||
* @brief Initialize i2s channel to TDM mode
|
||||
* @note Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
|
||||
* and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] tdm_cfg Configurations for TDM mode, including clock, slot and gpio
|
||||
* The clock configuration can be generated by the helper macro `I2S_TDM_CLK_DEFAULT_CONFIG`
|
||||
* The slot configuration can be generated by the helper macro `I2S_TDM_PHILIP_SLOT_DEFAULT_CONFIG`,
|
||||
* `I2S_TDM_PCM_SHORT_SLOT_DEFAULT_CONFIG`, `I2S_TDM_PCM_LONG_SLOT_DEFAULT_CONFIG` or `I2S_TDM_MSB_SLOT_DEFAULT_CONFIG`
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Initialize successfully
|
||||
* - ESP_ERR_NO_MEM No memory for storing the channel information
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer or invalid configuration
|
||||
* - ESP_ERR_INVALID_STATE This channel is not registered
|
||||
*/
|
||||
esp_err_t i2s_channel_init_tdm_mode(i2s_chan_handle_t handle, const i2s_tdm_config_t *tdm_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S clock for TDM mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] clk_cfg Standard mode clock configuration, can be generated by `I2S_TDM_CLK_DEFAULT_CONFIG`
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not TDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_tdm_clock(i2s_chan_handle_t handle, const i2s_tdm_clk_config_t *clk_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S slot for TDM mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] slot_cfg Standard mode slot configuration, can be generated by `I2S_TDM_PHILIP_SLOT_DEFAULT_CONFIG`,
|
||||
* `I2S_TDM_PCM_SHORT_SLOT_DEFAULT_CONFIG`, `I2S_TDM_PCM_LONG_SLOT_DEFAULT_CONFIG` or `I2S_TDM_MSB_SLOT_DEFAULT_CONFIG`.
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_NO_MEM No memory for DMA buffer
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not TDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_tdm_slot(i2s_chan_handle_t handle, const i2s_tdm_slot_config_t *slot_cfg);
|
||||
|
||||
/**
|
||||
* @brief Reconfigure the I2S gpio for TDM mode
|
||||
* @note Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
|
||||
* this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
|
||||
* @note The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfigring
|
||||
*
|
||||
* @param[in] handle I2S channel handler
|
||||
* @param[in] gpio_cfg Standard mode gpio configuration, specified by user
|
||||
* @return
|
||||
* - ESP_OK Set clock successfully
|
||||
* - ESP_ERR_INVALID_ARG NULL pointer, invalid configuration or not TDM mode
|
||||
* - ESP_ERR_INVALID_STATE This channel is not initialized or not stopped
|
||||
*/
|
||||
esp_err_t i2s_channel_reconfig_tdm_gpio(i2s_chan_handle_t handle, const i2s_tdm_gpio_config_t *gpio_cfg);
|
||||
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif // SOC_I2S_SUPPORTS_TDM
|
||||
@@ -0,0 +1,79 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stdbool.h>
|
||||
#include <stddef.h>
|
||||
#include "soc/soc_caps.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief I2S controller port number, the max port number is (SOC_I2S_NUM -1).
|
||||
*/
|
||||
typedef enum {
|
||||
I2S_NUM_0 = 0, /*!< I2S controller port 0 */
|
||||
#if SOC_I2S_NUM > 1
|
||||
I2S_NUM_1 = 1, /*!< I2S controller port 1 */
|
||||
#endif
|
||||
I2S_NUM_AUTO, /*!< Select whichever port is available */
|
||||
} i2s_port_t;
|
||||
|
||||
/**
|
||||
* @brief I2S controller communication mode
|
||||
*/
|
||||
typedef enum {
|
||||
I2S_COMM_MODE_STD, /*!< I2S controller using standard communication mode, support philip/MSB/PCM format */
|
||||
#if SOC_I2S_SUPPORTS_PDM
|
||||
I2S_COMM_MODE_PDM, /*!< I2S controller using PDM communication mode, support PDM output or input */
|
||||
#endif
|
||||
#if SOC_I2S_SUPPORTS_TDM
|
||||
I2S_COMM_MODE_TDM, /*!< I2S controller using TDM communication mode, support up to 16 slots per frame */
|
||||
#endif
|
||||
I2S_COMM_MODE_NONE, /*!< Unspecified I2S controller mode */
|
||||
} i2s_comm_mode_t;
|
||||
|
||||
/**
|
||||
* @brief The multiple of mclk to sample rate
|
||||
*/
|
||||
typedef enum {
|
||||
I2S_MCLK_MULTIPLE_128 = 128, /*!< mclk = sample_rate * 128 */
|
||||
I2S_MCLK_MULTIPLE_256 = 256, /*!< mclk = sample_rate * 256 */
|
||||
I2S_MCLK_MULTIPLE_384 = 384, /*!< mclk = sample_rate * 384 */
|
||||
} i2s_mclk_multiple_t;
|
||||
|
||||
/**
|
||||
* @brief Event structure used in I2S event queue
|
||||
*/
|
||||
typedef struct {
|
||||
void *data; /**< The pointer of DMA buffer that just finished sending or receiving for `on_recv` and `on_sent` callback
|
||||
* NULL for `on_recv_q_ovf` and `on_send_q_ovf` callback
|
||||
*/
|
||||
size_t size; /**< The buffer size of DMA buffer when success to send or receive,
|
||||
* also the buffer size that dropped when queue overflow.
|
||||
* It is related to the dma_frame_num and data_bit_width, typically it is fixed when data_bit_width is not changed.
|
||||
*/
|
||||
} i2s_event_data_t;
|
||||
|
||||
typedef struct i2s_channel_t *i2s_chan_handle_t; /*!< i2s channel handle, the control unit of the i2s driver*/
|
||||
|
||||
/**
|
||||
* @brief I2S event callback
|
||||
* @param[in] handle I2S channel handle, created from `i2s_new_channel()`
|
||||
* @param[in] event I2S event data
|
||||
* @param[in] user_ctx User registered context, passed from `i2s_channel_register_event_callback()`
|
||||
*
|
||||
* @return Whether a high priority task has been waken up by this callback function
|
||||
*/
|
||||
typedef bool (*i2s_isr_callback_t)(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
Reference in New Issue
Block a user