Merge branch 'feature/esp-timer-add-api-for-expiry-time' into 'master'

esp_timer: Added esp_timer_get_period/expiry_time APIs

Closes IDF-4285

See merge request espressif/esp-idf!15835

components/esp_timer/include/esp_timer.h

@@ -211,6 +211,39 @@ int64_t esp_timer_get_next_alarm(void);
  */
 int64_t esp_timer_get_next_alarm_for_wake_up(void);
 
+/**
+ * @brief Get the period of a timer
+ *
+ * This function fetches the timeout period of a timer.
+ *
+ * @note The timeout period is the time interval with which a timer restarts after expiry. For one-shot timers, the
+ * period is 0 as there is no periodicity associated with such timers.
+ *
+ * @param timer timer handle allocated using esp_timer_create
+ * @param period memory to store the timer period value in microseconds
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if the arguments are invalid
+ */
+esp_err_t esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period);
+
+/**
+ * @brief Get the expiry time of a one-shot timer
+ *
+ * This function fetches the expiry time of a one-shot timer.
+ *
+ * @note This API returns a valid expiry time only for a one-shot timer. It returns an error if the timer handle passed
+ * to the function is for a periodic timer.
+ *
+ * @param timer timer handle allocated using esp_timer_create
+ * @param expiry memory to store the timeout value in microseconds
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if the arguments are invalid
+ *      - ESP_ERR_NOT_SUPPORTED if the timer type is periodic
+ */
+esp_err_t esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry);
+
 /**
  * @brief Dump the list of timers to a stream
  *

components/esp_timer/src/esp_timer.c

@@ -623,6 +623,41 @@ int64_t IRAM_ATTR esp_timer_get_next_alarm_for_wake_up(void)
     return next_alarm;
 }
 
+esp_err_t IRAM_ATTR esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period)
+{
+    if (timer == NULL || period == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    esp_timer_dispatch_t dispatch_method = timer->flags & FL_ISR_DISPATCH_METHOD;
+
+    timer_list_lock(dispatch_method);
+    *period = timer->period;
+    timer_list_unlock(dispatch_method);
+
+    return ESP_OK;
+}
+
+esp_err_t IRAM_ATTR esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry)
+{
+    if (timer == NULL || expiry == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    if (timer->period > 0) {
+        /* Return error for periodic timers */
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    esp_timer_dispatch_t dispatch_method = timer->flags & FL_ISR_DISPATCH_METHOD;
+
+    timer_list_lock(dispatch_method);
+    *expiry = timer->alarm;
+    timer_list_unlock(dispatch_method);
+
+    return ESP_OK;
+}
+
 bool esp_timer_is_active(esp_timer_handle_t timer)
 {
     return timer_armed(timer);