Skip to content

Commit 7727de5

Browse files
L-KAYAL-KAYA
committed
docs(i2s): fix some i2s capabilities in programming guide
1 parent 7ff0087 commit 7727de5

File tree

2 files changed

+38
-60
lines changed
  • docs
    • en/api-reference/peripherals
    • zh_CN/api-reference/peripherals

2 files changed

+38
-60
lines changed

‎docs/en/api-reference/peripherals/i2s.rst‎

Lines changed: 19 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ Inter-IC Sound (I2S)
33

44
:link_to_translation:`zh_CN:[中文]`
55

6-
{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two"}
6+
{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two", esp32p4="three"}
7+
{IDF_TARGET_I2S_STD_TDM:default="standard and TDM", esp32="standard", esp32s2="standard"}
78

89
Introduction
910
------------
@@ -18,7 +19,7 @@ I2S (Inter-IC Sound) is a synchronous serial communication protocol usually used
1819

1920
{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.
2021

21-
An I2S bus that communicates in standard or TDM mode consists of the following lines:
22+
An I2S bus that communicates in {IDF_TARGET_I2S_STD_TDM} mode consists of the following lines:
2223

2324
- **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.
2425
- **BCLK:** Bit clock line. The bit clock for data line.
@@ -57,10 +58,12 @@ I2S File Structure
5758

5859
**Public headers that need to be included in the I2S application are as follows:**
5960

60-
- ``i2s.h``: The header file that provides legacy I2S APIs (for apps using legacy driver).
61-
- ``i2s_std.h``: The header file that provides standard communication mode specific APIs (for apps using new driver with standard mode).
62-
- ``i2s_pdm.h``: The header file that provides PDM communication mode specific APIs (for apps using new driver with PDM mode).
63-
- ``i2s_tdm.h``: The header file that provides TDM communication mode specific APIs (for apps using new driver with TDM mode).
61+
.. list::
62+
63+
- ``i2s.h``: The header file that provides legacy I2S APIs (for apps using legacy driver).
64+
- ``i2s_std.h``: The header file that provides standard communication mode specific APIs (for apps using new driver with standard mode).
65+
: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).
66+
: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).
6467

6568
.. note::
6669

@@ -78,27 +81,14 @@ I2S Clock
7881
Clock Source
7982
^^^^^^^^^^^^
8083

81-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default PLL clock.
82-
83-
.. only:: SOC_I2S_SUPPORTS_PLL_F160M
84-
85-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`: 160 MHz PLL clock.
86-
87-
.. only:: SOC_I2S_SUPPORTS_PLL_F120M
88-
89-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`: 120 MHz PLL clock.
90-
91-
.. only:: SOC_I2S_SUPPORTS_PLL_F96M
84+
.. list::
9285

93-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`: 96 MHz PLL clock.
94-
95-
.. only:: SOC_I2S_SUPPORTS_PLL_F240M
96-
97-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`: 240 MHz PLL clock.
98-
99-
.. only:: SOC_I2S_SUPPORTS_APLL
100-
101-
- :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.
86+
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default PLL clock.
87+
:SOC_I2S_SUPPORTS_PLL_F160M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`: 160 MHz PLL clock.
88+
:SOC_I2S_SUPPORTS_PLL_F120M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`: 120 MHz PLL clock.
89+
:SOC_I2S_SUPPORTS_PLL_F96M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`: 96 MHz PLL clock.
90+
:SOC_I2S_SUPPORTS_PLL_F240M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`: 240 MHz PLL clock.
91+
: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.
10292

10393
Clock Terminology
10494
^^^^^^^^^^^^^^^^^
@@ -131,8 +121,8 @@ ESP32-C6 I2S 0 I2S 0 none I2S 0 I2S 0 none
131121
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 I2S 0/1 none none
132122
ESP32-H2 I2S 0 I2S 0 none I2S 0 I2S 0 none none
133123
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 I2S 0~2 none none
134-
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 none none
135-
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 none none
124+
ESP32-C5 I2S 0 I2S 0 none I2S 0 I2S 0 none none
125+
ESP32-C61 I2S 0 I2S 0 none I2S 0 I2S 0 none none
136126
========= ======== ============ ============ ========= ======== ======== ==========
137127

138128
.. note::
@@ -190,7 +180,6 @@ In standard mode, there are always two sound channels, i.e., the left and right
190180

191181
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`.
192182

193-
194183
.. only:: SOC_I2S_SUPPORTS_PCM2PDM
195184

196185
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:
905894
Full-duplex
906895
^^^^^^^^^^^
907896

908-
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.
897+
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.
909898

910899
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.
911900

‎docs/zh_CN/api-reference/peripherals/i2s.rst‎

Lines changed: 19 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ I2S
33

44
:link_to_translation:`en:[English]`
55

6-
{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2"}
6+
{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2", esp32p4="3"}
7+
{IDF_TARGET_I2S_STD_TDM:default="标准和 TDM", esp32="标准", esp32s2="标准"}
78

89
简介
910
----
@@ -18,7 +19,7 @@ I2S（Inter-IC Sound，集成电路内置音频总线）是一种同步串行通
1819

1920
{IDF_TARGET_NAME} 包含 {IDF_TARGET_I2S_NUM} 个 I2S 外设。通过配置这些外设，可以借助 I2S 驱动来输入和输出采样数据。
2021

21-
标准或 TDM 通信模式下的 I2S 总线包含以下几条线路：
22+
{IDF_TARGET_I2S_STD_TDM} 模式下的 I2S 总线包含以下几条线路：
2223

2324
- **MCLK**：主时钟线。该信号线可选，具体取决于从机，主要用于向 I2S 从机提供参考时钟。
2425
- **BCLK**：位时钟线。用于数据线的位时钟。
@@ -57,10 +58,12 @@ I2S 文件结构
5758

5859
**需要包含在 I2S 应用中的公共头文件如下所示：**
5960

60-
- ``i2s.h``：提供原有 I2S API（用于使用原有驱动的应用）。
61-
- ``i2s_std.h``：提供标准通信模式的 API（用于使用标准模式的新驱动程序的应用）。
62-
- ``i2s_pdm.h``：提供 PDM 通信模式的 API（用于使用 PDM 模式的新驱动程序的应用）。
63-
- ``i2s_tdm.h``：提供 TDM 通信模式的 API（用于使用 TDM 模式的新驱动的应用）。
61+
.. list::
62+
63+
- ``i2s.h``：提供原有 I2S API（用于使用原有驱动的应用）。
64+
- ``i2s_std.h``：提供标准通信模式的 API（用于使用标准模式的新驱动程序的应用）。
65+
:SOC_I2S_SUPPORTS_PDM: - ``i2s_pdm.h``：提供 PDM 通信模式的 API（用于使用 PDM 模式的新驱动程序的应用）。
66+
:SOC_I2S_SUPPORTS_TDM: - ``i2s_tdm.h``：提供 TDM 通信模式的 API（用于使用 TDM 模式的新驱动的应用）。
6467

6568
.. note::
6669

@@ -78,27 +81,14 @@ I2S 时钟
7881
时钟源
7982
^^^^^^
8083

81-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认 PLL 时钟。
82-
83-
.. only:: SOC_I2S_SUPPORTS_PLL_F160M
84-
85-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`：160 MHz PLL 时钟。
86-
87-
.. only:: SOC_I2S_SUPPORTS_PLL_F120M
88-
89-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`：120 MHz PLL 时钟。
90-
91-
.. only:: SOC_I2S_SUPPORTS_PLL_F96M
84+
.. list::
9285

93-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`：96 MHz PLL 时钟。
94-
95-
.. only:: SOC_I2S_SUPPORTS_PLL_F240M
96-
97-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`：240 MHz PLL 时钟。
98-
99-
.. only:: SOC_I2S_SUPPORTS_APLL
100-
101-
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`：音频 PLL 时钟，在高采样率应用中比 ``I2S_CLK_SRC_PLL_160M`` 更精确。其频率可根据采样率进行配置，但如果 APLL 已经被 EMAC 或其他通道占用，则无法更改 APLL 频率，驱动程序将尝试在原有 APLL 频率下工作。如果原有 APLL 频率无法满足 I2S 的需求，时钟配置将失败。
86+
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认 PLL 时钟。
87+
:SOC_I2S_SUPPORTS_PLL_F160M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`：160 MHz PLL 时钟。
88+
:SOC_I2S_SUPPORTS_PLL_F120M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`：120 MHz PLL 时钟。
89+
:SOC_I2S_SUPPORTS_PLL_F96M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`：96 MHz PLL 时钟。
90+
:SOC_I2S_SUPPORTS_PLL_F240M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`：240 MHz PLL 时钟。
91+
: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 的需求，时钟配置将失败。
10292

10393
时钟术语
10494
^^^^^^^^
@@ -131,8 +121,8 @@ ESP32-C6 I2S 0 I2S 0 无 I2S 0 I2S 0 无
131121
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 I2S 0/1 无 无
132122
ESP32-H2 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
133123
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 I2S 0~2 无 无
134-
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无 无
135-
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无 无
124+
ESP32-C5 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
125+
ESP32-C61 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
136126
========= ======== ========== ========== =========== ========== ======== ===========
137127

138128
.. note::
@@ -157,7 +147,6 @@ ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无
157147
.. wavedrom:: /../_static/diagrams/i2s/std_pcm.json
158148

159149

160-
161150
.. only:: SOC_I2S_SUPPORTS_PDM
162151

163152
PDM 模式
@@ -905,7 +894,7 @@ STD RX 模式
905894
全双工
906895
^^^^^^
907896

908-
全双工模式可以在 I2S 端口中同时注册 TX 和 RX 通道，同时通道共享 BCLK 和 WS 信号。目前，STD 和 TDM 通信模式支持以下方式的全双工通信，但不支持 PDM 全双工模式，因为 PDM 模式下 TX 和 RX 通道的时钟不同。
897+
全双工模式可以在 I2S 端口中同时注册 TX 和 RX 通道，同时通道共享 BCLK 和 WS 信号。目前，{IDF_TARGET_I2S_STD_TDM} 通信模式支持以下方式的全双工通信，但不支持 PDM 全双工模式，因为 PDM 模式下 TX 和 RX 通道的时钟不同。
909898

910899
请注意，一个句柄只能代表一个通道，因此仍然需要对 TX 和 RX 通道逐个进行声道和时钟配置。
911900

0 commit comments

Comments
 (0)