mirror of
https://github.com/espressif/esp-idf
synced 2025-03-09 17:19:09 -04:00
docs(i2s): fix some i2s capabilities in programming guide
This commit is contained in:
laokaiyao
parent
7ff0087d3b
commit
7727de5337
@ -3,7 +3,8 @@ Inter-IC Sound (I2S)
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two"}
|
||||
{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two", esp32p4="three"}
|
||||
{IDF_TARGET_I2S_STD_TDM:default="standard and TDM", esp32="standard", esp32s2="standard"}
|
||||
|
||||
Introduction
|
||||
------------
|
||||
@ -18,7 +19,7 @@ I2S (Inter-IC Sound) is a synchronous serial communication protocol usually used
|
||||
|
||||
{IDF_TARGET_NAME} contains {IDF_TARGET_I2S_NUM} I2S peripheral(s). These peripherals can be configured to input and output sample data via the I2S driver.
|
||||
|
||||
An I2S bus that communicates in standard or TDM mode consists of the following lines:
|
||||
An I2S bus that communicates in {IDF_TARGET_I2S_STD_TDM} mode consists of the following lines:
|
||||
|
||||
- **MCLK:** Master clock line. It is an optional signal depending on the slave side, mainly used for offering a reference clock to the I2S slave device.
|
||||
- **BCLK:** Bit clock line. The bit clock for data line.
|
||||
@ -57,10 +58,12 @@ I2S File Structure
|
||||
|
||||
**Public headers that need to be included in the I2S application are as follows:**
|
||||
|
||||
- ``i2s.h``: The header file that provides legacy I2S APIs (for apps using legacy driver).
|
||||
- ``i2s_std.h``: The header file that provides standard communication mode specific APIs (for apps using new driver with standard mode).
|
||||
- ``i2s_pdm.h``: The header file that provides PDM communication mode specific APIs (for apps using new driver with PDM mode).
|
||||
- ``i2s_tdm.h``: The header file that provides TDM communication mode specific APIs (for apps using new driver with TDM mode).
|
||||
.. list::
|
||||
|
||||
- ``i2s.h``: The header file that provides legacy I2S APIs (for apps using legacy driver).
|
||||
- ``i2s_std.h``: The header file that provides standard communication mode specific APIs (for apps using new driver with standard mode).
|
||||
:SOC_I2S_SUPPORTS_PDM: - ``i2s_pdm.h``: The header file that provides PDM communication mode specific APIs (for apps using new driver with PDM mode).
|
||||
:SOC_I2S_SUPPORTS_TDM: - ``i2s_tdm.h``: The header file that provides TDM communication mode specific APIs (for apps using new driver with TDM mode).
|
||||
|
||||
.. note::
|
||||
|
||||
@ -78,27 +81,14 @@ I2S Clock
|
||||
Clock Source
|
||||
^^^^^^^^^^^^
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default PLL clock.
|
||||
.. list::
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F160M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`: 160 MHz PLL clock.
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F120M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`: 120 MHz PLL clock.
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F96M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`: 96 MHz PLL clock.
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F240M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`: 240 MHz PLL clock.
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_APLL
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`: Audio PLL clock, which is more precise than ``I2S_CLK_SRC_PLL_160M`` in high sample rate applications. Its frequency is configurable according to the sample rate. However, if APLL has been occupied by EMAC or other channels, the APLL frequency cannot be changed, and the driver will try to work under this APLL frequency. If this frequency cannot meet the requirements of I2S, the clock configuration will fail.
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default PLL clock.
|
||||
:SOC_I2S_SUPPORTS_PLL_F160M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`: 160 MHz PLL clock.
|
||||
:SOC_I2S_SUPPORTS_PLL_F120M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`: 120 MHz PLL clock.
|
||||
:SOC_I2S_SUPPORTS_PLL_F96M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`: 96 MHz PLL clock.
|
||||
:SOC_I2S_SUPPORTS_PLL_F240M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`: 240 MHz PLL clock.
|
||||
:SOC_I2S_SUPPORTS_APLL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`: Audio PLL clock, which is more precise than ``I2S_CLK_SRC_PLL_160M`` in high sample rate applications. Its frequency is configurable according to the sample rate. However, if APLL has been occupied by EMAC or other channels, the APLL frequency cannot be changed, and the driver will try to work under this APLL frequency. If this frequency cannot meet the requirements of I2S, the clock configuration will fail.
|
||||
|
||||
Clock Terminology
|
||||
^^^^^^^^^^^^^^^^^
|
||||
@ -131,8 +121,8 @@ ESP32-C6 I2S 0 I2S 0 none I2S 0 I2S 0 none
|
||||
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 I2S 0/1 none none
|
||||
ESP32-H2 I2S 0 I2S 0 none I2S 0 I2S 0 none none
|
||||
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 I2S 0~2 none none
|
||||
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 none none
|
||||
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 none none
|
||||
ESP32-C5 I2S 0 I2S 0 none I2S 0 I2S 0 none none
|
||||
ESP32-C61 I2S 0 I2S 0 none I2S 0 I2S 0 none none
|
||||
========= ======== ============ ============ ========= ======== ======== ==========
|
||||
|
||||
.. note::
|
||||
@ -190,7 +180,6 @@ In standard mode, there are always two sound channels, i.e., the left and right
|
||||
|
||||
As for the slot configuration of raw PDM format, you can use the helper macros like :c:macro:`I2S_PDM_TX_SLOT_RAW_FMT_DEFAULT_CONFIG` or :c:macro:`I2S_PDM_TX_SLOT_RAW_FMT_DAC_DEFAULT_CONFIG`.
|
||||
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PCM2PDM
|
||||
|
||||
PDM TX Mode in PCM Format (with PCM-to-PDM Converter)
|
||||
@ -905,7 +894,7 @@ Here is the table of the data received in the buffer with different :cpp:member:
|
||||
Full-duplex
|
||||
^^^^^^^^^^^
|
||||
|
||||
Full-duplex mode registers TX and RX channel in an I2S port at the same time, and the channels share the BCLK and WS signals. Currently, STD and TDM communication modes supports full-duplex mode in the following way, but PDM full-duplex is not supported because due to different PDM TX and RX clocks.
|
||||
Full-duplex mode registers TX and RX channel in an I2S port at the same time, and the channels share the BCLK and WS signals. Currently, {IDF_TARGET_I2S_STD_TDM} communication modes supports full-duplex mode in the following way, but PDM full-duplex is not supported because due to different PDM TX and RX clocks.
|
||||
|
||||
Note that one handle can only stand for one channel. Therefore, it is still necessary to configure the slot and clock for both TX and RX channels one by one.
|
||||
|
||||
|
||||
@ -3,7 +3,8 @@ I2S
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2"}
|
||||
{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2", esp32p4="3"}
|
||||
{IDF_TARGET_I2S_STD_TDM:default="标准和 TDM", esp32="标准", esp32s2="标准"}
|
||||
|
||||
简介
|
||||
----
|
||||
@ -18,7 +19,7 @@ I2S（Inter-IC Sound，集成电路内置音频总线）是一种同步串行通
|
||||
|
||||
{IDF_TARGET_NAME} 包含 {IDF_TARGET_I2S_NUM} 个 I2S 外设。通过配置这些外设，可以借助 I2S 驱动来输入和输出采样数据。
|
||||
|
||||
标准或 TDM 通信模式下的 I2S 总线包含以下几条线路：
|
||||
{IDF_TARGET_I2S_STD_TDM} 模式下的 I2S 总线包含以下几条线路：
|
||||
|
||||
- **MCLK**：主时钟线。该信号线可选，具体取决于从机，主要用于向 I2S 从机提供参考时钟。
|
||||
- **BCLK**：位时钟线。用于数据线的位时钟。
|
||||
@ -57,10 +58,12 @@ I2S 文件结构
|
||||
|
||||
**需要包含在 I2S 应用中的公共头文件如下所示：**
|
||||
|
||||
- ``i2s.h``：提供原有 I2S API（用于使用原有驱动的应用）。
|
||||
- ``i2s_std.h``：提供标准通信模式的 API（用于使用标准模式的新驱动程序的应用）。
|
||||
- ``i2s_pdm.h``：提供 PDM 通信模式的 API（用于使用 PDM 模式的新驱动程序的应用）。
|
||||
- ``i2s_tdm.h``：提供 TDM 通信模式的 API（用于使用 TDM 模式的新驱动的应用）。
|
||||
.. list::
|
||||
|
||||
- ``i2s.h``：提供原有 I2S API（用于使用原有驱动的应用）。
|
||||
- ``i2s_std.h``：提供标准通信模式的 API（用于使用标准模式的新驱动程序的应用）。
|
||||
:SOC_I2S_SUPPORTS_PDM: - ``i2s_pdm.h``：提供 PDM 通信模式的 API（用于使用 PDM 模式的新驱动程序的应用）。
|
||||
:SOC_I2S_SUPPORTS_TDM: - ``i2s_tdm.h``：提供 TDM 通信模式的 API（用于使用 TDM 模式的新驱动的应用）。
|
||||
|
||||
.. note::
|
||||
|
||||
@ -78,27 +81,14 @@ I2S 时钟
|
||||
时钟源
|
||||
^^^^^^
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认 PLL 时钟。
|
||||
.. list::
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F160M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`：160 MHz PLL 时钟。
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F120M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`：120 MHz PLL 时钟。
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F96M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`：96 MHz PLL 时钟。
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PLL_F240M
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`：240 MHz PLL 时钟。
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_APLL
|
||||
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`：音频 PLL 时钟，在高采样率应用中比 ``I2S_CLK_SRC_PLL_160M`` 更精确。其频率可根据采样率进行配置，但如果 APLL 已经被 EMAC 或其他通道占用，则无法更改 APLL 频率，驱动程序将尝试在原有 APLL 频率下工作。如果原有 APLL 频率无法满足 I2S 的需求，时钟配置将失败。
|
||||
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认 PLL 时钟。
|
||||
:SOC_I2S_SUPPORTS_PLL_F160M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`：160 MHz PLL 时钟。
|
||||
:SOC_I2S_SUPPORTS_PLL_F120M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`：120 MHz PLL 时钟。
|
||||
:SOC_I2S_SUPPORTS_PLL_F96M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`：96 MHz PLL 时钟。
|
||||
:SOC_I2S_SUPPORTS_PLL_F240M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`：240 MHz PLL 时钟。
|
||||
:SOC_I2S_SUPPORTS_APLL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`：音频 PLL 时钟，在高采样率应用中比 ``I2S_CLK_SRC_PLL_160M`` 更精确。其频率可根据采样率进行配置，但如果 APLL 已经被 EMAC 或其他通道占用，则无法更改 APLL 频率，驱动程序将尝试在原有 APLL 频率下工作。如果原有 APLL 频率无法满足 I2S 的需求，时钟配置将失败。
|
||||
|
||||
时钟术语
|
||||
^^^^^^^^
|
||||
@ -131,8 +121,8 @@ ESP32-C6 I2S 0 I2S 0 无 I2S 0 I2S 0 无
|
||||
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 I2S 0/1 无 无
|
||||
ESP32-H2 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
|
||||
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 I2S 0~2 无 无
|
||||
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无 无
|
||||
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无 无
|
||||
ESP32-C5 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
|
||||
ESP32-C61 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
|
||||
========= ======== ========== ========== =========== ========== ======== ===========
|
||||
|
||||
.. note::
|
||||
@ -157,7 +147,6 @@ ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无
|
||||
.. wavedrom:: /../_static/diagrams/i2s/std_pcm.json
|
||||
|
||||
|
||||
|
||||
.. only:: SOC_I2S_SUPPORTS_PDM
|
||||
|
||||
PDM 模式
|
||||
@ -905,7 +894,7 @@ STD RX 模式
|
||||
全双工
|
||||
^^^^^^
|
||||
|
||||
全双工模式可以在 I2S 端口中同时注册 TX 和 RX 通道，同时通道共享 BCLK 和 WS 信号。目前，STD 和 TDM 通信模式支持以下方式的全双工通信，但不支持 PDM 全双工模式，因为 PDM 模式下 TX 和 RX 通道的时钟不同。
|
||||
全双工模式可以在 I2S 端口中同时注册 TX 和 RX 通道，同时通道共享 BCLK 和 WS 信号。目前，{IDF_TARGET_I2S_STD_TDM} 通信模式支持以下方式的全双工通信，但不支持 PDM 全双工模式，因为 PDM 模式下 TX 和 RX 通道的时钟不同。
|
||||
|
||||
请注意，一个句柄只能代表一个通道，因此仍然需要对 TX 和 RX 通道逐个进行声道和时钟配置。
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user