driver: add doc on how to unregister event callbacks

Closes https://github.com/espressif/esp-idf/pull/9523

components/driver/gptimer.c

@@ -245,7 +245,6 @@ esp_err_t gptimer_register_event_callbacks(gptimer_handle_t timer, const gptimer
 {
     gptimer_group_t *group = NULL;
     ESP_RETURN_ON_FALSE(timer && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
-    ESP_RETURN_ON_FALSE(timer->fsm == GPTIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state");
     group = timer->group;
     int group_id = group->group_id;
     int timer_id = timer->timer_id;
@@ -261,6 +260,7 @@ esp_err_t gptimer_register_event_callbacks(gptimer_handle_t timer, const gptimer
 
     // lazy install interrupt service
     if (!timer->intr) {
+        ESP_RETURN_ON_FALSE(timer->fsm == GPTIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state");
         // if user wants to control the interrupt allocation more precisely, we can expose more flags in `gptimer_config_t`
         int isr_flags = timer->flags.intr_shared ? ESP_INTR_FLAG_SHARED | GPTIMER_INTR_ALLOC_FLAGS : GPTIMER_INTR_ALLOC_FLAGS;
         ESP_RETURN_ON_ERROR(esp_intr_alloc_intrstatus(timer_group_periph_signals.groups[group_id].timer_irq_id[timer_id], isr_flags,

components/driver/include/driver/gptimer.h

@@ -138,7 +138,8 @@ esp_err_t gptimer_get_raw_count(gptimer_handle_t timer, uint64_t *value);
  * @brief Set callbacks for GPTimer
  *
  * @note User registered callbacks are expected to be runnable within ISR context
- * @note This function should be called when the timer is in the init state (i.e. before calling `gptimer_enable()`)
+ * @note The first call to this function needs to be before the call to `gptimer_enable`
+ * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
  *
  * @param[in] timer Timer handle created by `gptimer_new_timer()`
  * @param[in] cbs Group of callback functions

components/driver/include/driver/mcpwm_cap.h

@@ -168,6 +168,8 @@ typedef struct {
 /**
  * @brief Set event callbacks for MCPWM capture channel
  *
+ * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
+ *
  * @param[in] cap_channel MCPWM capture channel handle, allocated by `mcpwm_new_capture_channel()`
  * @param[in] cbs Group of callback functions
  * @param[in] user_data User data, which will be passed to callback functions directly

components/driver/include/driver/mcpwm_cmpr.h

@@ -63,6 +63,8 @@ typedef struct {
 /**
  * @brief Set event callbacks for MCPWM comparator
  *
+ * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
+ *
  * @param[in] cmpr MCPWM comparator handle, allocated by `mcpwm_new_comparator()`
  * @param[in] cbs Group of callback functions
  * @param[in] user_data User data, which will be passed to callback functions directly

components/driver/include/driver/mcpwm_fault.h

@@ -97,6 +97,8 @@ typedef struct {
 /**
  * @brief Set event callbacks for MCPWM fault
  *
+ * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
+ *
  * @param[in] fault MCPWM GPIO fault handle, allocated by `mcpwm_new_gpio_fault()`
  * @param[in] cbs Group of callback functions
  * @param[in] user_data User data, which will be passed to callback functions directly

components/driver/include/driver/mcpwm_oper.h

@@ -119,6 +119,8 @@ typedef struct {
 /**
  * @brief Set event callbacks for MCPWM operator
  *
+ * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
+ *
  * @param[in] oper MCPWM operator handle, allocated by `mcpwm_new_operator()`
  * @param[in] cbs Group of callback functions
  * @param[in] user_data User data, which will be passed to callback functions directly

components/driver/include/driver/mcpwm_timer.h

@@ -107,6 +107,9 @@ esp_err_t mcpwm_timer_start_stop(mcpwm_timer_handle_t timer, mcpwm_timer_start_s
 /**
  * @brief Set event callbacks for MCPWM timer
  *
+ * @note The first call to this function needs to be before the call to `mcpwm_timer_enable`
+ * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
+ *
  * @param[in] timer MCPWM timer handle, allocated by `mcpwm_new_timer()`
  * @param[in] cbs Group of callback functions
  * @param[in] user_data User data, which will be passed to callback functions directly

components/driver/include/driver/pulse_cnt.h

@@ -233,7 +233,8 @@ esp_err_t pcnt_unit_get_count(pcnt_unit_handle_t unit, int *value);
  * @brief Set event callbacks for PCNT unit
  *
  * @note User registered callbacks are expected to be runnable within ISR context
- * @note This function is only allowed to be called when the unit is in the init state (i.e. before calling `pcnt_unit_enable()`)
+ * @note The first call to this function needs to be before the call to `pcnt_unit_enable`
+ * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
  *
  * @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
  * @param[in] cbs Group of callback functions

components/driver/mcpwm/mcpwm_timer.c

@@ -166,7 +166,6 @@ esp_err_t mcpwm_del_timer(mcpwm_timer_handle_t timer)
 esp_err_t mcpwm_timer_register_event_callbacks(mcpwm_timer_handle_t timer, const mcpwm_timer_event_callbacks_t *cbs, void *user_data)
 {
     ESP_RETURN_ON_FALSE(timer && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
-    ESP_RETURN_ON_FALSE(timer->fsm == MCPWM_TIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state");
     mcpwm_group_t *group = timer->group;
     int group_id = group->group_id;
     int timer_id = timer->timer_id;
@@ -189,6 +188,7 @@ esp_err_t mcpwm_timer_register_event_callbacks(mcpwm_timer_handle_t timer, const
 
     // lazy install interrupt service
     if (!timer->intr) {
+        ESP_RETURN_ON_FALSE(timer->fsm == MCPWM_TIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state");
         int isr_flags = MCPWM_INTR_ALLOC_FLAG;
         ESP_RETURN_ON_ERROR(esp_intr_alloc_intrstatus(mcpwm_periph_signals.groups[group_id].irq_id, isr_flags,
                             (uint32_t)mcpwm_ll_intr_get_status_reg(hal->dev), MCPWM_LL_EVENT_TIMER_MASK(timer_id),

components/driver/pulse_cnt.c

@@ -366,7 +366,6 @@ esp_err_t pcnt_unit_register_event_callbacks(pcnt_unit_handle_t unit, const pcnt
 {
     ESP_RETURN_ON_FALSE(unit && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
     // unit event callbacks should be registered in init state
-    ESP_RETURN_ON_FALSE(unit->fsm == PCNT_UNIT_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "unit not in init state");
     pcnt_group_t *group = unit->group;
     int group_id = group->group_id;
     int unit_id = unit->unit_id;
@@ -382,6 +381,7 @@ esp_err_t pcnt_unit_register_event_callbacks(pcnt_unit_handle_t unit, const pcnt
 
     // lazy install interrupt service
     if (!unit->intr) {
+        ESP_RETURN_ON_FALSE(unit->fsm == PCNT_UNIT_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "unit not in init state");
         int isr_flags = PCNT_INTR_ALLOC_FLAGS;
         ESP_RETURN_ON_ERROR(esp_intr_alloc_intrstatus(pcnt_periph_signals.groups[group_id].irq, isr_flags,
                             (uint32_t)pcnt_ll_get_intr_status_reg(group->hal.dev), PCNT_LL_UNIT_WATCH_EVENT(unit_id),