Documentation: Document I2S support on ESP32-S3-DevKitC-1 board

Add documentation about the I2S peripheral support on ESP32-S3. The
I2S/audio support is demonstrated on the ESP32-S3-DevKitC-1 board.

Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst

@@ -47,6 +47,21 @@ Board LEDs
 There are several on-board LEDs for that indicate the presence of power
 and USB activity.  None of these are available for use by software.
 
+I2S
+===
+
+ESP32-S3 has two I2S peripherals accessible using either the generic I2S audio
+driver or a specific audio codec driver
+(`CS4344 <https://www.cirrus.com/products/cs4344-45-48/>`__ bindings are
+available at the moment). The generic I2S audio driver enables the use of both
+the receiver module (RX) and the transmitter module (TX) without using any
+specific codec. Also, it's possible to use the I2S character device driver
+to bypass the audio subsystem and write directly to the I2S peripheral.
+
+The following configurations use the I2S peripheral::
+  * :ref:`platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:audio`
+  * :ref:`platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:nxlooper`
+
 Configurations
 ==============
 
@@ -58,6 +73,56 @@ All of the configurations presented below can be tested by running the following
 Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
 Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
+audio
+-----
+
+This configuration uses the I2S0 peripheral and an externally connected audio
+codec to play an audio file streamed over an HTTP connection while connected
+to a Wi-Fi network.
+
+**Audio Codec Setup**
+
+The CS4344 audio codec is connected to the following pins:
+
+============ ========== ============================================
+ESP32-S3 Pin CS4344 Pin Description
+============ ========== ============================================
+5            MCLK       Master Clock
+16           SCLK       Serial Clock
+7            LRCK       Left Right Clock (Word Select)
+6            SDIN       Serial Data In on CS4344. (DOUT on ESP32-S3)
+============ ========== ============================================
+
+**Simple HTTP server**
+
+Prepare a PCM-encoded (`.wav`) audio file with 16 or 24 bits/sample (sampled at
+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
+PC and run::
+
+    $ python3 -m http.server
+    Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)
+
+Look for your PC IP address and test playing the prepared audio on your
+browser:
+
+.. figure:: esp32-audio-config-file.png
+          :align: center
+
+After successfully built and flashed, connect the board to the Wi-Fi network::
+
+    nsh> wapi psk wlan0 mypasswd 3
+    nsh> wapi essid wlan0 myssid 1
+    nsh> renew wlan0
+
+Once connected, open NuttX's player and play the file according to the filename
+and the IP address of the HTTP server::
+
+    nsh> nxplayer
+    nxplayer> play http://192.168.1.239:8000/tones.wav
+
 buttons
 -------
 
@@ -149,6 +214,64 @@ nsh
 Basic NuttShell configuration (console enabled in UART0, exposed via
 USB connection by means of CP2102 converter, at 115200 bps).
 
+nxlooper
+--------
+
+This configuration uses the I2S1 peripheral as an I2S receiver and the I2S0
+peripheral as an I2S transmitter. The idea is to capture an I2S data frame
+using an I2S peripheral and reproduce the captured data on the other.
+
+**Receiving data on I2S1**
+
+The I2S1 will act as a receiver (in slave mode, i.e., waiting for the BCLK
+and WS signals from the transmitter), capturing data from DIN, which
+needs to be connected to an external source as follows:
+
+============ ========== =========================================
+ESP32-S3 Pin Signal Pin Description
+============ ========== =========================================
+18           BCLK       Bit Clock (SCLK)
+17           WS         Word Select (LRCLK)
+15           DIN        Data IN
+============ ========== =========================================
+
+**Transmitting data on I2S0**
+
+The I2S0 will act as a transmitter (in master mode, i.e., providing the
+BCLK and WS signals), replicating the data captured on I2S1.
+The pinout for the transmitter is as follows:
+
+========== ========== =========================================
+ESP32 Pin  Signal Pin Description
+========== ========== =========================================
+5          MCLK       Master Clock
+16         BCLK       Bit Clock (SCLK)
+7          WS         Word Select (LRCLK)
+6          DOUT       Data Out
+========== ========== =========================================
+
+.. note:: The audio codec CS4344 can be connected to the transmitter pins
+  to reproduce the captured data if the receiver's source is a PCM-encoded
+  audio data.
+
+**nxlooper**
+
+The ``nxlooper`` application captures data from the audio device with input
+capabilities (the I2S1 in this example) and forwards the audio data frame to
+the audio device with output capabilities (the I2S0 in this example).
+
+After successfully built and flashed, run on the boards' terminal::
+
+  nsh> nxlooper
+  nxlooper> loopback
+
+.. note:: ``loopback`` command default arguments for the channel configuration,
+  data width and sample rate are, respectively, 2 channels,
+  16 bits/sample and 48KHz. These arguments can be supplied to select
+  different audio formats, for instance::
+
+    nxlooper> loopback 2 16 44100
+
 oneshot
 -------
 

Documentation/platforms/xtensa/esp32s3/index.rst

@@ -98,7 +98,7 @@ DMA          Yes
 eFuse        No
 GPIO         Yes
 I2C          No
-I2S          No
+I2S          Yes
 LCD          No
 LED_PWM      No
 MCPWM        No