documentation: update esp32[-s2] documentation about I2S/audio support

Documentation/introduction/detailed_support.rst

@@ -3052,10 +3052,10 @@ Please, refer to the :doc:`ESP32 </platforms/xtensa/esp32/index>` on NuttX for
 further information.
 
 ESP32-S2 (Single Xtensa LX7)
-=======================
+============================
 
 Xtensa LX7 ESP32-S2
-----------------
+-------------------
 
 Initial architectural support for Xtensa LX7 processor for the Espressif
 ESP32-S2 was added in NuttX-10.2.
@@ -3067,10 +3067,10 @@ Please, refer to the :doc:`ESP32-S2 </platforms/xtensa/esp32s2/index>` on NuttX
 further information.
 
 ESP32-S3 (Dual Xtensa LX7)
-=======================
+==========================
 
 Xtensa LX7 ESP32-S3
-----------------
+-------------------
 
 Initial architectural support for dual Xtensa LX7 processors for the Espressif
 ESP32-S3 was added in NuttX-10.3.

Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst

@@ -115,16 +115,13 @@ driver to bypass audio systems and write directly to the I2S peripheral.
 
 .. note:: The I2S peripheral is able to work on two functional modes
   internally: 16 and 32-bit width.
-  That limits using the I2S peripheral to play audio files other than 16/32
+  ESP32's I2S driver, however, uses an internal buffer to enable inserting
-  bit-widths as the internal buffer allocated for the audio content does not
+  padding bytes and provide the ability to play 8, 16, 24 or 32-bits/sample
-  consider the operation modes of the peripheral. This limitation is planned
+  audio files. Sample rate and data width are automatically set by the upper
-  to be removed soon by copying the buffers internally and making the
+  half audio driver.
-  necessary adjustments.
 
-.. note:: The above statement is not valid when using the I2S character
+.. note:: Also, it's possible to use 8, 16, 24, and 32-bit-widths writing
-  device driver.
+  directly to the I2S character device. Just make sure to set the bit-width::
-  It's possible to use 8, 16, 24, and 32-bit-widths writing directly to the
-  I2S character device. Just make sure to set the bit-width::
 
     $ make menuconfig
     -> System Type
@@ -173,8 +170,8 @@ ESP32 Pin  CS4344 Pin Description
 
 **Simple HTTP server**
 
-Prepare a PCM-encoded (`.wav`) audio file with 16 bits/sample (sampled at
+Prepare a PCM-encoded (`.wav`) audio file with 16 or 24 bits/sample (sampled at
-8~48kHz). This file must be placed into a folder in a computer that could
+16~48kHz). This file must be placed into a folder in a computer that could
 be accessed on the same Wi-Fi network the ESP32 will be connecting to.
 
 Python provides a simple HTTP server. `cd` to the audio file folder on the

Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst

@@ -66,13 +66,8 @@ driver or a specific audio codec driver
 available at the moment). Also, it's possible to use the I2S character device
 driver to bypass audio systems and write directly to the I2S peripheral.
 
-.. note:: The I2S peripheral is able to work on two functional modes
+.. note:: When using the audio system, sample rate and data width are
-  internally: 16 and 32-bit width.
+  automatically set by the upper half audio driver.
-  That limits using the I2S peripheral to play audio files other than 16/32
-  bit-widths as the internal buffer allocated for the audio content does not
-  consider the operation modes of the peripheral. This limitation is planned
-  to be removed soon by copying the buffers internally and making the
-  necessary adjustments.
 
 .. note:: The above statement is not valid when using the I2S character
   device driver.
@@ -86,9 +81,6 @@ driver to bypass audio systems and write directly to the I2S peripheral.
                 -> I2S0/1
                     -> Bit Witdh
 
-  And make sure the data stream buffer being written to the I2S peripheral is
-  aligned to the next boundary i.e. 16 bits for the 8 and 16-bit-widths and
-  32 bits for 24 and 32-bit-widths.
 
 Configurations
 ==============
@@ -99,7 +91,7 @@ audio
 This configuration uses the I2S0 peripheral and an externally connected audio
 codec to play an audio file. The easiest way of playing an uncompressed file
 is embedding into the firmware. This configuration selects
-`romfs example <https://github.com/apache/incubator-nuttx-apps/tree/master/examples/romfs>`_`
+`romfs example <https://github.com/apache/incubator-nuttx-apps/tree/master/examples/romfs>`__
 to allow that.
 
 **Audio Codec Setup**
@@ -122,7 +114,7 @@ Prepare and build the `audio` defconfig::
   $ make -j distclean && ./tools/configure.sh esp32s2-saola-1:audio && make
 
 This will create a temporary folder in `apps/examples/romfs/testdir`. Move
-a PCM-encoded (`.wav`) audio file with 16 bits/sample (sampled at 8~48kHz)
+a PCM-encoded (`.wav`) audio file with 16 or 24 bits/sample (sampled at 16~48kHz)
 to this folder.
 
 .. note:: You can use :download:`this 440 Hz sinusoidal tone <tone.wav>`.