alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs(temperature_sensor): Add new documents for temperature sensor ETM on ESP32C6/H2

Browse Source
This commit is contained in:
Cao Sen Miao 2024-02-29 18:31:40 +08:00
parent c6be2584a7
commit 943ebe2ca2
8 changed files with 44 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
components/esp_driver_tsens/include/driver/temperature_sensor_etm.h
View File

@ -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);

8
components/esp_driver_tsens/src/temperature_sensor.c
View File

@ -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

10
components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_etm.c
View File

@ -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 = {

2
components/esp_driver_tsens/test_apps/temperature_sensor/main/test_temperature_sensor.c
View File

@ -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++) {

2
docs/doxygen/Doxyfile
View File

@ -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 \

2
docs/en/api-reference/peripherals/etm.rst
View File

@ -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 </api-reference/peripherals/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:

21
docs/en/api-reference/peripherals/temp_sensor.rst
View File

@ -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 </api-reference/peripherals/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 </api-reference/peripherals/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

2
examples/peripherals/temperature_sensor/temp_sensor_monitor/main/temp_sensor_monitor_main.c
View File

@ -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
*/