From e83fc30b6790eabcbc693e206428c324b870fa37 Mon Sep 17 00:00:00 2001 From: Armando Date: Fri, 8 Nov 2024 12:24:52 +0800 Subject: [PATCH 1/6] fix(lp_i2s): added cbs iram check --- components/esp_driver_i2s/lp_i2s.c | 8 ++++++++ .../esp_driver_i2s/test_apps/lp_i2s/main/test_lp_i2s.c | 4 ++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/components/esp_driver_i2s/lp_i2s.c b/components/esp_driver_i2s/lp_i2s.c index 0d5e43dd8d..5b5f8b7393 100644 --- a/components/esp_driver_i2s/lp_i2s.c +++ b/components/esp_driver_i2s/lp_i2s.c @@ -18,6 +18,7 @@ #include "freertos/FreeRTOS.h" #include "freertos/semphr.h" #include "esp_clk_tree.h" +#include "esp_memory_utils.h" #include "hal/hal_utils.h" #include "hal/lp_i2s_hal.h" #include "hal/lp_i2s_ll.h" @@ -250,6 +251,13 @@ esp_err_t lp_i2s_register_event_callbacks(lp_i2s_chan_handle_t handle, const lp_ ESP_RETURN_ON_FALSE(handle && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); ESP_RETURN_ON_FALSE(handle->state < I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel is in enabled state already"); + if (cbs->on_thresh_met) { + ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_thresh_met), ESP_ERR_INVALID_ARG, TAG, "on_thresh_met callback not in IRAM"); + } + if (cbs->on_request_new_trans) { + ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_request_new_trans), ESP_ERR_INVALID_ARG, TAG, "on_request_new_trans callback not in IRAM"); + } + handle->cbs.on_thresh_met = cbs->on_thresh_met; handle->cbs.on_request_new_trans = cbs->on_request_new_trans; handle->user_data = user_data; diff --git a/components/esp_driver_i2s/test_apps/lp_i2s/main/test_lp_i2s.c b/components/esp_driver_i2s/test_apps/lp_i2s/main/test_lp_i2s.c index 8d87f12f78..4e399a9efd 100644 --- a/components/esp_driver_i2s/test_apps/lp_i2s/main/test_lp_i2s.c +++ b/components/esp_driver_i2s/test_apps/lp_i2s/main/test_lp_i2s.c @@ -222,7 +222,7 @@ TEST_CASE("test LP I2S read for STD", "[lp_i2s]") } } -static bool s_lp_i2s_on_thresh_met(lp_i2s_chan_handle_t handle, lp_i2s_evt_data_t *edata, void *user_data) +static bool IRAM_ATTR s_lp_i2s_on_thresh_met(lp_i2s_chan_handle_t handle, lp_i2s_evt_data_t *edata, void *user_data) { ESP_DRAM_LOGD(TAG, "edata->trans.received_size: %d", edata->trans.received_size); s_data_check(edata->trans.buffer, edata->trans.received_size); @@ -230,7 +230,7 @@ static bool s_lp_i2s_on_thresh_met(lp_i2s_chan_handle_t handle, lp_i2s_evt_data_ return false; } -static bool s_lp_i2s_on_request_new_trans(lp_i2s_chan_handle_t handle, lp_i2s_evt_data_t *edata, void *user_data) +static bool IRAM_ATTR s_lp_i2s_on_request_new_trans(lp_i2s_chan_handle_t handle, lp_i2s_evt_data_t *edata, void *user_data) { lp_i2s_trans_t trans = *(lp_i2s_trans_t *)user_data; edata->trans.buffer = trans.buffer; From e4a924351784374554afae4c516a52897c0e5b83 Mon Sep 17 00:00:00 2001 From: Armando Date: Fri, 8 Nov 2024 12:25:50 +0800 Subject: [PATCH 2/6] doc(lp_i2s): lp i2s programming guide --- .../esp_driver_i2s/include/driver/lp_i2s.h | 16 +- components/esp_driver_i2s/lp_i2s.c | 12 +- docs/doxygen/Doxyfile | 3 + docs/en/api-reference/peripherals/i2s.rst | 6 + docs/en/api-reference/peripherals/index.rst | 1 + docs/en/api-reference/peripherals/lp_i2s.rst | 147 ++++++++++++++++++ 6 files changed, 171 insertions(+), 14 deletions(-) create mode 100644 docs/en/api-reference/peripherals/lp_i2s.rst diff --git a/components/esp_driver_i2s/include/driver/lp_i2s.h b/components/esp_driver_i2s/include/driver/lp_i2s.h index 09db9c057e..49cf3272e0 100644 --- a/components/esp_driver_i2s/include/driver/lp_i2s.h +++ b/components/esp_driver_i2s/include/driver/lp_i2s.h @@ -55,7 +55,7 @@ esp_err_t lp_i2s_new_channel(const lp_i2s_chan_config_t *chan_cfg, lp_i2s_chan_h /** * @brief Register LP I2S event callbacks * - * @param[in] handle LP I2S channel handle + * @param[in] chan LP I2S channel handle * @param[in] cbs Callbacks * @param[in] user_data User data * @@ -64,12 +64,12 @@ esp_err_t lp_i2s_new_channel(const lp_i2s_chan_config_t *chan_cfg, lp_i2s_chan_h * - ESP_ERR_INVALID_ARG: Invalid argument * - ESP_ERR_INVALID_STATE: Invalid state */ -esp_err_t lp_i2s_register_event_callbacks(lp_i2s_chan_handle_t handle, const lp_i2s_evt_cbs_t *cbs, void *user_data); +esp_err_t lp_i2s_register_event_callbacks(lp_i2s_chan_handle_t chan, const lp_i2s_evt_cbs_t *cbs, void *user_data); /** * @brief Enable LP I2S driver * - * @param[in] handle LP I2S channel handle + * @param[in] chan LP I2S channel handle * * @return * - ESP_OK: On success @@ -81,7 +81,7 @@ esp_err_t lp_i2s_channel_enable(lp_i2s_chan_handle_t chan); /** * @brief Read LP I2S received data * - * @param[in] handle LP I2S channel handle + * @param[in] chan LP I2S channel handle * @param[in] trans LP I2S transaction * @param[in] timeout_ms Timeout in ms, set to `LP_I2S_MAX_DELAY` to wait until read is done * @@ -95,7 +95,7 @@ esp_err_t lp_i2s_channel_read(lp_i2s_chan_handle_t chan, lp_i2s_trans_t *trans, /** * @brief Read LP I2S received data until certain bytes * - * @param[in] handle LP I2S channel handle + * @param[in] chan LP I2S channel handle * @param[in] trans LP I2S transaction * * @return @@ -108,7 +108,7 @@ esp_err_t lp_i2s_channel_read_until_bytes(lp_i2s_chan_handle_t chan, lp_i2s_tran /** * @brief Disable LP I2S driver * - * @param[in] handle LP I2S channel handle + * @param[in] chan LP I2S channel handle * * @return * - ESP_OK: On success @@ -120,13 +120,13 @@ esp_err_t lp_i2s_channel_disable(lp_i2s_chan_handle_t chan); /** * @brief Delete the LP I2S channel * - * @param[in] handle LP I2S channel handler + * @param[in] chan LP I2S channel handler * * @return * - ESP_OK Delete successfully * - ESP_ERR_INVALID_ARG NULL pointer */ -esp_err_t lp_i2s_del_channel(lp_i2s_chan_handle_t handle); +esp_err_t lp_i2s_del_channel(lp_i2s_chan_handle_t chan); #ifdef __cplusplus } diff --git a/components/esp_driver_i2s/lp_i2s.c b/components/esp_driver_i2s/lp_i2s.c index 5b5f8b7393..707e5c12c7 100644 --- a/components/esp_driver_i2s/lp_i2s.c +++ b/components/esp_driver_i2s/lp_i2s.c @@ -246,10 +246,10 @@ esp_err_t lp_i2s_del_channel(lp_i2s_chan_handle_t chan) _Static_assert(sizeof(lp_i2s_evt_cbs_t) == sizeof(lp_i2s_evt_cbs_internal_t), "Invalid size of lp_i2s_evt_cbs_t structure"); #endif -esp_err_t lp_i2s_register_event_callbacks(lp_i2s_chan_handle_t handle, const lp_i2s_evt_cbs_t *cbs, void *user_data) +esp_err_t lp_i2s_register_event_callbacks(lp_i2s_chan_handle_t chan, const lp_i2s_evt_cbs_t *cbs, void *user_data) { - ESP_RETURN_ON_FALSE(handle && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); - ESP_RETURN_ON_FALSE(handle->state < I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel is in enabled state already"); + ESP_RETURN_ON_FALSE(chan && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); + ESP_RETURN_ON_FALSE(chan->state < I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel is in enabled state already"); if (cbs->on_thresh_met) { ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_thresh_met), ESP_ERR_INVALID_ARG, TAG, "on_thresh_met callback not in IRAM"); @@ -258,9 +258,9 @@ esp_err_t lp_i2s_register_event_callbacks(lp_i2s_chan_handle_t handle, const lp_ ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_request_new_trans), ESP_ERR_INVALID_ARG, TAG, "on_request_new_trans callback not in IRAM"); } - handle->cbs.on_thresh_met = cbs->on_thresh_met; - handle->cbs.on_request_new_trans = cbs->on_request_new_trans; - handle->user_data = user_data; + chan->cbs.on_thresh_met = cbs->on_thresh_met; + chan->cbs.on_request_new_trans = cbs->on_request_new_trans; + chan->user_data = user_data; return ESP_OK; } diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 8a3c7d78c2..f2cc320d35 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -125,6 +125,9 @@ INPUT = \ $(PROJECT_PATH)/components/esp_driver_i2s/include/driver/i2s_pdm.h \ $(PROJECT_PATH)/components/esp_driver_i2s/include/driver/i2s_std.h \ $(PROJECT_PATH)/components/esp_driver_i2s/include/driver/i2s_tdm.h \ + $(PROJECT_PATH)/components/esp_driver_i2s/include/driver/lp_i2s.h \ + $(PROJECT_PATH)/components/esp_driver_i2s/include/driver/lp_i2s_std.h \ + $(PROJECT_PATH)/components/esp_driver_i2s/include/driver/lp_i2s_pdm.h \ $(PROJECT_PATH)/components/esp_driver_i2s/include/driver/i2s_types.h \ $(PROJECT_PATH)/components/esp_driver_pcnt/include/driver/pulse_cnt.h \ $(PROJECT_PATH)/components/esp_driver_rmt/include/driver/rmt_common.h \ diff --git a/docs/en/api-reference/peripherals/i2s.rst b/docs/en/api-reference/peripherals/i2s.rst index 8169e6d551..47a8e73756 100644 --- a/docs/en/api-reference/peripherals/i2s.rst +++ b/docs/en/api-reference/peripherals/i2s.rst @@ -10,6 +10,12 @@ Introduction I2S (Inter-IC Sound) is a synchronous serial communication protocol usually used for transmitting audio data between two digital audio devices. +.. only:: SOC_LP_I2S_SUPPORTED + + .. note:: + + For LP I2S documentation, see :doc:`Low Power Inter-IC Sound <./lp_i2s>`. + {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: diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 3a959b7249..ce256d9c76 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -41,6 +41,7 @@ Peripherals API :SOC_GPSPI_SUPPORTED: spi_master :SOC_GPSPI_SUPPORTED: spi_slave :SOC_SPI_SUPPORT_SLAVE_HD_VER2: spi_slave_hd + :SOC_LP_I2S_SUPPORTED: lp_i2s :SOC_TEMP_SENSOR_SUPPORTED: temp_sensor :SOC_TOUCH_SENSOR_SUPPORTED and not esp32p4: touch_pad :esp32p4: cap_touch_sens diff --git a/docs/en/api-reference/peripherals/lp_i2s.rst b/docs/en/api-reference/peripherals/lp_i2s.rst new file mode 100644 index 0000000000..04cd3c9c09 --- /dev/null +++ b/docs/en/api-reference/peripherals/lp_i2s.rst @@ -0,0 +1,147 @@ +Low Power Inter-IC Sound (LP I2S) +================================= + + +Introduction +------------ + +LP I2S (Low Power Inter-IC Sound) is a synchronous protocol which can be used for audio data transmission. It also provides a data reception communication interface for Voice Activity Detection (VAD) and some digital audio applications in low power mode. For more details about VAD, see :doc:`Voice Activity Detection <./vad>`. + +.. only:: SOC_I2S_SUPPORTED + + .. note:: + + For I2S documentation, see :doc:`Inter-IC Sound <./i2s>`. + +The I2S standard bus defines three signals, +- BCK: bit clock +- WS: word select +- SD: serial data + +A basic I2S data bus has one master and one slave. The roles remain unchanged throughout the communication. + +.. only:: esp32p4 + + LP I2S on {IDF_TARGET_NAME} only supports working as an I2S Slave. + +The LP I2S module on {IDF_TARGET_NAME} provides an independent RX unit, which supports receiving data when the chip is running with the lowest power consumption. Compared to HP I2S, LP I2S does not support DMA access. Instead, it uses a piece of separate internal memory to store data. + + +I2S Communication Mode +---------------------- + +Standard Mode +^^^^^^^^^^^^^ + +In standard mode, there are always two sound channels, i.e., the left and right channels, which are called "slots". These slots support 16-bit-width sample data. The communication format for the slots mainly includes the following: + +- **Philips Format**: Data signal has one-bit shift comparing to the WS signal, and the duty of WS signal is 50%. + +.. wavedrom:: /../_static/diagrams/i2s/std_philips.json + +- **MSB Format**: Basically the same as Philips format, but without data shift. + +.. wavedrom:: /../_static/diagrams/i2s/std_msb.json + +- **PCM Short Format**: Data has one-bit shift and meanwhile the WS signal becomes a pulse lasting for one BCLK cycle. + +.. wavedrom:: /../_static/diagrams/i2s/std_pcm.json + +PDM Mode (RX) +^^^^^^^^^^^^^ + +PDM (Pulse-density Modulation) mode for RX channel can receive PDM-format data. Only 16-bit-width sample data are supported. + + +Functional Overview +------------------- + +Resource Allocation +^^^^^^^^^^^^^^^^^^^ + +To create a LP I2S channel handle, you should set up the LP I2S channel configuration structure :cpp:type:`lp_i2s_chan_config_t`, and call :cpp:func:`lp_i2s_new_channel` with the prepared configuration structure. + +If the LP I2S channel is no longer used, you should recycle the allocated resource by calling :cpp:func:`lp_i2s_del_channel`. + +.. code:: c + + //initialization + lp_i2s_chan_handle_t rx_handle = NULL; + lp_i2s_chan_config_t config = { + .id = 0, + .role = I2S_ROLE_SLAVE, + .threshold = 512, + }; + ESP_ERROR_CHECK(lp_i2s_new_channel(&config, NULL, &rx_handle)); + + //deinitialization + ESP_ERROR_CHECK(lp_i2s_del_channel(rx_chan)); + + +Register Event Callbacks +^^^^^^^^^^^^^^^^^^^^^^^^ + +By calling :cpp:func:`lp_i2s_register_event_callbacks`, you can hook your own function to the driver ISR. Supported event callbacks are listed in :cpp:type:`lp_i2s_evt_cbs_t`. + +As the above callbacks are called in an ISR context, you should always ensure the callback function is suitable for an ISR context. Blocking logic should not appear in these callbacks. The callback function prototype is declared in :cpp:type:`lp_i2s_callback_t`. + +You can also register your own context when calling :cpp:func:`lp_i2s_register_event_callbacks` by the parameter ``user_data``. This user data will be passed to the callback functions directly. + +This function may fail due to reasons like :c:macro:`ESP_ERR_INVALID_ARG`, especially, this error may indicate that the callback functions are not in the internal RAM. Callbacks should be placed in IRAM since the default ISR handler is allocated with the `ESP_INTR_FLAG_IRAM` flag. + +Please check the error log for more details. If it fails due to :c:macro:`ESP_ERR_INVALID_STATE`, it indicates that the LP I2S channel is enabled, and you cannot add a callback at this moment. + +.. code:: c + + lp_i2s_evt_cbs_t cbs = { + .on_thresh_met = s_lp_i2s_on_thresh_met, + .on_request_new_trans = s_lp_i2s_on_request_new_trans, + }; + ESP_ERROR_CHECK(lp_i2s_register_event_callbacks(rx_chan, &cbs, &trans)); + +Enable and Disable LP I2S +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before using LP I2S to receive data, you need to enable the LP I2S channel by calling :cpp:func:`lp_i2s_channel_enable`, this function switches the driver state from **init** to **enable**. Calling :cpp:func:`lp_i2s_channel_disable` does the opposite, that is, puts the driver back to the **init** state. + +Communication Mode +^^^^^^^^^^^^^^^^^^ + +.. list:: + + - Calling :cpp:func:`lp_i2s_channel_init_std_mode` can help you initialize the LP I2S channel to STD mode. Some initialization helpers are listed below: + - :c:macro:`LP_I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG` + - :c:macro:`LP_I2S_STD_MSB_SLOT_DEFAULT_CONFIG` + - :c:macro:`LP_I2S_STD_PCM_SHORT_SLOT_DEFAULT_CONFIG` + + - Calling :cpp:func:`lp_i2s_channel_init_pdm_rx_mode` can help you initialize the LP I2S channel to PDM mode. :c:macro:`LP_I2S_PDM_RX_SLOT_DEFAULT_CONFIG` is an initialization helper. + +Read Data via LP I2S +^^^^^^^^^^^^^^^^^^^^ + +After the LP I2S channel is enabled, :cpp:func:`lp_i2s_channel_read` and :cpp:func:`lp_i2s_channel_read_until_bytes` will be available. + +.. list:: + + - For :cpp:func:`lp_i2s_channel_read`, if there are new data received by the LP I2S channel, this API will move the received data to the ``buffer`` you specified in :cpp:type:`lp_i2s_trans_t`. The API will try to receive the data as the ``buflen`` you specified. Check the ``received_size`` to know how many bytes you received, in case there are no enough received data. If no new received data, the API will block until ``timeout_ms``. + + - For :cpp:func:`lp_i2s_channel_read_until_bytes`, this API is a wrapper of the :cpp:func:`lp_i2s_channel_read`. The difference is, the :cpp:func:`lp_i2s_channel_read_until_bytes` will block until ``buflen`` bytes are received. + + - For both of the two APIs, if :cpp:member:`lp_i2s_evt_cbs_t::on_request_new_trans` is set, the driver will each time requesting a new LP I2S transaction descriptor (:cpp:type:`lp_i2s_trans_t`) from the callback event data structure (:cpp:type:`lp_i2s_evt_data_t`). This also means, the ``buffer`` in the (:cpp:type:`lp_i2s_trans_t`) needs to be ready for receiving data. + + +Thread Safety +^^^^^^^^^^^^^ + +All the APIs are guaranteed to be thread safe by the driver, which means, you can call them from different RTOS tasks without protection by extra locks. + +All the APIs are not allowed to be used in ISR context. + + +API Reference +------------- + +.. include-build-file:: inc/lp_i2s.inc +.. include-build-file:: inc/lp_i2s_std.inc +.. include-build-file:: inc/lp_i2s_pdm.inc +.. include-build-file:: inc/components/esp_driver_i2s/include/driver/i2s_types.inc From 37d8e97a9d8525303c98489cbb60fb748d59b638 Mon Sep 17 00:00:00 2001 From: Armando Date: Fri, 8 Nov 2024 12:26:05 +0800 Subject: [PATCH 3/6] doc(lp_vad): lp vad programming guide --- .../include/driver/lp_i2s_vad.h | 10 +- .../include/ulp_lp_core_lp_vad_shared.h | 2 - .../diagrams/vad/vad_state_machine.png | Bin 0 -> 52656 bytes docs/conf_common.py | 6 + docs/doxygen/Doxyfile | 3 - docs/doxygen/Doxyfile_esp32p4 | 5 + docs/en/api-reference/peripherals/index.rst | 1 + docs/en/api-reference/peripherals/lp_i2s.rst | 19 +- docs/en/api-reference/peripherals/vad.rst | 181 ++++++++++++++++++ .../zh_CN/api-reference/peripherals/index.rst | 2 + .../api-reference/peripherals/lp_i2s.rst | 1 + docs/zh_CN/api-reference/peripherals/vad.rst | 1 + 12 files changed, 206 insertions(+), 25 deletions(-) create mode 100644 docs/_static/diagrams/vad/vad_state_machine.png create mode 100644 docs/en/api-reference/peripherals/vad.rst create mode 100644 docs/zh_CN/api-reference/peripherals/lp_i2s.rst create mode 100644 docs/zh_CN/api-reference/peripherals/vad.rst diff --git a/components/esp_driver_i2s/include/driver/lp_i2s_vad.h b/components/esp_driver_i2s/include/driver/lp_i2s_vad.h index ce52370cde..a11f19782b 100644 --- a/components/esp_driver_i2s/include/driver/lp_i2s_vad.h +++ b/components/esp_driver_i2s/include/driver/lp_i2s_vad.h @@ -78,8 +78,9 @@ typedef struct vad_unit_ctx_t *vad_unit_handle_t; typedef struct { int init_frame_num; /**< Number of init frames that are used for VAD to denoise, this helps the VAD to decrease the accidental trigger ratio. Note too big values may lead to voice activity miss */ - int min_energy_thresh; ///< Min energy threshold. - bool skip_band_energy_thresh; ///< Skip band energy threshold or not + int min_energy_thresh; ///< Minimum energy threshold, voice activities with energy higher than this value will be detected. + bool skip_band_energy_thresh; /**< Skip band energy threshold or not, the passband energy check determines whether the proportion of passband energy within the total frequency domain meets the required threshold. + Note in different environments, enabling the passband energy check may reduce false trigger rates but could also increase the rate of missed detections. */ int speak_activity_thresh; /**< When in speak-activity-listening-state, if number of the detected speak activity is higher than this value, VAD runs into speak-activity-detected-state */ @@ -93,6 +94,9 @@ typedef struct { int max_speak_activity_thresh; /**< When in speak-activity-detected-state, if the number of the detected speak activity is higher than this value, VAD runs into speak-activity-listening-state */ } lp_vad_config_t; +/** + * @brief LP VAD Init Configurations + */ typedef struct { lp_i2s_chan_handle_t lp_i2s_chan; ///< LP I2S channel handle lp_vad_config_t vad_config; ///< LP VAD config @@ -115,7 +119,6 @@ esp_err_t lp_i2s_vad_new_unit(lp_vad_t vad_id, const lp_vad_init_config_t *init_ * @brief Enable LP VAD * * @param[in] unit VAD handle - * @param[in] init_config Initial configurations * * @return * - ESP_OK: On success @@ -128,7 +131,6 @@ esp_err_t lp_i2s_vad_enable(vad_unit_handle_t unit); * @brief Disable LP VAD * * @param[in] unit VAD handle - * @param[in] init_config Initial configurations * * @return * - ESP_OK: On success diff --git a/components/ulp/lp_core/shared/include/ulp_lp_core_lp_vad_shared.h b/components/ulp/lp_core/shared/include/ulp_lp_core_lp_vad_shared.h index 8a37dee54d..979398eab6 100644 --- a/components/ulp/lp_core/shared/include/ulp_lp_core_lp_vad_shared.h +++ b/components/ulp/lp_core/shared/include/ulp_lp_core_lp_vad_shared.h @@ -82,7 +82,6 @@ esp_err_t lp_core_lp_vad_init(lp_vad_t vad_id, const lp_core_lp_vad_cfg_t *init_ * @brief Enable LP VAD * * @param[in] vad_id VAD ID - * @param[in] init_config Initial configurations * * @return * - ESP_OK: On success @@ -95,7 +94,6 @@ esp_err_t lp_core_lp_vad_enable(lp_vad_t vad_id); * @brief Disable LP VAD * * @param[in] vad_id VAD ID - * @param[in] init_config Initial configurations * * @return * - ESP_OK: On success diff --git a/docs/_static/diagrams/vad/vad_state_machine.png b/docs/_static/diagrams/vad/vad_state_machine.png new file mode 100644 index 0000000000000000000000000000000000000000..7677ec07a4d98558176f36ed5eebf98c8a57fd21 GIT binary patch literal 52656 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. + + +Hardware State Machine +---------------------- + +LP VAD driver provides a structure :cpp:type:`lp_vad_config_t` to configure the LP VAD module: + +- :cpp:member:`lp_vad_config_t::init_frame_num`, number of init frames that are used for VAD to denoise, this helps the VAD to decrease the accidental trigger ratio. Note too big values may lead to voice activity miss. +- :cpp:member:`lp_vad_config_t::min_energy_thresh`, minimum energy threshold, voice activities with energy higher than this value will be detected. +- :cpp:member:`lp_vad_config_t::skip_band_energy_thresh`, skip band energy threshold or not, the passband energy check determines whether the proportion of passband energy within the total frequency domain meets the required threshold. Note in different environments, enabling the passband energy check may reduce false trigger rates but could also increase the rate of missed detections. +- :cpp:member:`lp_vad_config_t::speak_activity_thresh`, when in speak-activity-listening-state, if number of the detected speak activity is higher than this value, VAD runs into speak-activity-detected-state. +- :cpp:member:`lp_vad_config_t::non_speak_activity_thresh`, when in speak-activity-detected-state, if the number of the detected speak activity is higher than this value, but lower than :cpp:member:`lp_vad_config_t::max_speak_activity_thresh`, + * if the number of the detected non-speak activity is higher than this value, VAD runs into speak-activity-listening-state + * if the number of the detected non-speak activity is lower than this value, VAD keeps in speak-activity-detected-state +- :cpp:member:`lp_vad_config_t::min_speak_activity_thresh`, when in speak-activity-detected-state, if the number of the detected speak activity is higher than this value, but lower than :cpp:member:`lp_vad_config_t::max_speak_activity_thresh`, then the VAD state machine will depends on the value of :cpp:member:`lp_vad_config_t::non_speak_activity_thresh` +- :cpp:member:`lp_vad_config_t::max_speak_activity_thresh`, when in speak-activity-detected-state, if the number of the detected speak activity is higher than this value, VAD runs into speak-activity-listening-state + +Above configurations can change the VAD state machine shown below: + +.. code-block:: text + + ┌──────────────────────────────────┐ + │ │ + ┌─────────────┤ speak-activity-listening-state │ ◄───────────────┐ + │ │ │ │ + │ └──────────────────────────────────┘ │ + │ ▲ │ + │ │ │ + │ │ │ + │ │ │ + │ │ │ + detected speak activity │ │ detected speak activity │ detected speak activity + >= │ │ >= │ >= + 'speak_activity_thresh' │ │ 'min_speak_activity_thresh' │ 'max_speak_activity_thresh' + │ │ │ + │ │ && │ + │ │ │ + │ │ detected non-speak activity │ + │ │ < │ + │ │ 'non_speak_activity_thresh' │ + │ │ │ + │ │ │ + │ │ │ + │ │ │ + │ │ │ + │ ┌───────────┴─────────────────────┐ │ + │ │ │ │ + └───────────► │ speak-activity-detected-state ├─────────────────┘ + │ │ + └─┬───────────────────────────────┘ + │ + │ ▲ + │ │ + │ │ + │ │ detected speak activity + │ │ >= + │ │ 'min_speak_activity_thresh' + │ │ + │ │ && + │ │ + │ │ detected non-speak activity + │ │ < + └─────────────────────┘ 'non_speak_activity_thresh' + + +HP Driver Functional Overview +----------------------------- + +The VAD HP driver is used for configure the LP VAD to be working under the control of the HP core. The HP core can also be woken up by the VAD when voice activity is detected. + +Resource Allocation +^^^^^^^^^^^^^^^^^^^ + +.. only:: SOC_LP_I2S_SUPPORT_VAD + + :cpp:type:`lp_vad_init_config_t` is the configuration structure that is needed to create a LP I2S VAD unit handle. To create a LP I2S VAD unit handle, you will need to first create a LP I2S channel handle. see :doc:`Low Power Inter-IC Sound <./lp_i2s>`. + + You can call :cpp:func:`lp_i2s_vad_new_unit` to create the handle. If the VAD unit is no longer used, you should recycle the allocated resource by calling :cpp:func:`lp_i2s_vad_del_unit`. + + .. code:: c + + vad_unit_handle_t vad_handle = NULL; + lp_vad_init_config_t init_config = { + .lp_i2s_chan = rx_handle, + .vad_config = { + .init_frame_num = 100, + .min_energy_thresh = 100, + .speak_activity_thresh = 10, + .non_speak_activity_thresh = 30, + .min_speak_activity_thresh = 3, + .max_speak_activity_thresh = 100, + }, + }; + ESP_ERROR_CHECK(lp_i2s_vad_new_unit(vad_id, init_config, &vad_handle)); + + ESP_ERROR_CHECK(lp_i2s_vad_del_unit(vad_handle)); + +Enable and Disable the VAD +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. only:: SOC_LP_I2S_SUPPORT_VAD + + Before using a VAD unit to detect voice activity, you need to enable the VAD unit by calling :cpp:func:`lp_i2s_vad_enable`, this function switches the driver state from **init** to **enable**, and also enables the VAD hardware. Calling :cpp:func:`lp_i2s_vad_disable` does the opposite, that is, put the driver back to the **init** state, the hardware will stop as well. + +HP Core Wake-up +^^^^^^^^^^^^^^^ + +.. only:: SOC_LP_I2S_SUPPORT_VAD + + :cpp:func:`esp_sleep_enable_vad_wakeup` can help you to set the VAD to be working as the HP core wake-up source. To make VAD work during sleep, you should let the system maintain the RTC domain and XTAL power. See code example below: + + .. code:: c + + ESP_ERROR_CHECK(esp_sleep_enable_vad_wakeup()); + + +LP Driver Functional Overview +----------------------------- + +The VAD LP driver is mainly for LP core wake-up. The VAD can be configured under HP core control, then it can wakeup the LP core when voice activities are detected. + +Resource Allocation +^^^^^^^^^^^^^^^^^^^ + +.. only:: SOC_LP_I2S_SUPPORT_VAD + + :cpp:type:`lp_core_lp_vad_cfg_t` and :cpp:func:`lp_core_lp_vad_init` are used to initialize the VAD LP driver. + + :cpp:func:`lp_core_lp_vad_deinit` is used to recycle the allocated resources. + +Enable and Disable the VAD +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. only:: SOC_LP_I2S_SUPPORT_VAD + + :cpp:func:`lp_core_lp_vad_enable` and :cpp:func:`lp_core_lp_vad_disable` are used for enabling / disabling the hardware. + +LP Core Wake-up +^^^^^^^^^^^^^^^ + +.. only:: SOC_LP_I2S_SUPPORT_VAD + + Set :c:macro:`ULP_LP_CORE_WAKEUP_SOURCE_LP_VAD` in :cpp:type:`ulp_lp_core_cfg_t` to enable the VAD to be working as the LP core wake-up source. + + .. code:: c + + static void load_and_start_lp_core_firmware(ulp_lp_core_cfg_t* cfg, const uint8_t* firmware_start, const uint8_t* firmware_end) + { + TEST_ASSERT(ulp_lp_core_load_binary(firmware_start, + (firmware_end - firmware_start)) == ESP_OK); + + TEST_ASSERT(ulp_lp_core_run(cfg) == ESP_OK); + } + + ulp_lp_core_cfg_t cfg = { + .wakeup_source = ULP_LP_CORE_WAKEUP_SOURCE_LP_VAD, + }; + load_and_start_lp_core_firmware(&cfg, lp_core_main_vad_bin_start, lp_core_main_vad_bin_end); + + +API Reference +------------- + +.. include-build-file:: inc/lp_i2s_vad.inc +.. include-build-file:: inc/ulp_lp_core_lp_vad_shared.inc diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index ea2198b57a..fb247adae0 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -40,6 +40,8 @@ :SOC_GPSPI_SUPPORTED: spi_master :SOC_GPSPI_SUPPORTED: spi_slave :SOC_SPI_SUPPORT_SLAVE_HD_VER2: spi_slave_hd + :SOC_LP_I2S_SUPPORTED: lp_i2s + :SOC_LP_VAD_SUPPORTED: vad :SOC_JPEG_CODEC_SUPPORTED: jpeg :SOC_TEMP_SENSOR_SUPPORTED: temp_sensor :SOC_TOUCH_SENSOR_SUPPORTED and not esp32p4: touch_pad diff --git a/docs/zh_CN/api-reference/peripherals/lp_i2s.rst b/docs/zh_CN/api-reference/peripherals/lp_i2s.rst new file mode 100644 index 0000000000..7bb773ad78 --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/lp_i2s.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/peripherals/lp_i2s.rst diff --git a/docs/zh_CN/api-reference/peripherals/vad.rst b/docs/zh_CN/api-reference/peripherals/vad.rst new file mode 100644 index 0000000000..bd87f08f81 --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/vad.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/peripherals/vad.rst From 22f36bea530994afe4ff7ad7626ab22475e3d381 Mon Sep 17 00:00:00 2001 From: Armando Date: Thu, 14 Nov 2024 14:24:45 +0800 Subject: [PATCH 4/6] change(vad): wakeup driver maitain necessary power domain --- components/esp_hw_support/sleep_modes.c | 21 ++++++++++++++++++- .../test_apps/vad_wakeup/README.md | 1 + .../vad_wakeup/main/test_vad_wakeup.c | 2 -- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/components/esp_hw_support/sleep_modes.c b/components/esp_hw_support/sleep_modes.c index 71d873069f..935fdd4f91 100644 --- a/components/esp_hw_support/sleep_modes.c +++ b/components/esp_hw_support/sleep_modes.c @@ -1669,8 +1669,27 @@ esp_err_t esp_sleep_enable_timer_wakeup(uint64_t time_in_us) #if SOC_LP_VAD_SUPPORTED esp_err_t esp_sleep_enable_vad_wakeup(void) { + esp_err_t ret = ESP_FAIL; + + ret = esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON); + if (ret != ESP_OK) { + ESP_LOGE(TAG, "fail to keep rtc periph power on"); + return ret; + } + + ret = esp_sleep_pd_config(ESP_PD_DOMAIN_XTAL, ESP_PD_OPTION_ON); + if (ret != ESP_OK) { + ESP_LOGE(TAG, "fail to keep xtal power on"); + return ret; + } + ret = esp_sleep_sub_mode_config(ESP_SLEEP_LP_USE_XTAL_MODE, true); + if (ret != ESP_OK) { + ESP_LOGE(TAG, "fail to set to ESP_SLEEP_LP_USE_XTAL_MODE mode"); + return ret; + } s_config.wakeup_triggers |= RTC_LP_VAD_TRIG_EN; - return esp_sleep_sub_mode_config(ESP_SLEEP_LP_USE_XTAL_MODE, true); + + return ESP_OK; } #endif diff --git a/components/esp_hw_support/test_apps/vad_wakeup/README.md b/components/esp_hw_support/test_apps/vad_wakeup/README.md index f8ea707124..49827b24fa 100644 --- a/components/esp_hw_support/test_apps/vad_wakeup/README.md +++ b/components/esp_hw_support/test_apps/vad_wakeup/README.md @@ -1,3 +1,4 @@ | Supported Targets | ESP32-P4 | | ----------------- | -------- | +Slave side (LP I2S) should use default (UART0) console, as the USJ isn't working well under sleep modes. \ No newline at end of file diff --git a/components/esp_hw_support/test_apps/vad_wakeup/main/test_vad_wakeup.c b/components/esp_hw_support/test_apps/vad_wakeup/main/test_vad_wakeup.c index 2a245bfc6f..290d9b6638 100644 --- a/components/esp_hw_support/test_apps/vad_wakeup/main/test_vad_wakeup.c +++ b/components/esp_hw_support/test_apps/vad_wakeup/main/test_vad_wakeup.c @@ -98,8 +98,6 @@ static void s_hp_i2s_config(void) static void s_lp_vad_config(void) { ESP_ERROR_CHECK(esp_sleep_enable_vad_wakeup()); - ESP_ERROR_CHECK(esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON)); - ESP_ERROR_CHECK(esp_sleep_pd_config(ESP_PD_DOMAIN_XTAL, ESP_PD_OPTION_ON)); lp_i2s_chan_handle_t rx_handle = NULL; lp_i2s_chan_config_t config = { From 6aa6883af474dfca988d309ddc554941b1748a77 Mon Sep 17 00:00:00 2001 From: Armando Date: Thu, 21 Nov 2024 10:51:39 +0800 Subject: [PATCH 5/6] change(lp_i2d): use atomic fsm check --- components/esp_driver_i2s/i2s_private.h | 3 ++- components/esp_driver_i2s/lp_i2s.c | 17 ++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/components/esp_driver_i2s/i2s_private.h b/components/esp_driver_i2s/i2s_private.h index bc2cc1f8b4..b875c08f0b 100644 --- a/components/esp_driver_i2s/i2s_private.h +++ b/components/esp_driver_i2s/i2s_private.h @@ -7,6 +7,7 @@ #pragma once #include +#include #include "freertos/FreeRTOS.h" #include "freertos/semphr.h" #include "freertos/queue.h" @@ -199,7 +200,7 @@ struct lp_i2s_channel_obj_t { i2s_comm_mode_t mode; /*!< lp i2s channel communication mode */ i2s_role_t role; /*!< lp i2s role */ i2s_dir_t dir; /*!< lp i2s channel direction */ - i2s_state_t state; /*!< lp i2s driver state. Ensuring the driver working in a correct sequence */ + _Atomic i2s_state_t state; /*!< lp i2s driver state. Ensuring the driver working in a correct sequence */ SemaphoreHandle_t semphr; /*!< lp i2s event semphr*/ lp_i2s_trans_t trans; /*!< transaction */ size_t threshold; /*!< lp i2s threshold*/ diff --git a/components/esp_driver_i2s/lp_i2s.c b/components/esp_driver_i2s/lp_i2s.c index 707e5c12c7..82284bdd46 100644 --- a/components/esp_driver_i2s/lp_i2s.c +++ b/components/esp_driver_i2s/lp_i2s.c @@ -135,8 +135,8 @@ err1: esp_err_t lp_i2s_channel_enable(lp_i2s_chan_handle_t chan) { ESP_RETURN_ON_FALSE(chan, ESP_ERR_INVALID_ARG, TAG, "invalid argument: null pointer"); - ESP_RETURN_ON_FALSE(chan->state < I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel is in enabled state already"); - + i2s_state_t expected_state = I2S_CHAN_STATE_READY; + ESP_RETURN_ON_FALSE(atomic_compare_exchange_strong(&(chan->state), &expected_state, I2S_CHAN_STATE_RUNNING), ESP_ERR_INVALID_STATE, TAG, "the channel isn't enabled"); lp_i2s_evt_data_t evt_data = {}; if (chan->cbs.on_request_new_trans) { chan->cbs.on_request_new_trans(chan, &evt_data, chan->user_data); @@ -146,7 +146,6 @@ esp_err_t lp_i2s_channel_enable(lp_i2s_chan_handle_t chan) chan->trans = evt_data.trans; } - chan->state = I2S_CHAN_STATE_RUNNING; portENTER_CRITICAL(&g_i2s.spinlock); lp_i2s_ll_rx_enable_interrupt(chan->ctlr->hal.dev, LP_I2S_LL_EVENT_RX_MEM_THRESHOLD_INT, true); lp_i2s_ll_rx_start(chan->ctlr->hal.dev); @@ -158,7 +157,7 @@ esp_err_t lp_i2s_channel_enable(lp_i2s_chan_handle_t chan) esp_err_t lp_i2s_channel_read(lp_i2s_chan_handle_t chan, lp_i2s_trans_t *trans, uint32_t timeout_ms) { ESP_RETURN_ON_FALSE(chan, ESP_ERR_INVALID_ARG, TAG, "invalid argument: null pointer"); - ESP_RETURN_ON_FALSE(chan->state == I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel isn't enabled"); + ESP_RETURN_ON_FALSE(atomic_load(&(chan->state)) == I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel can't be deleted unless it is disabled"); ESP_RETURN_ON_FALSE(!chan->cbs.on_request_new_trans, ESP_ERR_INVALID_STATE, TAG, "on_request_new_trans registered, no use of this read API"); TickType_t ticks_to_wait = timeout_ms / portTICK_PERIOD_MS; @@ -207,8 +206,8 @@ esp_err_t lp_i2s_channel_read_until_bytes(lp_i2s_chan_handle_t chan, lp_i2s_tran esp_err_t lp_i2s_channel_disable(lp_i2s_chan_handle_t chan) { ESP_RETURN_ON_FALSE(chan, ESP_ERR_INVALID_ARG, TAG, "invalid argument: null pointer"); - ESP_RETURN_ON_FALSE(chan->state > I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, TAG, "the channel is disabled already"); - chan->state = I2S_CHAN_STATE_READY; + i2s_state_t expected_state = I2S_CHAN_STATE_RUNNING; + ESP_RETURN_ON_FALSE(atomic_compare_exchange_strong(&(chan->state), &expected_state, I2S_CHAN_STATE_READY), ESP_ERR_INVALID_STATE, TAG, "the channel isn't enabled"); portENTER_CRITICAL(&g_i2s.spinlock); lp_i2s_ll_rx_enable_interrupt(chan->ctlr->hal.dev, LP_I2S_LL_EVENT_RX_MEM_THRESHOLD_INT, false); @@ -221,7 +220,7 @@ esp_err_t lp_i2s_channel_disable(lp_i2s_chan_handle_t chan) esp_err_t lp_i2s_del_channel(lp_i2s_chan_handle_t chan) { ESP_RETURN_ON_FALSE(chan, ESP_ERR_INVALID_ARG, TAG, "invalid argument: null pointer"); - ESP_RETURN_ON_FALSE(chan->state < I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel can't be deleted unless it is disabled"); + ESP_RETURN_ON_FALSE(atomic_load(&(chan->state)) == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, TAG, "the channel can't be deleted unless it is disabled"); int id = chan->ctlr->id; portENTER_CRITICAL(&g_i2s.spinlock); @@ -249,7 +248,7 @@ _Static_assert(sizeof(lp_i2s_evt_cbs_t) == sizeof(lp_i2s_evt_cbs_internal_t), "I esp_err_t lp_i2s_register_event_callbacks(lp_i2s_chan_handle_t chan, const lp_i2s_evt_cbs_t *cbs, void *user_data) { ESP_RETURN_ON_FALSE(chan && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); - ESP_RETURN_ON_FALSE(chan->state < I2S_CHAN_STATE_RUNNING, ESP_ERR_INVALID_STATE, TAG, "the channel is in enabled state already"); + ESP_RETURN_ON_FALSE(atomic_load(&(chan->state)) == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, TAG, "the channel is in enabled state already"); if (cbs->on_thresh_met) { ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_thresh_met), ESP_ERR_INVALID_ARG, TAG, "on_thresh_met callback not in IRAM"); @@ -287,7 +286,7 @@ static esp_err_t s_i2s_register_channel(lp_i2s_controller_t *ctlr, i2s_dir_t dir new_chan->mode = I2S_COMM_MODE_NONE; new_chan->role = I2S_ROLE_MASTER; new_chan->dir = dir; - new_chan->state = I2S_CHAN_STATE_REGISTER; + atomic_init(&(new_chan->state), I2S_CHAN_STATE_READY); new_chan->ctlr = ctlr; if (dir == I2S_DIR_RX) { From 4207ec8b3b915db26da82f4c58507c8def0ae2b9 Mon Sep 17 00:00:00 2001 From: Armando Date: Thu, 21 Nov 2024 18:27:11 +0800 Subject: [PATCH 6/6] doc(vad): remove vad png --- docs/_static/diagrams/vad/vad_state_machine.png | Bin 52656 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/_static/diagrams/vad/vad_state_machine.png diff --git a/docs/_static/diagrams/vad/vad_state_machine.png b/docs/_static/diagrams/vad/vad_state_machine.png deleted file mode 100644 index 7677ec07a4d98558176f36ed5eebf98c8a57fd21..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 52656 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