From 943ebe2ca2918d882493353cd983a9d09b8edf83 Mon Sep 17 00:00:00 2001 From: Cao Sen Miao Date: Thu, 29 Feb 2024 18:31:40 +0800 Subject: [PATCH] docs(temperature_sensor): Add new documents for temperature sensor ETM on ESP32C6/H2 --- .../include/driver/temperature_sensor_etm.h | 12 +++++------ .../esp_driver_tsens/src/temperature_sensor.c | 8 +++---- .../main/test_temperature_etm.c | 10 ++++++--- .../main/test_temperature_sensor.c | 2 +- docs/doxygen/Doxyfile | 2 ++ docs/en/api-reference/peripherals/etm.rst | 2 ++ .../api-reference/peripherals/temp_sensor.rst | 21 +++++++++++++++++++ .../main/temp_sensor_monitor_main.c | 2 +- 8 files changed, 44 insertions(+), 15 deletions(-) diff --git a/components/esp_driver_tsens/include/driver/temperature_sensor_etm.h b/components/esp_driver_tsens/include/driver/temperature_sensor_etm.h index 3e030375d5..34c395a22f 100644 --- a/components/esp_driver_tsens/include/driver/temperature_sensor_etm.h +++ b/components/esp_driver_tsens/include/driver/temperature_sensor_etm.h @@ -47,15 +47,15 @@ typedef struct { /** * @brief Get the ETM task for Temperature Sensor * - * @note The created ETM event object can be deleted later by calling `esp_etm_del_event` + * @note The created ETM task object can be deleted later by calling `esp_etm_del_task` * * @param[in] tsens Temperature Sensor, allocated by `temperature_sensor_install()` - * @param[in] config Temperature Sensor ETM event configuration - * @param[out] out_task Returned ETM event handle + * @param[in] config Temperature Sensor ETM task configuration + * @param[out] out_task Returned ETM task handle * @return - * - ESP_OK: Get ETM event successfully - * - ESP_ERR_INVALID_ARG: Get ETM event failed because of invalid argument - * - ESP_FAIL: Get ETM event failed because of other error + * - ESP_OK: Get ETM task successfully + * - ESP_ERR_INVALID_ARG: Get ETM task failed because of invalid argument + * - ESP_FAIL: Get ETM task failed because of other error */ esp_err_t temperature_sensor_new_etm_task(temperature_sensor_handle_t tsens, const temperature_sensor_etm_task_config_t *config, esp_etm_task_handle_t *out_task); diff --git a/components/esp_driver_tsens/src/temperature_sensor.c b/components/esp_driver_tsens/src/temperature_sensor.c index b8067bcc99..584f15e364 100644 --- a/components/esp_driver_tsens/src/temperature_sensor.c +++ b/components/esp_driver_tsens/src/temperature_sensor.c @@ -103,7 +103,7 @@ esp_err_t temperature_sensor_install(const temperature_sensor_config_t *tsens_co ESP_RETURN_ON_FALSE((s_tsens_attribute_copy == NULL), ESP_ERR_INVALID_STATE, TAG, "Already installed"); temperature_sensor_handle_t tsens = NULL; tsens = (temperature_sensor_obj_t *) heap_caps_calloc(1, sizeof(temperature_sensor_obj_t), MALLOC_CAP_DEFAULT); - ESP_GOTO_ON_FALSE(tsens != NULL, ESP_ERR_NO_MEM, err, TAG, "no mem for temp sensor"); + ESP_RETURN_ON_FALSE((tsens != NULL), ESP_ERR_NO_MEM, TAG, "no mem for temp sensor"); tsens->clk_src = tsens_config->clk_src; temperature_sensor_power_acquire(); @@ -260,7 +260,7 @@ esp_err_t temperature_sensor_set_absolute_threshold(temperature_sensor_handle_t { esp_err_t ret = ESP_OK; ESP_RETURN_ON_FALSE((tsens != NULL), ESP_ERR_INVALID_ARG, TAG, "Temperature sensor has not been installed"); - ESP_RETURN_ON_FALSE(tsens->fsm == TEMP_SENSOR_FSM_ENABLE, ESP_ERR_INVALID_STATE, TAG, "temperature sensor is not in enable state"); + ESP_RETURN_ON_FALSE(tsens->fsm == TEMP_SENSOR_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "temperature sensor is not in init state"); ESP_RETURN_ON_FALSE(abs_cfg, ESP_ERR_INVALID_ARG, TAG, "Invalid callback configuration"); temperature_sensor_ll_set_sample_rate(0xffff); @@ -275,7 +275,7 @@ esp_err_t temperature_sensor_set_delta_threshold(temperature_sensor_handle_t tse { esp_err_t ret = ESP_OK; ESP_RETURN_ON_FALSE((tsens != NULL), ESP_ERR_INVALID_ARG, TAG, "Temperature sensor has not been installed"); - ESP_RETURN_ON_FALSE(tsens->fsm == TEMP_SENSOR_FSM_ENABLE, ESP_ERR_INVALID_STATE, TAG, "temperature sensor is not in enable state"); + ESP_RETURN_ON_FALSE(tsens->fsm == TEMP_SENSOR_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "temperature sensor is not in init state"); ESP_RETURN_ON_FALSE(delta_cfg, ESP_ERR_INVALID_ARG, TAG, "Invalid callback configuration"); temperature_sensor_ll_set_sample_rate(0xffff); @@ -290,7 +290,7 @@ esp_err_t temperature_sensor_register_callbacks(temperature_sensor_handle_t tsen { esp_err_t ret = ESP_OK; ESP_RETURN_ON_FALSE((tsens != NULL), ESP_ERR_INVALID_ARG, TAG, "Temperature sensor has not been installed"); - ESP_RETURN_ON_FALSE(tsens->fsm == TEMP_SENSOR_FSM_ENABLE, ESP_ERR_INVALID_STATE, TAG, "temperature sensor is not in enable state"); + ESP_RETURN_ON_FALSE(tsens->fsm == TEMP_SENSOR_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "temperature sensor is not in init state"); ESP_RETURN_ON_FALSE(cbs, ESP_ERR_INVALID_ARG, TAG, "callback group pointer is invalid"); #if CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE diff --git a/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_etm.c b/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_etm.c index e9eb171932..d036d4ef9c 100644 --- a/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_etm.c +++ b/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_etm.c @@ -15,10 +15,14 @@ #include "driver/temperature_sensor.h" #include "soc/soc_etm_struct.h" +// To run this example, you need a facility that can make the temperature change +// on board. Like a heat gun. +// Then after the temperature meet the threshold, you can see the gpio level changes +// from 0 to 1 on logic analyzer or oscilloscope. TEST_CASE("temperature sensor alarm cause gpio pull up", "[etm]") { const uint32_t output_gpio = 5; - // temperature sensor alarm ---> ETM channel A ---> GPIO toggle + // temperature sensor alarm ---> ETM channel A ---> GPIO level to high printf("allocate etm channel\r\n"); esp_etm_channel_config_t etm_config = {}; esp_etm_channel_handle_t etm_channel_a; @@ -27,7 +31,7 @@ TEST_CASE("temperature sensor alarm cause gpio pull up", "[etm]") printf("allocate GPIO etm task\r\n"); esp_etm_task_handle_t gpio_task = NULL; gpio_etm_task_config_t gpio_task_config = { - .action = GPIO_ETM_TASK_ACTION_TOG, + .action = GPIO_ETM_TASK_ACTION_SET, }; TEST_ESP_OK(gpio_new_etm_task(&gpio_task_config, &gpio_task)); // set gpio number for the gpio etm primitives @@ -46,13 +50,13 @@ TEST_CASE("temperature sensor alarm cause gpio pull up", "[etm]") temperature_sensor_config_t temp_sensor = TEMPERATURE_SENSOR_CONFIG_DEFAULT(10, 50); temperature_sensor_handle_t temp_handle = NULL; TEST_ESP_OK(temperature_sensor_install(&temp_sensor, &temp_handle)); - TEST_ESP_OK(temperature_sensor_enable(temp_handle)); temperature_sensor_abs_threshold_config_t threshold_cfg = { .high_threshold = 50, .low_threshold = -10, }; TEST_ESP_OK(temperature_sensor_set_absolute_threshold(temp_handle, &threshold_cfg)); + TEST_ESP_OK(temperature_sensor_enable(temp_handle)); printf("Temperature sensor started\n"); temperature_sensor_etm_event_config_t tsens_etm_event = { diff --git a/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_sensor.c b/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_sensor.c index 37c1b7e81a..6bc7fe4e86 100644 --- a/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_sensor.c +++ b/components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_sensor.c @@ -110,7 +110,6 @@ TEST_CASE("Temperature sensor callback test", "[temperature_sensor]") temperature_sensor_config_t temp_sensor = TEMPERATURE_SENSOR_CONFIG_DEFAULT(10, 50); temperature_sensor_handle_t temp_handle = NULL; TEST_ESP_OK(temperature_sensor_install(&temp_sensor, &temp_handle)); - TEST_ESP_OK(temperature_sensor_enable(temp_handle)); temperature_sensor_event_callbacks_t cbs = { .on_threshold = temp_sensor_cbs_test, @@ -125,6 +124,7 @@ TEST_CASE("Temperature sensor callback test", "[temperature_sensor]") TEST_ESP_OK(temperature_sensor_set_absolute_threshold(temp_handle, &threshold_cfg)); temperature_sensor_register_callbacks(temp_handle, &cbs, &temperature_alarm); + TEST_ESP_OK(temperature_sensor_enable(temp_handle)); #if CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE printf("disable flash cache and check if we can still get temperature intr\r\n"); for (int i = 0; i < 100; i++) { diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 7476855338..278eb61808 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -143,6 +143,7 @@ INPUT = \ $(PROJECT_PATH)/components/esp_driver_spi/include/driver/spi_slave_hd.h \ $(PROJECT_PATH)/components/esp_driver_spi/include/driver/spi_slave.h \ $(PROJECT_PATH)/components/esp_driver_tsens/include/driver/temperature_sensor.h \ + $(PROJECT_PATH)/components/esp_driver_tsens/include/driver/temperature_sensor_etm.h \ $(PROJECT_PATH)/components/esp_driver_uart/include/driver/uart.h \ $(PROJECT_PATH)/components/esp_driver_uart/include/driver/uart_vfs.h \ $(PROJECT_PATH)/components/esp_eth/include/esp_eth_com.h \ @@ -251,6 +252,7 @@ INPUT = \ $(PROJECT_PATH)/components/hal/include/hal/sdm_types.h \ $(PROJECT_PATH)/components/hal/include/hal/spi_flash_types.h \ $(PROJECT_PATH)/components/hal/include/hal/spi_types.h \ + $(PROJECT_PATH)/components/hal/include/hal/temperature_sensor_types.h \ $(PROJECT_PATH)/components/hal/include/hal/timer_types.h \ $(PROJECT_PATH)/components/hal/include/hal/touch_sensor_types.h \ $(PROJECT_PATH)/components/hal/include/hal/twai_types.h \ diff --git a/docs/en/api-reference/peripherals/etm.rst b/docs/en/api-reference/peripherals/etm.rst index bca698df5d..8c9d901881 100644 --- a/docs/en/api-reference/peripherals/etm.rst +++ b/docs/en/api-reference/peripherals/etm.rst @@ -71,6 +71,7 @@ Other Peripheral Events :SOC_GDMA_SUPPORT_ETM: - Refer to :doc:`/api-reference/system/async_memcpy` for how to get the ETM event handle from async memcpy. :SOC_MCPWM_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/mcpwm` for how to get the ETM event handle from MCPWM. :SOC_ANA_CMPR_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/ana_cmpr` for how to get the ETM event handle from analog comparator. + :SOC_TEMPERATURE_SENSOR_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/temp_sensor` for how to get the ETM event handle from temperature sensor. .. _etm-task: @@ -96,6 +97,7 @@ Other Peripheral Tasks .. list:: :SOC_TIMER_SUPPORT_ETM: - Refer to :doc:`GPTimer ` for how to get the ETM task handle from GPTimer. + :SOC_TEMPERATURE_SENSOR_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/temp_sensor` for how to get the ETM task handle from temperature sensor. .. _etm-channel-control: diff --git a/docs/en/api-reference/peripherals/temp_sensor.rst b/docs/en/api-reference/peripherals/temp_sensor.rst index 13ceb154e3..5a0be3676a 100644 --- a/docs/en/api-reference/peripherals/temp_sensor.rst +++ b/docs/en/api-reference/peripherals/temp_sensor.rst @@ -46,6 +46,7 @@ The description of the temperature sensor functionality is divided into the foll - :ref:`temp-power-management` - covers how the temperature sensor is affected when changing power mode (e.g., Light-sleep mode). :SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: - :ref:`temp-iram-safe` - describes tips on how to make the temperature sensor interrupt work better along with a disabled cache. - :ref:`temp-thread-safety` - covers how to make the driver to be thread-safe. + :SOC_TEMPERATURE_SENSOR_SUPPORT_ETM: - :ref:`temperature-sensor-etm-event-and-task` - describes what the events and tasks can be connected to the ETM channel. .. _temp-resource-allocation: @@ -180,6 +181,21 @@ Thread Safety In the temperature sensor driver, we do not add any protection to ensure the thread safety, because typically this driver is only supposed to be used in one task. If you have to use this driver in different tasks, please add extra locks to protect it. +.. only:: SOC_TEMPERATURE_SENSOR_SUPPORT_ETM + + .. _temperature-sensor-etm-event-and-task: + + ETM Event and Task + ^^^^^^^^^^^^^^^^^^ + + Temperature Sensor is able to generate events that can interact with the :doc:`ETM ` module. The supported events are listed in the :cpp:type:`temperature_sensor_etm_event_type_t`. You can call :cpp:func:`temperature_sensor_new_etm_event` to get the corresponding ETM event handle. The supported tasks are listed in the :cpp:type:`temperature_sensor_etm_task_type_t`. You can call :cpp:func:`temperature_sensor_new_etm_task` to get the corresponding ETM event handle. + + .. note:: + + - :cpp:enumerator:`TEMPERATURE_SENSOR_EVENT_OVER_LIMIT` for :cpp:member:`temperature_sensor_etm_event_type_t::event_type` depends on what kind of threshold you set first. If you set the absolute threshold by :cpp:func:`temperature_sensor_set_absolute_threshold`, then the :cpp:enumerator:`TEMPERATURE_SENSOR_EVENT_OVER_LIMIT` refers to absolute threshold. Likewise, if you set the delta threshold by :cpp:func:`temperature_sensor_set_delta_threshold`, then the :cpp:enumerator:`TEMPERATURE_SENSOR_EVENT_OVER_LIMIT` refers to delta threshold. + + For how to connect the event and task to an ETM channel, please refer to the :doc:`ETM ` documentation. + Unexpected Behaviors -------------------- @@ -202,3 +218,8 @@ API Reference ---------------------------------- .. include-build-file:: inc/temperature_sensor.inc +.. include-build-file:: inc/temperature_sensor_types.inc + +.. only:: SOC_TEMPERATURE_SENSOR_SUPPORT_ETM + + .. include-build-file:: inc/temperature_sensor_etm.inc diff --git a/examples/peripherals/temperature_sensor/temp_sensor_monitor/main/temp_sensor_monitor_main.c b/examples/peripherals/temperature_sensor/temp_sensor_monitor/main/temp_sensor_monitor_main.c index 96e4e981c2..b75cd5960c 100644 --- a/examples/peripherals/temperature_sensor/temp_sensor_monitor/main/temp_sensor_monitor_main.c +++ b/examples/peripherals/temperature_sensor/temp_sensor_monitor/main/temp_sensor_monitor_main.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */