Merge branch 'doc/gptimer_include_etm_contents_conditionally' into 'master'

docs(gptimer): include etm content conditionally

Closes DOC-8437

See merge request espressif/esp-idf!32442

components/esp_driver_gptimer/include/driver/gptimer.h

@@ -117,7 +117,8 @@ esp_err_t gptimer_get_resolution(gptimer_handle_t timer, uint32_t *out_resolutio
 /**
  * @brief Get GPTimer captured count value
  *
- * @note The capture action can be issued either by ETM event or by software (see also `gptimer_get_raw_count`).
+ * @note Different from `gptimer_get_raw_count`, this function won't trigger a software capture event. It just returns the last captured count value.
+ *       It's especially useful when the capture has already been triggered by an external event and you want to read the captured value.
  * @note This function is allowed to run within ISR context
  * @note If `CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` is enabled, this function will be placed in the IRAM by linker,
  *       makes it possible to execute even when the Flash Cache is disabled.

components/esp_driver_gptimer/include/driver/gptimer_etm.h

@@ -9,11 +9,14 @@
 #include "esp_err.h"
 #include "esp_etm.h"
 #include "driver/gptimer_types.h"
+#include "soc/soc_caps.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if SOC_TIMER_SUPPORT_ETM
+
 /**
  * @brief GPTimer ETM event configuration
  */
@@ -58,6 +61,7 @@ typedef struct {
  */
 esp_err_t gptimer_new_etm_task(gptimer_handle_t timer, const gptimer_etm_task_config_t *config, esp_etm_task_handle_t *out_task);
 
+#endif // SOC_TIMER_SUPPORT_ETM
 #ifdef __cplusplus
 }
 #endif

components/hal/include/hal/timer_types.h

@@ -34,6 +34,7 @@ typedef enum {
     GPTIMER_COUNT_UP,   /*!< Increase count value */
 } gptimer_count_direction_t;
 
+#if SOC_TIMER_SUPPORT_ETM
 /**
  * @brief GPTimer specific tasks that supported by the ETM module
  */
@@ -53,6 +54,7 @@ typedef enum {
     GPTIMER_ETM_EVENT_ALARM_MATCH, /*!< Count value matches the alarm target value */
     GPTIMER_ETM_EVENT_MAX,         /*!< Maximum number of events */
 } gptimer_etm_event_type_t;
+#endif // SOC_TIMER_SUPPORT_ETM
 
 #ifdef __cplusplus
 }

docs/en/api-reference/peripherals/gptimer.rst

@@ -25,7 +25,7 @@ The following sections of this document cover the typical steps to install and o
     - :ref:`gptimer-register-event-callbacks` - covers how to hook user specific code to the alarm event callback function.
     - :ref:`enable-and-disable-timer` - covers how to enable and disable the timer.
     - :ref:`start-and-stop-timer` - shows some typical use cases that start the timer with different alarm behavior.
-    :SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - describes what the events and tasks can be connected to the ETM channel.
+    :SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - describes what the events and tasks can be connected to the ETM channel.
     - :ref:`gptimer-power-management` - describes how different source clock selections can affect power consumption.
     - :ref:`gptimer-iram-safe` - describes tips on how to make the timer interrupt and IO control functions work better along with a disabled cache.
     - :ref:`gptimer-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
@@ -261,7 +261,7 @@ Alarm value can be updated dynamically inside the ISR handler callback, by chang
     ESP_ERROR_CHECK(gptimer_start(gptimer, &alarm_config));
 
 
-.. only:: SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM
+.. only:: SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-etm-event-and-task:
 
@@ -274,7 +274,7 @@ Alarm value can be updated dynamically inside the ISR handler callback, by chang
 
     .. _gptimer-power-management:
 
-.. only:: not SOC_ETM_SUPPORTED or not SOC_TIMER_SUPPORT_ETM
+.. only:: not SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-power-management:
 
@@ -348,10 +348,13 @@ API Reference
 -------------
 
 .. include-build-file:: inc/gptimer.inc
-.. include-build-file:: inc/gptimer_etm.inc
 .. include-build-file:: inc/gptimer_types.inc
 .. include-build-file:: inc/timer_types.inc
 
+.. only:: SOC_TIMER_SUPPORT_ETM
+
+    .. include-build-file:: inc/gptimer_etm.inc
+
 .. [1]
    Different ESP chip series might have different numbers of GPTimer instances. For more details, please refer to **{IDF_TARGET_NAME} Technical Reference Manual** > Chapter **Timer Group (TIMG)** [`PDF <{IDF_TARGET_TRM_EN_URL}#timg>`__]. The driver does forbid you from applying for more timers, but it returns error when all available hardware resources are used up. Please always check the return value when doing resource allocation (e.g., :cpp:func:`gptimer_new_timer`).
 

docs/zh_CN/api-reference/peripherals/gptimer.rst

@@ -25,7 +25,7 @@
     - :ref:`gptimer-register-event-callbacks` - 如何将用户的特定代码挂载到警报事件回调函数。
     - :ref:`enable-and-disable-timer` - 如何使能和禁用定时器。
     - :ref:`start-and-stop-timer` - 通过不同报警行为启动定时器的典型使用场景。
-    :SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - 定时器提供了哪些事件和任务可以连接到 ETM 通道上。
+    :SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - 定时器提供了哪些事件和任务可以连接到 ETM 通道上。
     - :ref:`gptimer-power-management` - 选择不同的时钟源将会如何影响功耗。
     - :ref:`gptimer-iram-safe` - 在 cache 禁用的情况下，如何更好地让定时器处理中断事务以及实现 IO 控制功能。
     - :ref:`gptimer-thread-safety` - 驱动程序保证哪些 API 线程安全。
@@ -261,7 +261,7 @@
     ESP_ERROR_CHECK(gptimer_start(gptimer, &alarm_config));
 
 
-.. only:: SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM
+.. only:: SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-etm-event-and-task:
 
@@ -274,7 +274,7 @@
 
     .. _gptimer-power-management:
 
-.. only:: not SOC_ETM_SUPPORTED or not SOC_TIMER_SUPPORT_ETM
+.. only:: not SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-power-management:
 
@@ -348,10 +348,13 @@ API 参考
 -------------------
 
 .. include-build-file:: inc/gptimer.inc
-.. include-build-file:: inc/gptimer_etm.inc
 .. include-build-file:: inc/gptimer_types.inc
 .. include-build-file:: inc/timer_types.inc
 
+.. only:: SOC_TIMER_SUPPORT_ETM
+
+    .. include-build-file:: inc/gptimer_etm.inc
+
 .. [1]
    不同 ESP 芯片系列的通用定时器实例数量可能不同。了解详细信息，请参考《{IDF_TARGET_NAME} 技术参考手册》 > 章节定时器组 (TIMG) [`PDF <{IDF_TARGET_TRM_CN_URL}#timg>`__]。驱动程序对通道申请数量不做限制，但当硬件资源用尽时，驱动程序将返回错误。在分配资源时，请务必检查返回值（例如 :cpp:func:`gptimer_new_timer`）。