driver: timer

1. minor modifications
2. use TIMG_WDT_INT_ENA_M instead of BIT(2) in wdt.c
3. add doc/api/timer.rst

components/driver/include/driver/timer.h

@@ -255,7 +255,9 @@ esp_err_t timer_set_alarm(timer_group_t group_num, timer_idx_t timer_num, timer_
  * @param intr_type Timer interrupt type
  * @param fn Interrupt handler function.
  *        @note
- *        Note that the handler function MUST be defined with attribution of "IRAM_ATTR".
+ *        Code inside the handler function can only call functions in IRAM,  so cannot call other timer APIs.
+ *        Use direct register access to access timers from inside the ISR.
+ *
  * @param arg Parameter for handler function
  *
  * @return
@@ -296,6 +298,8 @@ esp_err_t timer_get_config(timer_group_t group_num, timer_idx_t timer_num, timer
  *
  * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  * @param en_mask Timer interrupt enable mask.
+ *        Use TIMG_T0_INT_ENA_M to enable t0 interrupt
+ *        Use TIMG_T1_INT_ENA_M to enable t1 interrupt
  *
  * @return
  *     - ESP_OK Success
@@ -307,6 +311,8 @@ esp_err_t timer_group_intr_enable(timer_group_t group_num, uint32_t en_mask);
  *
  * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  * @param disable_mask Timer interrupt disable mask.
+ *        Use TIMG_T0_INT_ENA_M to disable t0 interrupt
+ *        Use TIMG_T1_INT_ENA_M to disable t1 interrupt
  *
  * @return
  *     - ESP_OK Success

components/driver/timer.c

@@ -57,14 +57,13 @@ esp_err_t timer_get_counter_time_sec(timer_group_t group_num, timer_idx_t timer_
     TIMER_CHECK(timer_num < TIMER_MAX, TIMER_NUM_ERROR, ESP_ERR_INVALID_ARG);
     TIMER_CHECK(time != NULL, TIMER_PARAM_ADDR_ERROR, ESP_ERR_INVALID_ARG);
 
-    portENTER_CRITICAL(&timer_spinlock[group_num]);
-    TG[group_num]->hw_timer[timer_num].update = 1;
-    uint64_t timer_val = ((uint64_t) TG[group_num]->hw_timer[timer_num].cnt_high << 32)
-                | (TG[group_num]->hw_timer[timer_num].cnt_low);
+    uint64_t timer_val;
+    esp_err_t err = timer_get_counter_value(group_num, timer_num, &timer_val);
+    if (err == ESP_OK) {
         uint16_t div = TG[group_num]->hw_timer[timer_num].config.divider;
         *time = (double)timer_val * div / TIMER_BASE_CLK;
-    portEXIT_CRITICAL(&timer_spinlock[group_num]);
-    return ESP_OK;
+    }
+    return err;
 }
 
 esp_err_t timer_set_counter_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t load_val)

components/esp32/int_wdt.c

@@ -28,6 +28,7 @@
 #include "esp_freertos_hooks.h"
 #include "soc/timer_group_struct.h"
 #include "soc/timer_group_reg.h"
+#include "driver/timer.h"
 
 #include "esp_int_wdt.h"
 
@@ -85,7 +86,7 @@ void esp_int_wdt_init() {
     TIMERG1.wdt_feed=1;
     TIMERG1.wdt_wprotect=0;
     TIMERG1.int_clr_timers.wdt=1;
-    TIMERG1.int_ena.wdt=1;
+    timer_group_intr_enable(TIMER_GROUP_1, TIMG_WDT_INT_ENA_M);
     esp_register_freertos_tick_hook(tick_hook);
     ESP_INTR_DISABLE(WDT_INT_NUM);
     intr_matrix_set(xPortGetCoreID(), ETS_TG1_WDT_LEVEL_INTR_SOURCE, WDT_INT_NUM);

components/esp32/task_wdt.c

@@ -205,7 +205,7 @@ void esp_task_wdt_init() {
     intr_matrix_set(xPortGetCoreID(), ETS_TG0_WDT_LEVEL_INTR_SOURCE, ETS_T0_WDT_INUM);
     xt_set_interrupt_handler(ETS_T0_WDT_INUM, task_wdt_isr, NULL);
     TIMERG0.int_clr_timers.wdt=1;
-    timer_group_intr_enable(TIMER_GROUP_0, BIT(2));
+    timer_group_intr_enable(TIMER_GROUP_0, TIMG_WDT_INT_ENA_M);
     ESP_INTR_ENABLE(ETS_T0_WDT_INUM);
 }
 

docs/api/timer.rst

@@ -0,0 +1,73 @@
+TIMER
+========
+
+Overview
+--------
+
+ESP32 chip contains two hardware timer groups, each containing two general-purpose hardware timers. 
+
+They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-reload-capable up/down counters.
+
+
+Application Example
+-------------------
+
+64-bit hardware timer example: `examples/13_timer_group <https://github.com/espressif/esp-idf/tree/master/examples/13_timer_group>`_.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * `components/driver/timer.h <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/timer.h>`_
+
+Macros
+^^^^^^
+
+.. doxygendefine:: TIMER_BASE_CLK
+
+Type Definitions
+^^^^^^^^^^^^^^^^
+
+
+Enumerations
+^^^^^^^^^^^^
+
+.. doxygenenum:: timer_group_t
+.. doxygenenum:: timer_idx_t
+.. doxygenenum:: timer_count_dir_t
+.. doxygenenum:: timer_start_t
+.. doxygenenum:: timer_alarm_t
+.. doxygenenum:: timer_intr_mode_t
+.. doxygenenum:: timer_autoreload_t
+
+Structures
+^^^^^^^^^^
+
+.. doxygenstruct:: timer_config_t
+    :members:
+
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: timer_get_counter_value
+.. doxygenfunction:: timer_get_counter_time_sec
+.. doxygenfunction:: timer_set_counter_value
+.. doxygenfunction:: timer_start
+.. doxygenfunction:: timer_pause
+.. doxygenfunction:: timer_set_counter_mode
+.. doxygenfunction:: timer_set_auto_reload
+.. doxygenfunction:: timer_set_divider
+.. doxygenfunction:: timer_set_alarm_value
+.. doxygenfunction:: timer_get_alarm_value
+.. doxygenfunction:: timer_set_alarm
+.. doxygenfunction:: timer_isr_register
+.. doxygenfunction:: timer_init
+.. doxygenfunction:: timer_get_config
+.. doxygenfunction:: timer_group_intr_enable
+.. doxygenfunction:: timer_group_intr_disable
+.. doxygenfunction:: timer_enable_intr
+.. doxygenfunction:: timer_disable_intr
+